Como configurar a Entrada para balanceadores de carga externos do aplicativo

Neste documento, mostramos como configurar um balanceador de carga de aplicativo externo criando um objeto Ingress do Kubernetes.

Antes de ler este documento, você precisa conhecer bem os conceitos de rede do GKE.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

Ativar o complemento HttpLoadBalancing

O cluster precisa ter o complemento HttpLoadBalancing ativado. Esse complemento é ativado por padrão. Em clusters do Autopilot, não é possível desativar esse complemento.

É possível ativar o complemento HttpLoadBalancing usando o Console do Google Cloud ou a Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME --update-addons=HttpLoadBalancing=ENABLED

Criar um endereço IP estático

Um balanceador de carga de aplicativo externo fornece um endereço IP estável que pode ser usado para encaminhar solicitações para um ou mais serviços. Se você quiser um endereço IP permanente, será necessário reservar um endereço IP externo estático global antes de criar uma entrada.

Se você modificar uma entrada atual para usar um endereço IP estático em vez de um endereço IP temporário, o GKE poderá alterar o endereço IP do balanceador de carga quando o GKE recriar a regra de encaminhamento do balanceador de carga de dados.

Criar um balanceador de carga de aplicativo externo

Neste exercício, você configura um balanceador de carga de aplicativo externo para fazer o encaminhamento de solicitações para diferentes serviços de back-end, dependendo do caminho do URL.

Para seguir as instruções passo a passo desta tarefa diretamente no console do Google Cloud, clique em Orientação:

Orientações

Criar implantações e serviços

Crie duas implantações com serviços chamados hello-world-1 e hello-world-2:

1. Salve o seguinte manifesto como hello-world-deployment-1.yaml:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: hello-world-deployment-1
   spec:
     selector:
       matchLabels:
         greeting: hello
         version: one
     replicas: 3
     template:
       metadata:
         labels:
           greeting: hello
           version: one
       spec:
         containers:
         - name: hello-app-1
           image: "us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0"
           env:
           - name: "PORT"
             value: "50000"
   

   Este manifesto descreve um exemplo de implantação com três réplicas.

2. Aplique o manifesto ao cluster:

   kubectl apply -f hello-world-deployment-1.yaml
   

3. Salve o seguinte manifesto como hello-world-service-1.yaml:

   apiVersion: v1
   kind: Service
   metadata:
     name: hello-world-1
   spec:
     type: NodePort
     selector:
       greeting: hello
       version: one
     ports:
     - protocol: TCP
       port: 60000
       targetPort: 50000
   

   Este manifesto descreve um Serviço com as seguintes propriedades:

   • Qualquer pod que tenha o rótulo greeting: hello e o rótulo version: one é membro do serviço.
   • O GKE encaminha as solicitações enviadas ao serviço na porta TCP 60000 para um dos pods de membro na porta TCP 50000.
   • O tipo de serviço inclui NodePort, que é obrigatório, a menos que você esteja usando o balanceamento de carga nativo de contêiner. Se estiver, não há restrição de tipo de serviço. O uso de type: ClusterIP é recomendado.

4. Aplique o manifesto ao cluster:

   kubectl apply -f hello-world-service-1.yaml
   

5. Salve o seguinte manifesto como hello-world-deployment-2.yaml:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: hello-world-deployment-2
   spec:
     selector:
       matchLabels:
         greeting: hello
         version: two
     replicas: 3
     template:
       metadata:
         labels:
           greeting: hello
           version: two
       spec:
         containers:
         - name: hello-app-2
           image: "us-docker.pkg.dev/google-samples/containers/gke/hello-app:2.0"
           env:
           - name: "PORT"
             value: "8080"
   

   Este manifesto descreve um exemplo de implantação com três réplicas.

6. Aplique o manifesto ao cluster:

   kubectl apply -f hello-world-deployment-2.yaml
   

7. Salve o seguinte manifesto como hello-world-service-2.yaml:

   apiVersion: v1
   kind: Service
   metadata:
     name: hello-world-2
   spec:
     type: NodePort
     selector:
       greeting: hello
       version: two
     ports:
     - protocol: TCP
       port: 80
       targetPort: 8080
   

   Este manifesto descreve um Serviço com as seguintes propriedades:

   • Qualquer pod que tenha o rótulo greeting: hello e o rótulo version: two é membro do serviço.
   • O GKE encaminha as solicitações enviadas ao serviço na porta TCP 80 para um dos pods de membro na porta TCP 8080.

