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.

Console

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

  2. Clique no nome do cluster que você quer modificar.

  3. Em Rede, no campo Balanceamento de carga HTTP, clique em Editar balanceamento de carga HTTP.

  4. Marque a caixa de seleção Ativar balanceamento de carga HTTP.

  5. Clique em Salvar alterações.

gcloud

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

Substitua CLUSTER_NAME pelo nome do cluster.

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:

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ção Descrição
kubernetes.io/ingress.allow-http Especifica se o tráfego HTTP será permitido entre o cliente e o balanceador de carga HTTP(S). Os valores possíveis são "verdadeiro" e "falso". O padrão é "verdadeiro". Consulte Como desativar o HTTP.
ingress.gcp.kubernetes.io/pre-shared-cert Use esta anotação para anexar recursos de certificado a recursos de entrada do GKE. Para mais informações, consulte Como usar vários certificados SSL com balanceadores de carga de aplicativo externos.
kubernetes.io/ingress.global-static-ip-name Use essa anotação para especificar que o balanceador de carga usará um endereço IP externo e estático que você criou anteriormente. Consulte Endereços IP estáticos para balanceadores de carga HTTP(S).
networking.gke.io/v1beta1.FrontendConfig Use esta anotação para personalizar a configuração do balanceador de carga voltada para o cliente. Para mais informações, consulte Configuração de entrada.
networking.gke.io/suppress-firewall-xpn-error Para os balanceadores de carga de Entrada, se o Kubernetes não puder alterar as regras de firewall devido à permissão insuficiente, um evento firewallXPNError será criado em um intervalo de vários minutos. No GLBC 1.4 (em inglês) e posterior, adicione a anotação networking.gke.io/suppress-firewall-xpn-error: "true" ao recurso de entrada para desativar o som do evento firewallXPNError. Sempre é possível remover essa anotação para ativar o som. Os valores possíveis são true e false. O valor padrão é false.
Anotação Descrição
cloud.google.com/app-protocols Use essa anotação para definir o protocolo de comunicação entre o balanceador de carga e o aplicativo. Os protocolos possíveis são HTTP, HTTPS e HTTP2. Consulte HTTPS entre o balanceador de carga e o aplicativo e HTTP/2 para balanceamento de carga com Entrada.
cloud.google.com/backend-config Use essa anotação para configurar o serviço de back-end associado a um Serviço. Para mais informações, consulte Configuração de entrada.
cloud.google.com/neg Use essa anotação para especificar que o balanceador de carga usará grupos de endpoint de rede. Consulte Como usar o balanceamento de carga nativo de contêiner.

A seguir