Como configurar a Entrada para balanceadores de carga internos do aplicativo

Nesta página, mostramos como configurar e usar o Ingress para balanceadores de carga HTTP(S) interno no Google Kubernetes Engine (GKE). O Ingress fornece suporte integrado para balanceamento de carga interno por meio do controlador Ingress do GKE.

Para saber mais sobre quais recursos são compatíveis com o Ingress para balanceadores de carga de aplicativo internos, consulte Recursos do Ingress. Você também pode saber mais sobre como o Ingress para balanceadores de carga de aplicativo internos funciona em Ingress para balanceadores de carga de aplicativo internos.

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.

Requisitos

A Entrada para balanceadores de carga de aplicativo internos tem os seguintes requisitos:

• Seu cluster precisa usar uma versão do GKE posterior a 1.16.5-gke.10.
• O cluster precisa ser nativo de VPC.
• O cluster precisa ter o complemento HttpLoadBalancing ativado. Esse complemento é ativado por padrão. Não o desative.
• Use Grupos de endpoints de rede (NEGs, na sigla em inglês) como back-ends do seu serviço.

Como implantar a Entrada para balanceadores de carga internos do aplicativo

Os exercícios a seguir mostram como implantar o Ingress para balanceadores de carga de aplicativos internos:

1. Preparar o ambiente.
2. Crie um cluster.
3. Implementar um aplicativo.
4. Implantar um Service.
5. Implante o Ingress.
6. Validar a implantação.
7. Excluir recursos de Entrada

Preparar o ambiente

Antes de implantar os recursos do balanceador de carga por meio da API Entrada do Kubernetes, você precisa preparar seu ambiente de rede para que os proxies do balanceador de carga possam ser implantados em uma determinada região.

Criar uma sub-rede somente proxy:

gcloud compute networks subnets create proxy-only-subnet \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=COMPUTE_REGION \
    --network=NETWORK_NAME \
    --range=10.129.0.0/23

Substitua:

• COMPUTE_REGION: uma região do Compute Engine.
• NETWORK_NAME: o nome da rede da sub-rede.

Para mais informações, consulte Como configurar a sub-rede somente proxy.

Criar uma regra de firewall

Observação: o controlador da entrada não cria uma regra de firewall para permitir conexões dos proxies do balanceador de carga na sub-rede do proxy. Crie essa regra de firewall manualmente. No entanto, o controlador da entrada cria regras de firewall para permitir a entrada nas verificações de integridade do Google Cloud.

Crie uma regra de firewall para permitir conexões dos proxies do balanceador de carga na sub-rede somente proxy para a porta de detecção do pod:

gcloud compute firewall-rules create allow-proxy-connection \
    --allow=TCP:CONTAINER_PORT \
    --source-ranges=10.129.0.0/23 \
    --network=NETWORK_NAME

Substitua CONTAINER_PORT pelo valor da porta que o pod está detectando, como 9376.

Como criar um cluster

Nesta seção, você vai criar um cluster nativo de VPC que pode ser usado com o Ingress para balanceadores de carga de aplicativo internos. É possível criar esse cluster usando a Google Cloud CLI ou o Console do Google Cloud.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --network=NETWORK_NAME

Como implantar um aplicativo da Web

Nesta seção, você cria uma implantação.

Para criar uma implantação:

1. Salve o seguinte manifesto de amostra como web-deployment.yaml:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
       app: hostname
     name: hostname-server
   spec:
     selector:
       matchLabels:
         app: hostname
     minReadySeconds: 60
     replicas: 3
     template:
       metadata:
         labels:
           app: hostname
       spec:
         containers:
         - image: registry.k8s.io/serve_hostname:v1.4
           name: hostname-server
           ports:
           - containerPort: 9376
             protocol: TCP
         terminationGracePeriodSeconds: 90
   

   Este manifesto descreve uma implantação que detecta em um servidor HTTPS na porta 9376. Esse Deployment gerencia os pods do aplicativo. Cada pod executa um contêiner de aplicativo com um servidor HTTPS que retorna o nome do host do servidor de aplicativos como a resposta. O nome do host padrão de um pod é o nome do pod. O contêiner também processa o encerramento correto.

2. Aplique o manifesto ao cluster:

   kubectl apply -f web-deployment.yaml
   

Como implantar um serviço como um grupo de endpoints de rede (NEG)