8. Aplique o manifesto ao cluster:

   kubectl apply -f hello-world-service-2.yaml
   

Criar uma Entrada

Crie uma entrada que especifique regras para encaminhar solicitações, dependendo do caminho do URL na solicitação. Quando você cria o Ingress, o controlador de Entrada do GKE cria e configura um balanceador de carga de aplicativo externo.

1. Salve o seguinte manifesto como my-ingress.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: my-ingress
     annotations:
       # If the class annotation is not specified it defaults to "gce".
       kubernetes.io/ingress.class: "gce"
   spec:
     rules:
     - http:
         paths:
         - path: /*
           pathType: ImplementationSpecific
           backend:
             service:
               name: hello-world-1
               port:
                 number: 60000
         - path: /v2
           pathType: ImplementationSpecific
           backend:
             service:
               name: hello-world-2
               port:
                 number: 80
   

   Esse manifesto descreve uma Entrada com as seguintes propriedades:

   • Há duas classes de entrada do GKE. Para especificar uma classe de entrada, é necessário usar a anotação kubernetes.io/ingress.class. Não é possível especificar uma Entrada do GKE usando spec.ingressClassName.

   • A classe gce implanta um balanceador de carga de aplicativo externo.

   • A classe gce-internal implanta um balanceador de carga de aplicativo interno.

   • Quando você implanta um recurso Ingress sem as anotações spec.ingressClassName e kubernetes.io/ingress.class, o GKE cria um balanceador de carga de aplicativo externo. Esse é o mesmo comportamento que ocorrerá se você especificar a anotação kubernetes.io/ingress.class: gce. Para mais informações, consulte Comportamento do controlador de entrada do GKE.

   • O GKE cria um serviço de back-end do Google Cloud para cada backend.service.

   • Quando um cliente envia uma solicitação ao balanceador de carga com o caminho do URL /, o GKE encaminha a solicitação ao serviço hello-world-1 na porta 60000. Quando um cliente envia uma solicitação ao balanceador de carga usando o caminho do URL /v2, o GKE encaminha a solicitação ao serviço hello-world-2 na porta 80. Para mais informações sobre as propriedades path e pathType, consulte Caminhos do URL.

2. Aplique o manifesto ao cluster:

   kubectl apply -f my-ingress.yaml
   

Testar o balanceador de carga de aplicativo externo

Aguarde cerca de cinco minutos para que o balanceador de carga seja configurado e, em seguida, teste o balanceador de carga de aplicativo externo:

1. Veja a Entrada:

   kubectl get ingress my-ingress --output yaml
   

   A saída mostra o endereço IP do balanceador de carga de aplicativo externo:

   status:
     loadBalancer:
       ingress:
       - ip: 203.0.113.1
   

2. Teste o caminho /:

   curl LOAD_BALANCER_IP_ADDRESS/
   

   Substitua LOAD_BALANCER_IP_ADDRESS pelo endereço IP externo do balanceador de carga.

   O resultado será assim:

   Hello, world!
   Version: 1.0.0
   Hostname: ...
   

   Se a saída incluir um erro 404, aguarde alguns minutos.

3. Teste o caminho /v2:

   curl load-balancer-ip/v2
   

   O resultado será assim:

   Hello, world!
   Version: 2.0.0
   Hostname: ...
   

Como funciona a Entrada para balanceamento de carga externo

Um balanceador de carga de aplicativo externo atua como um proxy entre seus clientes e seu aplicativo. Se você quiser aceitar solicitações HTTPS dos seus clientes, o balanceador de carga precisará ter um certificado para provar a identidade dele aos clientes. Além disso, ele precisa ter uma chave privada para concluir o handshake HTTPS. Veja mais informações em:

• Como configurar o HTTPS (TLS) entre o cliente e o balanceador de carga.
• Como usar vários certificados SSL no balanceamento de carga HTTP(S) com o Ingress

Caminhos de URL

O único caractere curinga aceito no campo path de uma entrada é *. O caractere * precisa vir depois de uma barra (/) e ser o último caractere no padrão. Por exemplo, /*, /foo/* e /foo/bar/* são padrões válidos, ao contrário de *, /foo/bar* e /foo/*/bar.

