Configurando o Controlador de Entrada Nativa do OCI

Solicitações de roteamento com base no host

Você pode configurar o controlador de entrada nativo do OCI para rotear uma solicitação de entrada com base no nome do domínio no cabeçalho Host da solicitação (o host para o qual a solicitação foi originalmente enviada).

Para rotear uma solicitação para um serviço de backend e uma porta específicos com base no host, crie uma regra de roteamento no manifesto Ingress. Se o host corresponder à regra de roteamento, o controlador de entrada nativo do OCI roteará a solicitação para o serviço de backend e a porta associados.

Por exemplo, você pode definir a regra a seguir para rotear solicitações enviadas originalmente para http://foo.bar.com para um serviço de backend chamado ServiceA na porta 80. Todo o tráfego de entrada enviado originalmente para http://foo.bar.com é roteado para ServiceA na porta 80.

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

Rotear solicitações para diferentes serviços de backend com base no caminho

Você pode configurar o controlador de entrada nativo do OCI para rotear solicitações de entrada para diferentes serviços de backend, com base nos elementos no caminho para o qual as solicitações foram enviadas originalmente.

Para rotear uma solicitação para um serviço de backend e uma porta específicos com base no caminho, crie uma regra de roteamento no manifesto Ingress. Se o caminho corresponder à regra de roteamento, o controlador de entrada nativo do OCI roteará a solicitação para o serviço de backend e a porta associados. Você pode especificar vários caminhos na mesma regra para rotear solicitações para diferentes backends.

Por exemplo, você pode definir a seguinte regra para rotear solicitações com base no caminho para o qual a solicitação foi originalmente enviada:

• Se o caminho começar com /app1, o controlador de entrada nativo do OCI roteará a solicitação para um serviço de backend chamado ServiceA na porta 80.
• Se o caminho começar com /app2, o controlador de entrada nativo do OCI roteará a solicitação para um serviço de backend chamado ServiceB na porta 443.

Como a regra não especifica um host, ela se aplica a todo o tráfego de entrada.

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

Solicitações de roteamento com base no host e no caminho

Você pode configurar o controlador de entrada nativo do OCI para rotear uma solicitação de entrada com base no nome do domínio no cabeçalho Host da solicitação (o host para o qual a solicitação foi enviada originalmente) e nos elementos no caminho para o qual a solicitação original foi enviada.

Para rotear uma solicitação para um serviço de backend e uma porta específicos com base no host e no caminho, crie uma regra de roteamento no manifesto Ingress. Se o host e o caminho corresponderem à regra de roteamento, o controlador de entrada nativo do OCI roteará a solicitação para o serviço de backend e a porta associados.

Por exemplo, você pode definir a seguinte regra para rotear solicitações originalmente enviadas para http://foo.bar.com/app1 para um serviço de backend chamado foo na porta 80:

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

Rotear solicitações para um backend padrão

Você pode configurar o controlador de entrada nativo do OCI para rotear solicitações de entrada para um backend padrão. Você pode configurar um backend padrão para tratar solicitações que não correspondem a nenhuma regra de roteamento.

Por exemplo, você pode definir o defaultBackend a seguir para rotear solicitações que não correspondem a outras regras no manifesto Ingress para um serviço de backend chamado ServiceC na porta 8080.

Observe que, se você não especificar outras regras em um manifesto Ingress, deverá especificar um 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

Personalizando o comportamento geral usando anotações

Você pode adicionar anotações aos manifestos de recursos IngressClass ou Ingress para personalizar o comportamento geral do controlador de entrada nativo do OCI.

Personalizando o comportamento de verificação de integridade usando anotações

Você pode adicionar anotações ao manifesto de recursos Ingress para personalizar as verificações de integridade executadas pelo balanceador de carga criado pelo controlador de entrada nativo do OCI. Para obter mais informações sobre verificações de integridade do balanceador de carga, consulte Verificações de Integridade para Balanceadores de Carga.

Opção 1: O Controlador de Entrada Nativo do OCI obtém o certificado do serviço Certificates usando um segredo do Kubernetes