Nesta seção, você cria um recurso Serviço. O Serviço seleciona os contêineres de back-end pelos rótulos para que o controlador Ingress possa programá-los como endpoints de back-end. O Ingress para balanceadores de carga de aplicativo internos requer que você use NEGs como back-ends. O recurso não é compatível com grupos de instâncias como back-ends. Como os back-ends de NEG são necessários, a seguinte anotação de NEG é necessária ao implantar serviços que são expostos por meio do Ingress:

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

Seu serviço é anotado automaticamente com cloud.google.com/neg: '{"ingress": true}' quando todas as condições a seguir são verdadeiras:

• Você está usando clusters nativos de VPC.
• Se você não estiver usando uma VPC compartilhada.
• Se você não estiver usando a política de rede do GKE.

A anotação é adicionada automaticamente usando um MutatingWebhookConfiguration com o nome neg-annotation.config.common-webhooks.networking.gke.io. É possível verificar se MutatingWebhookConfiguration está presente com o seguinte comando:

kubectl get mutatingwebhookconfigurations

O uso de NEGs permite que o controlador Ingress execute o balanceamento de carga nativo do contêiner. O tráfego é balanceado por carga do proxy do Ingress diretamente para o IP do pod, em vez de transferir o IP do nó ou a rede kube-proxy. Além disso, os portões de prontidão do pod são implementados para determinar a integridade dos pods da perspectiva do balanceador de carga, e não apenas das verificações de prontidão e atividade do Kubernetes. Os portões de prontidão do pod garantem que o tráfego não seja interrompido durante eventos do ciclo de vida, como inicialização do pod, perda do pod ou perda de nó.

Se você não incluir uma anotação NEG, receberá um aviso no objeto Ingress que impede a configuração do balanceador de carga de aplicativo interno. Um evento do Kubernetes também será gerado no Ingress se a anotação NEG não estiver incluída. A mensagem a seguir é um exemplo da mensagem de evento:

Message
-------
error while evaluating the ingress spec: could not find port "8080" in service "default/no-neg-svc"

Um NEG não é criado até que um Ingress faça referência ao Serviço. O NEG não aparece no Compute Engine até que o Ingress e o respectivo Serviço referenciado existam. Os NEGs são um recurso zonal e, para clusters com várias zonas, um é criado por Serviço por zona.

Para criar um Service:

1. Salve o seguinte manifesto de amostra como web-service.yaml:

   apiVersion: v1
   kind: Service
   metadata:
     name: hostname
     namespace: default
     annotations:
       cloud.google.com/neg: '{"ingress": true}'
   spec:
     ports:
     - name: host1
       port: 80
       protocol: TCP
       targetPort: 9376
     selector:
       app: hostname
     type: ClusterIP
   

2. Aplique o manifesto ao cluster:

   kubectl apply -f web-service.yaml
   

Como implantar o Ingress

Nesta etapa, você cria um recurso de Entrada que aciona a implantação do balanceador de carga do Compute Engine pelo controlador de Entrada. O Ingress para balanceadores de carga de aplicativo internos requer a seguinte anotação:

annotations:
    kubernetes.io/ingress.class: "gce-internal"

Não é possível usar o campo ingressClassName para especificar um objeto Ingress do GKE. É preciso usar a anotação kubernetes.io/ingress.class. Para mais informações, consulte Comportamento do controlador de entrada do GKE.

Para criar um Ingress:

1. Salve o seguinte manifesto de amostra como internal-ingress.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ilb-demo-ingress
     namespace: default
     annotations:
       kubernetes.io/ingress.class: "gce-internal"
   spec:
     defaultBackend:
       service:
         name: hostname
         port:
           number: 80
   

2. Aplique o manifesto ao cluster:

   kubectl apply -f internal-ingress.yaml
   

Como validar uma implantação bem-sucedida do Ingress

Nesta seção, você validará se a implantação foi bem-sucedida.

Pode levar vários minutos para que o recurso Ingress seja totalmente provisionado. Durante esse período, o controlador Ingress cria itens como regras de encaminhamento, serviços de back-end, mapas de URL e NEGs.

Para recuperar o status do recurso Ingress criado na seção anterior, execute o seguinte comando:

kubectl get ingress ilb-demo-ingress

A saída será assim:

NAME               HOSTS    ADDRESS            PORTS     AGE
ilb-demo-ingress   *        10.128.0.58        80        59s

Quando o campo ADDRESS é preenchido, o Ingress está pronto. O uso de um endereço RFC 1918 nesse campo indica um IP interno na VPC.

Como o balanceador de carga de aplicativo interno é um balanceador de carga regional, o IP virtual (VIP, na sigla em inglês) só pode ser acessado por um cliente dentro da mesma região e VPC. Depois de recuperar o VIP do balanceador de carga, use ferramentas (por exemplo, curl) para emitir chamadas HTTP GET para o VIP de dentro da VPC.

