Como configurar a Entrada para balanceadores de carga externos do aplicativo

Nesta página, mostramos como configurar um balanceador de carga de aplicativo externo criando um objeto Ingress do Kubernetes.

Antes de ler esta página, conheça os conceitos de rede no 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 o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

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 HttpLoadBalancing complemento usando o Google Cloud console ou a Google Cloud CLI.

Console

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

    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 detalhadas desta tarefa diretamente no Google Cloud console, 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, mas recomendamos que você use um serviço de type ClusterIP, a menos que precise explicitamente do nodePort fornecido por um serviço NodePort. Os serviços LoadBalancer não têm suporte como back-ends de entrada.

  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 Google Cloud serviço de back-end para cada backend.service. Cada um dos serviços de back-end corresponde a um serviço do Kubernetes, e cada serviço de back-end precisa fazer referência a uma Google Cloud verificação de integridade. Essa verificação de integridade é diferente de uma sondagem de atividade ou prontidão do Kubernetes porque a verificação de integridade é implementada fora do cluster. Para saber mais, consulte Verificações de integridade

    • Quando um cliente envia uma solicitação ao balanceador de carga com o caminho do URL /, o GKE encaminha a solicitação ao hello-world-1 serviço 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.

    • Se você quiser reservar um endereço IP externo estático global, inclua uma kubernetes.io/ingress.global-static-ip-name anotação no objeto Entrada , conforme mostrado aqui:

     apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: my-ingress
   annotations:
     kubernetes.io/ingress.global-static-ip-name: my-static-address
 ```

  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

Esta seção descreve os componentes e as configurações que ativam o balanceamento de carga externo para aplicativos do GKE, incluindo correspondência de caminho de URL, grupos de endpoints de rede e integração da VPC compartilhada.

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.

Grupos de endpoints 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). Ao criar a entrada, o GKE cria um balanceador de carga de aplicativo no projeto e os NEGs são criados em cada zona em que o cluster é executado. Os endpoints no NEG e os do serviço são mantidos em sincronia. Para clusters do GKE 1.17 e mais recentes, 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 em determinadas condições. Para clusters em que os NEGs não são o padrão, ainda é altamente recomendado usar o balanceamento de carga nativo de contêiner, mas ele precisa ser ativado explicitamente em cada Serviço. A anotação deve ser aplicada aos Serviços da seguinte maneira:

kind: Service
...
  annotations:
    cloud.google.com/neg: '{"ingress": true}'
...

Ao adicionar essa anotação, será criado um novo BackendService para o serviço atual. Isso pode resultar em uma interrupção temporária no serviço.

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 Google Cloud verificações de integridade.

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 Google Cloud verificações de integridade 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 host projeto, é possível desativar os eventos firewallXPNError adicionando a networking.gke.io/suppress-firewall-xpn-error: "true" anotação ao recurso de Entrada.

Resumo das anotações de Entrada externa

É possível usar as anotações a seguir para configurar o comportamento dos recursos de Entrada externa e dos objetos de serviço do Kubernetes associados.

Anotações do Entrada

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