Configurazione di OCI Native Ingress Controller

Instrada richieste in base all'host

È possibile configurare il controller di entrata nativo OCI per instradare una richiesta in entrata in base al nome dominio nell'intestazione host della richiesta (l'host a cui è stata originariamente inviata la richiesta).

Per instradare una richiesta a un determinato servizio backend e a una determinata porta in base all'host, creare una regola di instradamento nel file manifesto Ingress. Se l'host corrisponde alla regola di instradamento, il controller di entrata nativo OCI instrada la richiesta al servizio backend e alla porta associati.

Ad esempio, è possibile definire la regola seguente per instradare le richieste inviate originariamente a http://foo.bar.com a un servizio backend denominato ServiceA sulla porta 80. Tutto il traffico in entrata originariamente inviato a http://foo.bar.com viene instradato a ServiceA sulla porta 80.

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /
          backend:
            serviceName: ServiceA
            servicePort: 80

Instrada le richieste a servizi backend diversi in base al percorso

Puoi configurare il controller di entrata nativo OCI per instradare le richieste in entrata a diversi servizi backend, in base agli elementi nel percorso a cui le richieste sono state originariamente inviate.

Per instradare una richiesta a un determinato servizio backend e a una determinata porta in base al percorso, creare una regola di instradamento nel file manifesto Ingress. Se il percorso corrisponde alla regola di instradamento, il controller di entrata nativo OCI instrada la richiesta al servizio backend e alla porta associati. È possibile specificare più percorsi nella stessa regola per instradare le richieste a backend diversi.

Ad esempio, è possibile definire la regola seguente per instradare le richieste in base al percorso al quale la richiesta è stata originariamente inviata:

• Se il percorso inizia con /app1, il controller di entrata nativo OCI instrada la richiesta a un servizio backend denominato ServiceA sulla porta 80.
• Se il percorso inizia con /app2, il controller di entrata nativo OCI instrada la richiesta a un servizio backend denominato ServiceB sulla porta 443.

Poiché la regola non specifica un host, la regola si applica a tutto il traffico in entrata.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443

Instrada richieste in base a host e percorso

È possibile configurare il controller di entrata nativo OCI per instradare una richiesta in entrata in base sia al nome di dominio nell'intestazione host della richiesta (l'host a cui è stata originariamente inviata la richiesta) che agli elementi nel percorso a cui è stata inviata la richiesta originale.

Per instradare una richiesta a un servizio e a una porta backend specifici in base all'host e al percorso, creare una regola di instradamento nel file manifesto Ingress. Se l'host e il percorso corrispondono alla regola di instradamento, il controller di entrata nativo OCI instrada la richiesta al servizio backend e alla porta associati.

Ad esempio, è possibile definire la regola seguente per instradare le richieste inviate originariamente a http://foo.bar.com/app1 a un servizio backend denominato foo sulla porta 80:

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: foo
            servicePort: 80

Instrada le richieste a un backend predefinito

Puoi configurare il controller di entrata nativo OCI per instradare le richieste in entrata a un backend predefinito. È possibile configurare un backend predefinito per gestire le richieste che non corrispondono ad alcuna regola di instradamento.

Ad esempio, è possibile definire il seguente defaultBackend per instradare le richieste che non corrispondono ad altre regole nel file manifesto Ingress a un servizio backend denominato ServiceC sulla porta 8080.

Tenere presente che se non si specificano altre regole in un file manifesto Ingress, è necessario specificare un valore defaultBackend.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443
  defaultBackend:
    service:
      name: ServiceC
      port:
        number: 8080

Personalizzazione del comportamento generale mediante annotazioni

È possibile aggiungere annotazioni ai file manifesto delle risorse IngressClass o Ingress per personalizzare il funzionamento generale del controller di entrata nativo OCI.

Personalizzazione del funzionamento del controllo dello stato mediante annotazioni

È possibile aggiungere annotazioni al manifesto delle risorse Ingress per personalizzare i controlli dello stato eseguiti dal load balancer creato dal controller di entrata nativo OCI. Per ulteriori informazioni sui controlli di integrità del load balancer, vedere Controlli di integrità per i load balancer.

Opzione 1: OCI Native Ingress Controller ottiene il certificato dal servizio Certificates utilizzando un segreto Kubernetes

Per configurare il controller di entrata nativo OCI per ottenere un certificato dal servizio OCI Certificates, effettuare le operazioni riportate di seguito.