Para emitir uma chamada HTTP GET, siga estas

1. Para alcançar o VIP do Ingress de dentro da VPC, implante uma VM na mesma região e rede do cluster.

   gcloud compute instances create l7-ilb-client \
       --image-family=debian-10 \
       --image-project=debian-cloud \
       --network=NETWORK_NAME \
       --subnet=SUBNET_NAME \
       --zone=COMPUTE_ZONE \
       --tags=allow-ssh
   

   Substitua:

   • SUBNET_NAME: o nome de uma sub-rede na rede.
   • COMPUTE_ZONE: uma zona do Compute Engine na região.

   Para saber mais sobre como criar instâncias, consulte Como criar e iniciar uma instância de VM.

2. Para acessar o VIP interno de dentro da VM, use curl:

   1. Use SSH para acessar a VM criada na etapa anterior:

      gcloud compute ssh l7-ilb-client \
          --zone=COMPUTE_ZONE 
      

   2. Use curl para acessar o VIP do aplicativo interno:

      curl 10.128.0.58
      hostname-server-6696cf5fc8-z4788
      

      A resposta HTTP e o nome do host de um dos contêineres de back-end indicam que o caminho de balanceamento de carga completo está funcionando corretamente.

Como excluir recursos de Entrada

A remoção dos recursos Ingress e Serviço também remove os recursos do balanceador de carga do Compute Engine associados a eles. Para evitar o vazamento de recursos, garanta que os recursos Ingress sejam eliminados quando você não precisar mais deles. Também é preciso excluir os recursos Ingress e Serviço antes de excluir clusters ou outros recursos de balanceamento de carga do Compute Engine serem órfãos.

Para remover uma Entrada, conclua as seguintes etapas:

1. Exclua o Ingress: Por exemplo, para excluir a entrada criada nesta página, execute o seguinte comando:

   kubectl delete ingress ilb-demo-ingress
   

   A exclusão do Ingress remove as regras de encaminhamento, os serviços de back-end e os mapas de URL associados a esse recurso Ingress.

2. Exclua o serviço: Por exemplo, para excluir o serviço criado nesta página, execute o seguinte comando:

   kubectl delete service hostname
   

   A exclusão do Serviço remove o NEG associado a ele.

Para implantar um aplicativo no GKE e expor o aplicativo com um endereço IP particular de balanceamento de carga, consulte Entrada interna básica.

Endereços IP estáticos

Os recursos de entrada interna são compatíveis com os endereços IP estático e temporário. Se um endereço IP não for especificado, um endereço IP disponível será alocado automaticamente da sub-rede do nó do GKE. No entanto, o recurso Ingress não provisiona endereços IP da sub-rede somente proxy, porque essa sub-rede é usada apenas para consumo interno de proxy. Esses endereços IP temporários são alocados ao Ingress somente pelo ciclo de vida do recurso interno do Ingress. Se você excluir a Entrada e criar uma nova no mesmo arquivo de manifesto, pode ser que não receba o mesmo endereço IP externo.

Se você quiser um endereço IP permanente que seja independente do ciclo de vida do recurso Ingress interno, reserve um endereço IP interno estático regional. Em seguida, especifique um endereço IP estático usando a anotação kubernetes.io/ingress.regional-static-ip-name no recurso de entrada.

O exemplo a seguir mostra como adicionar essa anotação:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.regional-static-ip-name: STATIC_IP_NAME
    kubernetes.io/ingress.class: "gce-internal"

Substitua STATIC_IP_NAME por um nome de IP estático que atenda aos seguintes critérios:

• Crie o endereço IP estático antes de implantar a entrada. Um balanceador de carga não é implantado até que o IP estático exista, e a referência a um recurso de endereço IP inexistente não cria um IP estático. 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.
• O IP estático é reservado no projeto de serviço para uma entrada implantada no projeto de serviço de uma VPC compartilhada.
• Faça referência ao recurso de endereço IP do Google Cloud pelo nome, e não pelo endereço IP.
• O endereço IP precisa ser de uma sub-rede na mesma região que o cluster do GKE. Use qualquer sub-rede privada disponível na região (exceto sub-rede somente proxy). Diferentes recursos de Entrada também podem ter endereços de sub-redes diferentes.

HTTPS entre o cliente e o balanceador de carga