Para configurar o controlador de entrada nativo do OCI para obter um certificado do serviço OCI Certificates:

1. Obtenha um par de chaves pública e privada TLS e um certificado.

   Em ambientes de produção, você obtém um certificado TLS da Autoridade de Certificação escolhida enviando uma solicitação de assinatura de certificado. Durante o processo de solicitação de certificado, uma chave pública e a chave privada correspondente são geradas.

   Em ambientes de desenvolvimento e teste, você mesmo pode criar um certificado autoassinado e gerar uma chave privada usando uma ferramenta como OpenSSL. Por exemplo (usando OpenSSL 3.0 ou posterior):

   1. Gere um par de chaves pública e privada informando os seguintes comandos:

      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. Gere um certificado informando os seguintes comandos:

      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

   Neste exemplo:

   • rootCA.key contém o par de chaves da CA raiz.
   • rootCA.crt contém o certificado da CA raiz.
   • server.key contém o par de chaves para gerar o certificado do servidor.
   • server.csr contém a solicitação de assinatura do certificado do servidor.
   • server.crt contém o certificado do servidor gerado.
2. Crie um recurso secreto do Kubernetes de uma das seguintes maneiras:

   • Usando o comando kubectl create secret generic, digitando:

     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

     em que:

     • <k8s-secret-name> é sua escolha de nome para o segredo do Kubernetes
     • --from-file=ca.crt=<path-and-filename>.crt especifica o caminho para o arquivo que contém o certificado da CA raiz. Por exemplo, --from-file=ca.crt=rootCA.crt
     • --from-file=tls.crt=<path-and-filename>.crt especifica o caminho para o arquivo que contém o certificado do servidor gerado. Por exemplo, --from-file=tls.crt=server.crt
     • --from-file=tls.key=<path-and-filename>.key especifica o caminho para o arquivo que contém a chave privada gerada. Por exemplo, --from-file=tls.key=server.key

     Por exemplo:

     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

   • Usando um arquivo de manifesto de recursos Secret:

     1. Defina o segredo do Kubernetes em um arquivo .yaml, no 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>

        em que:

        • name: <k8s-secret-name> é sua escolha de nome para o recurso secreto do Kubernetes.
        • ca.crt: <base64-encoded-certificate-chain> é o conteúdo do arquivo (ou arquivos) que contém certificados intermediários que formam uma cadeia de certificados do certificado folha de volta para a Autoridade de Certificação. Observe que você pode omitir ca.cert, desde que inclua toda a cadeia de certificados como o valor de tls.cert (nesse caso, inicie a cadeia de certificados com o conteúdo do arquivo que contém o certificado do servidor gerado, seguido pelos certificados restantes).
        • tls.crt: <base64-encoded-server-certificate> é o conteúdo do arquivo que contém o certificado do servidor gerado.
        • tls.key: <base64-encoded-private-key> é o conteúdo do arquivo que contém a chave privada gerada.

        Por exemplo:

        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. Crie o recurso secreto digitando kubectl create -f <filename>.yaml

3. Adicione o segredo do Kubernetes a um manifesto de recursos Ingress:
   1. Defina um novo recurso de entrada em um arquivo .yaml. Consulte Criar recurso de Entrada.
   2. Na seção spec: do manifesto, adicione um elemento tls: que especifique o host que receberá o tráfego HTTPS e o nome do segredo do Kubernetes, no formato:

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

      Por exemplo:

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

   3. Na seção rules: do manifesto, adicione uma regra para o host que receberá o tráfego HTTPS e especifique 443 como a porta na qual escutar o tráfego HTTPS.

      Por exemplo:

      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. Crie o recurso digitando kubectl create -f <filename>.yaml

Quando você cria o recurso de entrada, o controlador de entrada nativo do OCI usa o segredo do Kubernetes para obter um certificado do tipo Importado e um pacote de CAs (pacote de Autoridade de Certificação), do serviço OCI Certificates. O controlador de entrada nativo do OCI associa o certificado ao listener e o pacote de CAs ao conjunto de backend.