1. Ottenere una coppia di chiavi pubblica e privata TLS e un certificato.

   Negli ambienti di produzione è possibile ottenere un certificato TLS dall'autorità di certificazione scelta inviando una richiesta di firma certificato. Durante il processo di richiesta del certificato vengono generate una chiave pubblica e la chiave privata corrispondente.

   Negli ambienti di sviluppo e test è possibile creare un certificato con firma automatica e generare una chiave privata utilizzando uno strumento quale OpenSSL. Ad esempio, utilizzando OpenSSL 3.0 o versioni successive:

   1. Generare una coppia di chiavi pubblica e privata immettendo i seguenti comandi:

      openssl genrsa -out rootCA.key 4096

      openssl req -x509 -addext basicConstraints=critical,CA:TRUE -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt -subj /CN=RootCA

   2. Generare un certificato immettendo i seguenti comandi:

      openssl genrsa -out server.key 4096

      openssl req -new -sha256 -key server.key -subj /C=US/ST=CA/O=MyOrg,Inc./CN=my.example.com -out server.csr

      openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256

   In questo esempio:

   • rootCA.key contiene la coppia di chiavi per la CA root.
   • rootCA.crt contiene il certificato CA root.
   • server.key contiene la coppia di chiavi per generare il certificato del server.
   • server.csr contiene la richiesta di firma del certificato per il certificato del server.
   • server.crt contiene il certificato del server generato.
2. Creare una risorsa segreta Kubernetes in uno dei seguenti modi:

   • Utilizzando il comando kubectl create secret generic, immettere:

     kubectl create secret generic <k8s-secret-name> --type=kubernetes.io/tls --from-file=ca.crt=<path-and-filename>.crt --from-file=tls.crt=<path-and-filename>.crt --from-file=tls.key=<path-and-filename>.key

     Dove:

     • <k8s-secret-name> è il nome scelto per il segreto Kubernetes
     • --from-file=ca.crt=<path-and-filename>.crt specifica il percorso del file che contiene il certificato CA radice. Ad esempio, --from-file=ca.crt=rootCA.crt
     • --from-file=tls.crt=<path-and-filename>.crt specifica il percorso del file contenente il certificato del server generato. Ad esempio, --from-file=tls.crt=server.crt
     • --from-file=tls.key=<path-and-filename>.key specifica il percorso del file che contiene la chiave privata generata. Ad esempio, --from-file=tls.key=server.key

     Ad esempio:

     kubectl create secret generic example-tls-secret --type=kubernetes.io/tls --from-file=ca.crt=rootCA.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   • Utilizzo di un file manifesto della risorsa Secret:

     1. Definire il segreto Kubernetes in un file .yaml nel formato:

        apiVersion: v1
        kind: Secret
        metadata:
          name: <k8s-secret-name>
        type: kubernetes.io/tls
        data:
          ca.crt: <base64-encoded-certificate-chain>
          tls.crt: <base64-encoded-server-certificate>
          tls.key: <base64-encoded-private-key>

        Dove:

        • name: <k8s-secret-name> è il nome scelto per la risorsa segreta Kubernetes.
        • ca.crt: <base64-encoded-certificate-chain> è il contenuto del file (o dei file) contenente i certificati intermedi che formano una catena di certificati dal certificato foglia all'autorità di certificazione. Si noti che è possibile omettere ca.cert, a condizione di includere l'intera catena di certificati come valore di tls.cert (nel qual caso, avviare la catena di certificati con il contenuto del file contenente il certificato del server generato, seguito dai certificati rimanenti).
        • tls.crt: <base64-encoded-server-certificate> è il contenuto del file contenente il certificato del server generato.
        • tls.key: <base64-encoded-private-key> è il contenuto del file contenente la chiave privata generata.

        Ad esempio:

        apiVersion: v1
        kind: Secret
        metadata:
          name: example-tls-secret
        type: kubernetes.io/tls
        data:
          ca.crt : MIIFGERTegcDFRTuSDGfghREdE______Jre
          tls.crt: MIIC2DCCAcCgAwIBAgIBATANBg______kqh
          tls.key: MIIEpgIBAAKCAQEA7yn3bRHQ5F______HMQ

     2. Creare la risorsa segreta immettendo kubectl create -f <filename>.yaml

3. Aggiungere il segreto Kubernetes in un file manifesto delle risorse Ingress:
   1. Definire una nuova risorsa in entrata in un file .yaml. Vedere Crea risorsa in entrata.
   2. Nella sezione spec: del file manifesto, aggiungere un elemento tls: che specifichi sia l'host che deve ricevere il traffico HTTPS che il nome del segreto Kubernetes, nel formato:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - <host-name>
          secretName: <k8s-secret-name>

      Ad esempio:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret

   3. Nella sezione rules: del file manifesto aggiungere una regola per l'host che riceverà il traffico HTTPS e specificare 443 come porta di ascolto del traffico HTTPS.

      Ad esempio:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-secret-ingress
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Creare la risorsa immettendo kubectl create -f <filename>.yaml