O Ingress para balanceamento de carga interno permite a exibição de certificados TLS para clientes. É possível exibir certificados TLS por meio de secrets do Kubernetes ou de certificados SSL regionais pré-compartilhados no Google Cloud. Também é possível especificar vários certificados por recurso Ingress. O GKE 1.25+ é compatível com o uso simultâneo de HTTPS e HTTP. Para ativar esse recurso, você precisa criar um endereço IP estático com PURPOSE=SHARED_LOADBALANCER_VIP e configurá-lo na entrada. Se um endereço IP estático não for fornecido, somente o tráfego HTTPS será permitido, e você precisará seguir a documentação para Desativar o HTTP.

As etapas a seguir detalham como criar um certificado no Google Cloud e disponibilizá-lo por meio do Ingress para clientes internos para tráfego HTTPS e HTTP:

1. Crie o certificado regional:

   gcloud compute ssl-certificates create CERT_NAME \
       --certificate CERT_FILE_PATH \
       --private-key KEY_FILE_PATH \
       --region COMPUTE_REGION
   

   Substitua:

   • CERT_NAME: um nome para o certificado escolhido.
   • CERT_FILE_PATH: o caminho para o arquivo de certificado local a fim de criar um certificado autogerenciado. O certificado precisa estar no formato PEM.
   • KEY_FILE_PATH: o caminho para um arquivo de chave privada local. A chave privada precisa estar no formato PEM e usar a criptografia RSA ou ECDSA.
   • COMPUTE_REGION: uma região do Compute Engine para o certificado.

2. Reserve e aplique um endereço IP estático após o endereçamento IP estático.

3. Salve o seguinte manifesto de amostra como ingress-pre-shared-cert.yaml:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ilb-demo-ing
     namespace: default
     annotations:
       ingress.gcp.kubernetes.io/pre-shared-cert: "CERT_NAME"
       kubernetes.io/ingress.regional-static-ip-name: STATIC_IP_NAME
       kubernetes.io/ingress.class: "gce-internal"
   spec:
     rules:
     - host: DOMAIN
       http:
         paths:
         - pathType: ImplementationSpecific
           backend:
             service:
               name: SERVICE_NAME
               port:
                 number: 80
   

   Substitua:

   • DOMAIN: seu domínio.
   • CERT_NAME: o nome do certificado criado na seção anterior.
   • SERVICE_NAME: o nome do serviço.

4. Aplique o manifesto ao cluster:

   kubectl apply -f ingress-pre-shared-cert.yaml
   

HTTPS entre o balanceador de carga e o aplicativo

Se o aplicativo for executado em um pod do GKE e puder receber solicitações HTTPS, será possível configurar 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.

VPC compartilhada

Adicionar manualmente a anotação do NEG

Se o GKE em que você está implantando os recursos do Entrada estiver em um projeto de serviço de VPC compartilhada, os serviços não serão anotados automaticamente com a anotação cloud.google.com/neg: '{"ingress": true}' porque o MutatingWebhookConfiguration responsável pela injeção a anotação para os serviços não está instalada.

Adicione a anotação do NEG ao manifesto dos Serviços que são expostos por meio do Ingress dos balanceadores de carga de aplicativo internos.

Regras de firewall da VPC

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 o tráfego de entrada nas 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 internas do Ingress

As tabelas a seguir mostram as anotações que podem ser adicionadas ao criar recursos de Entrada e Serviço para Ingress para balanceadores de carga de aplicativo interno.

Anotações do Ingress

Anotações de serviço relacionadas à Entrada

Solução de problemas

Entender e observar o estado do Ingress geralmente envolve a inspeção dos recursos associados. Os tipos de problemas encontrados geralmente incluem recursos de balanceamento de carga que não estão sendo criados corretamente, tráfego que não alcança back-ends ou back-ends que não aparecem íntegros.

Algumas etapas comuns de solução de problemas incluem:

• Verificação de que o tráfego do cliente é derivado da mesma região e VPC que o balanceador de carga.
• Verificação de que os pods e back-ends estão íntegros.
• Validação do caminho de tráfego para o VIP e das verificações de integridade do Compute Engine para garantir que ele não seja bloqueado por regras de firewall.
• Verificação de erros nos eventos do recurso Ingress.
• Descrição do recurso Ingress para ver o mapeamento para recursos do Compute Engine.
• Validação de que os recursos de balanceamento de carga do Compute Engine existem, têm as configurações corretas e não têm erros relatados.

Como filtrar eventos do Ingress

A consulta a seguir filtra erros em todos os eventos do Ingress no cluster.

kubectl get events --all-namespaces --field-selector involvedObject.kind=Ingress