Um padrão mais específico tem precedência sobre um menos específico. Se você tiver os padrões /foo/* e /foo/bar/*, /foo/bar/bat será usado na correspondência com /foo/bar/*. Para mais informações sobre limitações de caminho e correspondência de padrões, consulte a documentação dos mapas de URL.

Para clusters do GKE que executam versões anteriores à 1.21.3-gke.1600, o único valor compatível com o campo pathType é ImplementationSpecific. Para clusters que executam a versão 1.21.3-gke.1600 ou posterior, os valores Prefix e Exact também são compatíveis com pathType.

Como desativar o HTTP

Se você quiser que todo o tráfego entre o cliente e o balanceador de carga use HTTPS, desative o HTTP. Para mais informações, consulte Como desativar o HTTP.

HTTPS entre o balanceador de carga e o aplicativo

Se o aplicativo em execução em um pod do GKE for capaz de receber solicitações HTTPS, configure o balanceador de carga para usar HTTPS quando encaminhar solicitações para o aplicativo. Para mais informações, consulte HTTPS (TLS) entre o balanceador de carga e o aplicativo.

HTTP/2 entre o cliente e o balanceador de carga

Os clientes podem usar HTTP/2 para enviar solicitações ao balanceador de carga. Nenhuma configuração é necessária.

HTTP/2 entre o balanceador de carga e o aplicativo

Se seu aplicativo em execução em um pod do GKE for capaz de receber solicitações HTTP/2, é possível configurar o balanceador de carga para usar HTTP/2 ao encaminhar solicitações para o aplicativo. Para mais informações, consulte HTTP/2 para balanceamento de carga com Entrada.

Grupos de endpoint de rede

Se o cluster for compatível com o balanceamento de carga nativo de contêiner, recomendamos usar grupos de endpoints de rede (NEGs, na sigla em inglês). Para clusters do GKE 1.17 e posteriores e em determinadas condições, o balanceamento de carga nativo de contêiner é padrão e não requer uma anotação de serviço cloud.google.com/neg: '{"ingress": true}' explícita.

VPC compartilhada

Se o cluster do GKE em que você está implantando os recursos de Entrada estiver em um projeto de serviço e você quiser que o plano de controle do GKE gerencie os recursos de firewall no projeto host, a conta de serviço do GKE do projeto de serviço precisará receber as permissões apropriadas do IAM no projeto de host, conforme mostrado em Como gerenciar recursos de firewall para clusters com VPC compartilhada. Isso permite que o controlador de Entrada crie regras de firewall para permitir tráfego de entrada e tráfego para verificações de integridade do Google Cloud.

Veja a seguir um exemplo de evento que pode estar presente nos registros de recurso da Entrada. Esse erro ocorre quando o controlador de Entrada não consegue criar uma regra de firewall para permitir o tráfego de Entrada para verificações de integridade do Google Cloud se as permissões não estiverem configuradas corretamente.

Firewall change required by security admin: `gcloud compute firewall-rules update <RULE_NAME> --description "GCE L7 firewall rule" --allow tcp:<PORT> --source-ranges 130.211.0.0/22,35.191.0.0/16 --target-tags <TARGET_TAG> --project <HOST_PROJECT>

Se você preferir provisionar manualmente regras de firewall do projeto host, é possível desativar os eventos firewallXPNError adicionando a anotação networking.gke.io/suppress-firewall-xpn-error: "true" ao recurso de Entrada.

Resumo das anotações de Entrada externa

Anotações do Ingress

Anotações de serviço relacionadas à Entrada

A seguir

• Leia uma visão geral conceitual da Entrada para balanceadores de carga de aplicativo externos no GKE.

• Execute o tutorial sobre Como configurar um balanceador de carga de aplicativo externo com a Entrada.

• Leia uma visão geral conceitual dos serviços no GKE.

• Implemente uma entrada externa básica.