Quando crei la risorsa in entrata, il controller in entrata nativo OCI utilizza il segreto Kubernetes per ottenere un certificato di tipo Importato e un bundle CA (bundle Autorità certificati) dal servizio OCI Certificates. Il controller di entrata nativo OCI associa il certificato al listener e il bundle CA al set backend.

Quando il listener in ascolto sulla porta 443 riceve una richiesta HTTPS all'host specificato, il listener utilizza il certificato per l'arresto TLS. Il listener utilizza quindi la regola di instradamento per inoltrare la richiesta al set backend. Il set backend crea una nuova connessione TLS con i backend in esecuzione nel cluster (utilizzando il bundle CA come autorità di attendibilità per la nuova connessione).

Opzione 2: ottenere il certificato dal servizio Certificati

Per configurare il controller di entrata nativo OCI in modo che utilizzi un certificato ottenuto dal servizio OCI Certificates, effettuare le operazioni riportate di seguito.

1. Creare un certificato nel servizio OCI Certificates in uno dei modi riportati di seguito.
   • importando un certificato emesso da un'autorità di certificazione di terze parti (il certificato sarà di tipo Importato);
   • emettendo il certificato internamente da una CA del servizio Certificati (il certificato sarà di tipo Emesso dalla CA interna).

   Non creare un certificato da gestire esternamente (di tipo Emesso dalla CA interna, gestito esternamente). Per ulteriori informazioni, vedere Creazione di un certificato.

2. Prendere nota dell'OCID del certificato.
3. Aggiungere l'OCID del certificato a un file manifesto della risorsa Ingress:
   1. Definire una nuova risorsa in entrata in un file .yaml. Vedere Crea risorsa in entrata.
   2. Nella sezione metadata: aggiungere un elemento annotations: che specifichi l'OCID del certificato creato nel servizio OCI Certificates nel formato seguente:

      kind: Ingress
      metadata:
        name: <i-name>
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>
      spec:
      ...

      Dove:

      • name: <i-name> è il nome scelto per la risorsa in entrata.
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid> è l'OCID del certificato creato nel servizio OCI Certificates

      Ad esempio:

      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
      ...

   3. Nella sezione rules: del manifesto delle risorse Ingress, aggiungere una regola per l'host che deve ricevere il traffico HTTPS e specificare 443 come porta su cui ascoltare il traffico HTTPS.

      Ad esempio:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Creare la risorsa immettendo kubectl create -f <filename>.yaml

Le conseguenze della creazione della risorsa in entrata dipendono dalla modalità di creazione del certificato nel servizio OCI Certificates:

• Se il certificato è stato creato importando un certificato emesso da un'autorità di certificazione di terze parti, il certificato è di tipo Importato. Il controller di entrata nativo OCI associa il certificato al listener, crea un bundle CA dalla catena di certificati e associa il bundle CA al set backend. Tenere presente che non è possibile configurare certificati di tipo Importati per la rotazione automatica.
• Se il certificato è stato creato emettendolo internamente da una CA del servizio Certificati, tale certificato è di tipo Emesso dalla CA interna. Il controller di entrata nativo OCI associa il certificato al listener, ottiene l'OCID della CA e associa tale OCID al set backend. È possibile configurare i certificati di tipo Emessi dalla CA interna in modo che vengano ruotati automaticamente.

Quando il listener in ascolto sulla porta 443 riceve una richiesta HTTPS all'host specificato, il listener utilizza il certificato per l'arresto TLS. Il listener utilizza quindi la regola di instradamento per inoltrare la richiesta al set backend. Il set backend crea una nuova connessione TLS con i backend in esecuzione nel cluster (utilizzando il bundle CA o la CA identificata dal relativo OCID come autorità sicura per la nuova connessione).

Applicazione delle tag definite al load balancer

Le tag definite vengono impostate e gestite da un amministratore di tag. Una tag definita è composta da uno spazio di nomi tag, una chiave e un valore. Lo spazio di nomi e la definizione della chiave di tag devono essere impostati in una tenancy prima di poter applicare una tag definita a una risorsa.

Per specificare che il controller di entrata nativo OCI deve applicare le tag definite al load balancer, utilizzare l'annotazione oci-native-ingress.oraclecloud.com/defined-tags nel file manifesto IngressClass nel formato seguente:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'
spec:
  ...

Dove:

• <tag-namespace> è lo spazio di nomi tag a cui appartiene la tag.
• <tag-key> è il nome di una tag definita da applicare al load balancer.
• <tag-value> è un valore per il tag di un elenco di valori predefinito, un nuovo valore o un valore vuoto (a seconda della modalità di impostazione del tag definito).