Quando o listener que atende na porta 443 recebe uma solicitação HTTPS para o host especificado, o listener usa o certificado para encerramento de TLS. Em seguida, o listener usa a regra de roteamento para encaminhar a solicitação ao conjunto de backend. O conjunto de backend cria uma nova conexão TLS com os backends em execução no cluster (usando o pacote de CAs como autoridade confiável para a nova conexão).

Opção 2: Você obtém o certificado do serviço Certificates

Para configurar o controlador de entrada nativo do OCI para usar um certificado obtido do serviço OCI Certificates:

1. Crie um certificado no serviço OCI Certificates de uma das seguintes maneiras:
   • importando um certificado emitido por uma CA de terceiros (o certificado será do tipo Importado)
   • emitindo o certificado internamente de uma CA do serviço Certificates (o certificado será do tipo Issued by internal CA)

   Não crie um certificado para gerenciar externamente (do tipo Emitido por CA interna, gerenciado externamente). Para obter mais informações, consulte Criando um Certificado.

2. Anote o OCID do certificado.
3. Adicione o OCID do certificado a um manifesto de recursos Ingress:
   1. Defina um novo recurso de entrada em um arquivo .yaml. Consulte Criar recurso de Entrada.
   2. Na seção metadata:, adicione um elemento annotations: que especifique o OCID do certificado criado no serviço OCI Certificates, no formato:

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

      em que:

      • name: <i-name> é sua escolha de nome para o recurso de entrada.
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid> é o OCID do certificado criado no serviço OCI Certificates

      Por exemplo:

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

   3. Na seção rules: do manifesto de recursos Ingress, adicione uma regra para o host que receberá o tráfego HTTPS e especifique 443 como a porta na qual escutar o tráfego HTTPS.

      Por exemplo:

      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. Crie o recurso digitando kubectl create -f <filename>.yaml

O que acontece quando você cria o recurso de entrada depende de como criou o certificado no serviço OCI Certificates:

• Se você criou o certificado importando um certificado emitido por uma CA de terceiros, o certificado será do tipo Importado. O controlador de entrada nativo do OCI associa o certificado ao listener, cria um pacote de CAs da cadeia de certificados e associa o pacote de CAs ao conjunto de backend. Observe que não é possível configurar certificados do tipo Importado para serem alternados automaticamente.
• Se você criou o certificado emitindo o certificado internamente de uma CA do serviço Certificates, o certificado será do tipo Emitido por CA interna. O controlador de entrada nativo do OCI associa o certificado ao listener, obtém o OCID da CA e associa esse OCID ao conjunto de backend. Observe que você pode configurar certificados do tipo Emitido por CA interna para serem alternados automaticamente.

Quando o listener que atende na porta 443 recebe uma solicitação HTTPS para o host especificado, o listener usa o certificado para encerramento de TLS. Em seguida, o listener usa a regra de roteamento para encaminhar a solicitação ao conjunto de backend. O conjunto de backend cria uma nova conexão TLS com os backends em execução no cluster (usando o pacote de CAs ou a CA identificada por seu OCID, como a autoridade confiável para a nova conexão).

Aplicando tags definidas ao balanceador de carga

As tags definidas são configuradas e gerenciadas por um administrador de tags. Uma tag definida consiste em um namespace de tag, uma chave e um valor. O namespace de tag e a definição de chave de tag devem ser configurados em uma tenancy para que você possa aplicar uma tag definida a um recurso.

Para especificar que o controlador de entrada nativo do OCI deve aplicar tags definidas ao balanceador de carga, use a anotação oci-native-ingress.oraclecloud.com/defined-tags no manifesto IngressClass, no seguinte formato:

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:
  ...

em que:

• <tag-namespace> é o namespace de tag ao qual a tag pertence.
• <tag-key> é o nome de uma tag definida a ser aplicada ao balanceador de carga.
• <tag-value> é um valor para a tag de uma lista predefinida de valores, ou um novo valor, ou está em branco (dependendo de como a tag definida foi configurada).

O valor da anotação oci-native-ingress.oraclecloud.com/defined-tags é uma string JSON, permitindo que você especifique vários namespaces de tag, chaves de tag e valores de tag no formato JSON.