Também é possível filtrar por objetos ou nomes de objetos:

kubectl get events --field-selector involvedObject.kind=Ingress,involvedObject.name=hostname-internal-ingress

No seguinte erro, veja que o Serviço referenciado pelo Ingress não existe:

LAST SEEN   TYPE      REASON      OBJECT                              MESSAGE
0s          Warning   Translate   ingress/hostname-internal-ingress   error while evaluating the ingress spec: could not find service "default/hostname-invalid"

Como inspecionar recursos do balanceador de carga do Compute Engine

O comando a seguir exibe a saída completa do recurso Ingress para que você veja os mapeamentos para os recursos do Compute Engine criados pelo controlador Ingress:

kubectl get ing INGRESS_FILENAME -o yaml

Substitua INGRESS_FILENAME pelo nome de arquivo do recurso Ingress.

A saída será assim:

apiVersion: v1
items:
- apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      ingress.kubernetes.io/backends: '{"k8s1-241a2b5c-default-hostname-80-29269aa5":"HEALTHY"}'
      ingress.kubernetes.io/forwarding-rule: k8s-fw-default-ilb-demo-ingress--241a2b5c94b353ec
      ingress.kubernetes.io/target-proxy: k8s-tp-default-ilb-demo-ingress--241a2b5c94b353ec
      ingress.kubernetes.io/url-map: k8s-um-default-ilb-demo-ingress--241a2b5c94b353ec
      kubectl.kubernetes.io/last-applied-configuration: |
       {"apiVersion":"networking.k8s.io/v1","kind":"Ingress","metadata":{"annotations":{"kubernetes.io/ingress.class":"gce-internal"},"name":"ilb-demo-ingress","namespace":"default"},"spec":{"defaultBackend":{"service":{"name":"hostname"},"port":{"number":80}}}}
      kubernetes.io/ingress.class: gce-internal
    creationTimestamp: "2019-10-15T02:16:18Z"
    finalizers:
    - networking.gke.io/ingress-finalizer
    generation: 1
    name: ilb-demo-ingress
    namespace: default
    resourceVersion: "1538072"
    selfLink: /apis/networking.k8s.io/v1/namespaces/default/ingresses/ilb-demo-ingress
    uid: 0ef024fe-6aea-4ee0-85f6-c2578f554975
  spec:
    defaultBackend:
      service:
        name: hostname
        port:
          number: 80
  status:
    loadBalancer:
      ingress:
      - ip: 10.128.0.127
kind: List
metadata:
  resourceVersion: ""
  selfLink: ""

As anotações ingress.kubernetes.io/backends listam os back-ends e os status. Verifique se os back-ends estão listados como HEALTHY.

Os recursos do Compute Engine criados pelo Ingress podem ser consultados diretamente para entender o status e a configuração deles. A execução dessas consultas também pode ser útil para a solução de problemas.

Para listar todas as regras de encaminhamento do Compute Engine:

gcloud compute forwarding-rules list

A saída será assim:

NAME                                                        REGION       IP_ADDRESS      IP_PROTOCOL  TARGET
k8s-fw-default-hostname-internal-ingress--42084f6a534c335b  REGION_NAME  10.128.15.225   TCP          REGION_NAME/targetHttpProxies/k8s-tp-default-hostname-internal-ingress--42084f6a534c335b

Para listar a integridade de um serviço de back-end, primeiro liste os serviços de back-end e faça uma cópia do nome do serviço de back-end que você quer inspecionar:

gcloud compute backend-services list

A saída será assim:

NAME                                         BACKENDS                                                                       PROTOCOL
k8s1-42084f6a-default-hostname-80-98cbc1c1   REGION_NAME/networkEndpointGroups/k8s1-42084f6a-default-hostname-80-98cbc1c1 HTTP

Agora você pode usar o nome do serviço de back-end para consultar a integridade dele:

gcloud compute backend-services get-health k8s1-42084f6a-default-hostname-80-98cbc1c1 \
    --region COMPUTE_REGION

Substitua COMPUTE_REGION pela região do Compute Engine do serviço de back-end.

O resultado será assim:

backend: https://www.googleapis.com/compute/v1/projects/user1-243723/zones/ZONE_NAME/networkEndpointGroups/k8s1-42084f6a-default-hostname-80-98cbc1c1
status:
  healthStatus:
  - healthState: HEALTHY

A seguir

• Saiba mais sobre a Entrada do GKE para balanceadores de carga de aplicativos externos.

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

• Saiba como criar um balanceador de carga de rede de passagem interna no GKE.

• Implemente uma entrada interna básica.