Il valore dell'annotazione oci-native-ingress.oraclecloud.com/defined-tags è una stringa JSON che consente di specificare più spazi di nomi tag, chiavi di tag e valori di tag in formato JSON.

Ad esempio:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"Operations": {"CostCenter": "42", "Department": "001"}, "Sales": {"Region": "US"}}'
spec:
  ...

La modifica di una delle tag nell'annotazione oci-native-ingress.oraclecloud.com/defined-tags del manifesto IngressClass fa sì che il controller di entrata nativo OCI riapplichi al load balancer tutte le tag definite specificate dall'annotazione. Tuttavia, se una tag definita contiene una variabile di tag, il controller di entrata nativo OCI riapplica la tag definita al load balancer solo se la tag non è già presente.

Tenere presente che per consentire al controller in entrata nativo OCI di applicare tag definite a un load balancer, è necessario che esista un criterio IAM adatto per consentire al controller in entrata nativo OCI di utilizzare lo spazio di nomi tag appropriato. Per ulteriori informazioni, fare riferimento agli argomenti sotto riportati.

• Concessione delle autorizzazioni al controller OCI Native Ingress come programma standalone
• Concessione delle autorizzazioni al componente aggiuntivo cluster del controller di entrata nativo OCI

Applicazione di tag in formato libero al load balancer

Le tag in formato libero non sono gestite da un amministratore di tag. Una tag in formato libero è composta da una chiave e da un valore. A differenza delle tag definite, le tag in formato libero non appartengono a uno spazio di nomi tag.

Per specificare che il controller di entrata nativo OCI deve applicare tag in formato libero al load balancer, utilizzare l'annotazione oci-native-ingress.oraclecloud.com/freeform-tags nel file manifesto IngressClass nel formato seguente:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"<tag-key>": "<tag-value>"}'
spec:
  ...

Dove:

• <tag-key> è un nome per la tag in formato libero da applicare al load balancer.
• <tag-value> è un valore per la tag in formato libero da applicare al load balancer.

Il valore dell'annotazione oci-native-ingress.oraclecloud.com/freeform-tags è una stringa JSON che consente di specificare più chiavi di tag e valori di tag in formato JSON.

Ad esempio:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"Project": "Red", "Version": "Alpha"}'
spec:
  ...

La modifica di una delle tag nell'annotazione oci-native-ingress.oraclecloud.com/freeform-tags del manifesto IngressClass fa sì che il controller di entrata nativo OCI riapplichi al load balancer tutte le tag in formato libero specificate dall'annotazione.

L'applicazione della tag predefinita al load balancer

Le impostazioni predefinite delle tag sono impostate per un compartimento specifico. I valori predefiniti delle tag sono specifici del compartimento. Le impostazioni predefinite delle tag specificano le tag definite che vengono applicate automaticamente a tutte le risorse create in un compartimento specifico al momento della creazione.

Quando si utilizza il controller di entrata nativo OCI versione 1.4.0 (o successiva), i valori predefiniti delle tag vengono applicati automaticamente ai load balancer creati dal controller di entrata nativo OCI. Successivamente, il controller di entrata nativo OCI conserva un valore predefinito di tag applicato a un load balancer a meno che non venga soddisfatta una delle seguenti condizioni:

• È possibile rimuovere manualmente un valore predefinito di tag applicato automaticamente a un load balancer.
• È possibile specificare un valore predefinito di tag come tag definita utilizzando l'annotazione oci-native-ingress.oraclecloud.com/defined-tags (nel qual caso, il controller di entrata nativo OCI considera il valore predefinito di tag come qualsiasi altra tag definita).

I valori predefiniti delle tag con i valori applicati dall'utente non sono supportati. Se è stata impostata un'impostazione predefinita di tag con un valore applicato dall'utente per un compartimento in cui il controller di entrata nativo OCI deve creare o gestire un load balancer, è necessario utilizzare l'annotazione oci-native-ingress.oraclecloud.com/defined-tags per specificare l'impostazione predefinita della tag come tag definita.

Per i load balancer creati utilizzando una versione del controller di ingresso nativo OCI precedente alla versione 1.4.0 o quando si utilizza l'annotazione oci-native-ingress.oraclecloud.com/id per specificare che il controller di ingresso nativo OCI deve gestire un load balancer esistente, tenere presente che i valori predefiniti delle tag non sono supportati. In entrambi i casi, per applicare o mantenere un valore predefinito di tag, utilizzare l'annotazione oci-native-ingress.oraclecloud.com/defined-tags per specificare il valore predefinito di tag come tag definito.