Por exemplo:

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:
  ...

A alteração de uma das tags na anotação oci-native-ingress.oraclecloud.com/defined-tags do manifesto IngressClass faz com que o controlador de entrada nativo do OCI se aplique novamente ao balanceador de carga todas as tags definidas especificadas pela anotação. No entanto, se uma tag definida contiver uma variável de tag, o controlador de entrada nativo do OCI só reaplicará a tag definida ao balanceador de carga se a tag ainda não estiver presente.

Observe que, para permitir que o controlador de entrada nativo do OCI aplique tags definidas a um balanceador de carga, deve existir uma política de IAM adequada para permitir que o controlador de entrada nativo do OCI use o namespace de tag apropriado. Para obter mais informações, consulte:

• Concedendo Permissões ao Controlador de Entrada Nativo do OCI como um Programa Standalone
• Concedendo Permissões ao Complemento do Cluster do Controlador de Entrada Nativo do OCI

Aplicando tags de formato livre ao balanceador de carga

As tags de formato livre não são gerenciadas por um administrador de tags. Uma tag de formato livre consiste em uma chave e um valor. Ao contrário das tags definidas, as tags de formato livre não pertencem a um namespace de tag.

Para especificar que o controlador de entrada nativo do OCI deve aplicar tags de formato livre ao balanceador de carga, use a anotação oci-native-ingress.oraclecloud.com/freeform-tags no manifesto IngressClass, no seguinte formato:

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

em que:

• <tag-key> é um nome para a tag de formato livre a ser aplicada ao balanceador de carga.
• <tag-value> é um valor para a tag de formato livre a ser aplicada ao balanceador de carga.

O valor da anotação oci-native-ingress.oraclecloud.com/freeform-tags é uma string JSON, permitindo que você especifique várias chaves de tag e valores de tag no formato JSON.

Por exemplo:

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:
  ...

A alteração de uma das tags na anotação oci-native-ingress.oraclecloud.com/freeform-tags do manifesto IngressClass faz com que o controlador de entrada nativo do OCI se aplique novamente ao balanceador de carga todas as tags de formato livre especificadas pela anotação.

Aplicando padrões de tag ao balanceador de carga

Os padrões de tag são configurados para um compartimento específico. Os padrões de tag são específicos do compartimento. Padrões de tag especificam tags definidas que são aplicadas automaticamente a todos os recursos criados em um compartimento específico no momento da criação.

Ao usar o controlador de entrada nativo do OCI versão 1.4.0 (ou posterior), os padrões de tag são aplicados automaticamente aos balanceadores de carga que o controlador de entrada nativo do OCI cria. Posteriormente, o controlador de entrada nativo do OCI mantém um padrão de tag aplicado a um balanceador de carga, a menos que uma das seguintes condições seja atendida:

• Você remove manualmente um padrão de tag que foi aplicado automaticamente a um balanceador de carga.
• Você especifica um padrão de tag como uma tag definida, usando a anotação oci-native-ingress.oraclecloud.com/defined-tags (nesse caso, o controlador de entrada nativo do OCI trata o padrão de tag como qualquer outra tag definida).

Observe que os padrões de tag com valores aplicados pelo usuário não são suportados. Se um padrão de tag com um valor aplicado pelo usuário tiver sido configurado para um compartimento no qual o controlador de entrada nativo do OCI deve criar ou gerenciar um balanceador de carga, use a anotação oci-native-ingress.oraclecloud.com/defined-tags para especificar o padrão de tag como uma tag definida.

Para balanceadores de carga criados usando uma versão do controlador de entrada nativo do OCI anterior à versão 1.4.0 ou ao usar a anotação oci-native-ingress.oraclecloud.com/id para especificar que o controlador de entrada nativo do OCI deve gerenciar um balanceador de carga existente, observe que os padrões de tag não são suportados. Em ambos os casos, para aplicar ou reter um padrão de tag, use a anotação oci-native-ingress.oraclecloud.com/defined-tags para especificar o padrão de tag como uma tag definida.