Ingress configuration on Google Cloud

Autopilot Padrão

---

Nesta página, você encontra uma visão geral do que é compatível e configurável por meio do Ingress do Kubernetes no Google Cloud.

Comparação do recurso

A tabela a seguir fornece uma lista de recursos compatíveis com o Ingress no Google Cloud. A disponibilidade do recurso, Disponibilidade geral (GA, na sigla em inglês) ou Beta, também é indicada.

Classe do Ingress	Entrada externa	Entrada interna	Entrada de vários clusters
Controlador de entrada	Controlador de entrada hospedado pelo Google			Controlador de Ingress do GKE
Tipo de balanceador de carga do Google Cloud	BC de HTTP(S) externo	BC de HTTP(S) interno	BC de HTTP(S) externo
Escopo do cluster	Cluster único	Cluster único	Vários clusters
Escopo do balanceador de carga	Global	Discos	Global
Suporte ao ambiente	GKE	GKE	GKE
Suporte para VPC compartilhada	GA	GA	GA
Anotações de serviço
Balanceamento de carga nativo de contêiner (NEGs)	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
HTTPS do balanceador de carga para back-ends	Disponibilidade geral	GA	Disponibilidade geral
HTTP/2	Disponibilidade geral	Disponibilidade geral Somente TLS	Disponibilidade geral
Anotações do Ingress
Endereços IP estáticos	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Certificados baseados em secrets do Kubernetes	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Certificados SSL autogerenciados	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Certificados SSL gerenciados pelo Google	Disponibilidade geral		Disponibilidade geral
FrontendConfig
Política de SSL	Disponibilidade geral		Disponibilidade geral
Redirecionamento HTTP-para-HTTPS	GA 1.17.13-gke.2600+^GA		Disponibilidade geral
BackendConfig
Tempo limite do serviço de back-end	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Cloud CDN	Disponibilidade geral		Disponibilidade geral
Tempo limite de diminuição da conexão	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Configuração personalizada da verificação de integridade do balanceador de carga	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Política de segurança do Google Cloud Armor	GA 1.19.10-gke.700^G		Disponibilidade geral
Configuração da geração de registros de acesso HTTP	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Identity-Aware Proxy (IAP)	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Afinidade da sessão	Disponibilidade geral	Disponibilidade geral	Disponibilidade geral
Cabeçalhos de solicitação definidos pelo usuário	Disponibilidade geral		Disponibilidade geral
Cabeçalhos de resposta personalizados	Disponibilidade geral	Disponibilidade geral

^B Esse recurso está disponível na versão Beta a partir da versão especificada. Os recursos sem uma versão listada são compatíveis com todas as versões disponíveis do GKE e do GKE Enterprise.

^G Este recurso é compatível com o GA a partir da versão especificada.

Como configurar o Ingress usando o controlador padrão

Não é possível configurar manualmente os recursos do LoadBalancer usando o SDK Google Cloud ou o console. É preciso usar os recursos do Kubernetes BackendConfig ou FrontendConfig.

Ao criar um Ingress usando o controlador padrão, é possível escolher o tipo de balanceador de carga (um balanceador de carga de aplicativo externo ou interno) usando uma anotação no objeto Ingress. Você pode escolher se o GKE cria NEGs zonais ou se usa grupos de instâncias com uma anotação em cada objeto Serviço.

As definições de recursos personalizados (CRDs) do FrontendConfig e do BackendConfig permitem personalizar ainda mais o balanceador de carga. Com essas CRDs, você define recursos adicionais do balanceador de carga de maneira mais estruturada do que as anotações. Para usar a Entrada (e esses CRDs), é necessário que o complemento de balanceamento de carga HTTP esteja ativado. Os clusters do GKE têm o balanceamento de carga HTTP ativado por padrão. Não o desative.

Os FrontendsConfigs são referenciados em um objeto de entrada e só podem ser usados com entradas externas. Os BackendConfigs são referenciados por um objeto de serviço. As mesmas CRDs podem ser referenciadas por vários objetos do Serviço ou da Entrada para consistência na configuração. As CRDs do FrontendConfig e do BackendConfig compartilham o mesmo ciclo de vida dos recursos Entrada e Serviço correspondentes e costumam ser implantados juntos.

Veja uma ilustração no diagrama abaixo:

• Uma anotação em um objeto Ingress ou MultiClusterIngress refere-se às CRDs do FrontendConfig. As CRDs do FrontendConfig referem-se a uma política de SSL do Google Cloud.

• Uma anotação em um objeto Serviço ou MultiClusterService refere-se às CRDs BackendConfig. As CRDs BackendConfig especificam configurações personalizadas para a verificação de integridade do serviço de back-end correspondente.

Figura: visão geral do BackendConfig e do FrontendConfig

Como associar o FrontendConfig ao Ingress

O FrontendConfig só pode ser usado com Ingresses externos.

É possível associar um FrontendConfig a um Ingress ou um MultiClusterIngress.

Entrada

Use a anotação networking.gke.io/v1beta1.FrontendConfig:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    networking.gke.io/v1beta1.FrontendConfig: "FRONTENDCONFIG_NAME"
...

Substitua FRONTENDCONFIG_NAME pelo nome da FrontendConfig.

MultiClusterIngress

Use a anotação networking.gke.io/frontend-config:

apiVersion: networking.gke.io/v1
kind: MultiClusterIngress
metadata:
  annotations:
    networking.gke.io/frontend-config: "FRONTENDCONFIG_NAME"
...

Substitua FRONTENDCONFIG_NAME pelo nome da FrontendConfig.

Como associar o BackendConfig ao seu Ingress

É possível usar a anotação cloud.google.com/backend-config ou beta.cloud.google.com/backend-config para especificar o nome de um BackendConfig.

Mesmo BackendConfig para todas as portas de Serviço

Para usar o mesmo BackendConfig para todas as portas, use a chave default na anotação. O controlador de Ingress usa o mesmo BackendConfig sempre que cria um serviço de back-end do balanceador de carga para referenciar uma das portas do Serviço.

É possível usar a chave default para os recursos Ingress e MultiClusterIngress.

apiVersion: v1
kind: Service
metadata:
  annotations:
    cloud.google.com/backend-config: '{"default": "my-backendconfig"}'
...

BackendConfig exclusivo por porta de serviço

Para o Ingress e o MultiClusterIngress, é possível especificar um BackendConfig personalizado para uma ou mais portas usando uma chave que corresponda ao nome ou número da porta. O controlador de entrada usa o BackendConfig específico ao criar um serviço de back-end do balanceador de carga para uma porta de Serviço referenciada.

GKE 1.16-gke.3 e posterior

apiVersion: v1
kind: Service
metadata:
  annotations:
    cloud.google.com/backend-config: '{"ports": {
    "SERVICE_REFERENCE_A":"BACKENDCONFIG_REFERENCE_A",
    "SERVICE_REFERENCE_B":"BACKENDCONFIG_REFERENCE_B"
    }}'
spec:
  ports:
  - name: PORT_NAME_1
    port: PORT_NUMBER_1
    protocol: TCP
    targetPort: 50000
  - name: PORT_NAME_2
    port: PORT_NUMBER_2
    protocol: TCP
    targetPort: 8080
...

Todas as versões compatíveis

apiVersion: v1
kind: Service
metadata:
  annotations:
    cloud.google.com/backend-config: '{"ports": {
      PORT_NAME_1:"BACKENDCONFIG_REFERENCE_A",
      PORT_NAME_2:"BACKENDCONFIG_REFERENCE_B"
    }}'
spec:
  ports:
  - name: PORT_NAME_1
    port: PORT_NUMBER_1
    protocol: TCP
    targetPort: 50000
  - name: PORT_NAME_2
    port: PORT_NUMBER_2
    protocol: TCP
    targetPort: 8080
...

Substitua:

• BACKENDCONFIG_REFERENCE_A: o nome de um BackendConfig.
• BACKENDCONFIG_REFERENCE_B: o nome de um BackendConfig.
• SERVICE_REFERENCE_A: use o valor de PORT_NUMBER_1 ou PORT_NAME_1. Isso ocorre porque a anotação BackendConfig de um serviço pode se referir ao nome da porta (spec.ports[].name) ou ao número da porta (spec.ports[].port).
• SERVICE_REFERENCE_B: use o valor de PORT_NUMBER_2 ou PORT_NAME_2. Isso ocorre porque a anotação BackendConfig de um serviço pode se referir ao nome da porta (spec.ports[].name) ou ao número da porta (spec.ports[].port).

Ao se referir à porta do Serviço por número, você precisa usar o valor port em vez do valor targetPort. O número da porta usado aqui serve apenas para vinculação do BackendConfig. Ele não controla a porta para a qual o balanceador de carga envia sondagens de verificação de tráfego ou de integridade:

• Ao usarbalanceamento de carga nativo de contêiner, o balanceador de carga envia tráfego para um endpoint em um grupo de endpoints da rede (correspondendo a um endereço IP do pod) na porta de Serviço referenciada targetPort (que precisa corresponder a um containerPort para um pod de exibição). Caso contrário, o balanceador de carga enviará tráfego para o endereço IP de um nó no nodePort da porta de serviço referenciada.

• Ao usar um BackendConfig para fornecer uma verificação de integridade do balanceador de carga personalizada, o número da porta usado para a verificação pode ser diferente do número spec.ports[].port do Serviço. Para detalhes sobre números de porta para verificações de integridade, consulte Configuração de verificação de integridade personalizada.

Observação: a porta de serviço associada ao BackendConfig também precisa ser usada no campo de definição do Ingress backend.service.port. Se a porta de serviço não for usada em qualquer objeto de Entrada, o BackendConfig será ignorado.

Como configurar recursos do Ingress por meio de parâmetros do FrontendConfig

A seção a seguir mostra como definir seu FrontendConfig para ativar recursos específicos do Ingress.

Políticas de SSL

As políticas de SSL permitem especificar um conjunto de versões e criptografias TLS que o balanceador de carga usa para encerrar o tráfego HTTPS dos clientes. Primeiro, é necessário criar uma política de SSL fora do GKE. Depois de criá-la, você pode referir-se a ela nas CRDs FrontendConfig.

O campo sslPolicy no FrontendConfig refere-se ao nome de uma política de SSL no mesmo projeto do Google Cloud que o cluster do GKE. Ele anexa a política de SSL ao proxy HTTPS de destino, criado para o balanceador de carga HTTP(S) externo pelo Ingress. O mesmo recurso FrontendConfig e a mesma política SSL podem ser referenciados por vários recursos Ingress. Se uma política SSL referenciada for alterada, a mudança será propagada para os front-ends do Google (GFEs) que alimentam o balanceador de carga HTTP(S) externo criado pelo Ingress.

O manifesto FrontendConfig a seguir ativa uma política de SSL chamada gke-ingress-ssl-policy:

apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
  name: my-frontend-config
spec:
  sslPolicy: gke-ingress-ssl-policy

Redirecionamentos HTTP para HTTPS

Um balanceador de carga HTTP externo pode redirecionar solicitações HTTP não criptografadas para um balanceador de carga HTTPS que usa o mesmo endereço IP. Quando você cria uma entrada com redirecionamentos HTTP para HTTPS ativados, os dois balanceadores de carga são criados automaticamente. As solicitações para o endereço IP externo da Entrada na porta 80 são redirecionadas automaticamente para o mesmo endereço IP externo na porta 443. Essa funcionalidade é criada em redirecionamentos HTTP para HTTPS fornecidos pelo Cloud Load Balancing.

Para oferecer suporte a redirecionamentos HTTP para HTTPS, é preciso configurar uma Entrada para exibir tráfego HTTP e HTTPS. Se HTTP ou HTTPS estiver desativado, o redirecionamento não funcionará.

Os redirecionamentos HTTP para HTTPS são configurados usando o campo redirectToHttps em um recurso personalizado FrontendConfig. Os redirecionamentos são ativados em todo o recurso de entrada para que todos os serviços referenciados pela entrada tenham redirecionamentos HTTPS ativados.

O seguinte manifesto FrontendConfig permite redirecionamentos HTTP para HTTPS. Defina o campo spec.redirectToHttps.enabled como true para ativar os redirecionamentos HTTPS. O campo spec.responseCodeName é opcional. Se ele for omitido, um redirecionamento Moved Permanently 301 será usado.

apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
  name: my-frontend-config
spec:
  redirectToHttps:
    enabled: true
    responseCodeName: RESPONSE_CODE

Substitua RESPONSE_CODE por um dos seguintes:

• MOVED_PERMANENTLY_DEFAULT para retornar um código de resposta de redirecionamento 301 (o padrão, se responseCodeName não for especificado).
• FOUND para retornar um código de resposta de redirecionamento 302.
• SEE_OTHER para retornar um código de resposta de redirecionamento 303.
• TEMPORARY_REDIRECT para retornar um código de resposta de redirecionamento do 307.
• PERMANENT_REDIRECT para retornar um código de resposta de redirecionamento 308.

Quando os redirecionamentos estão ativados, o controlador de entrada cria um balanceador de carga, conforme mostrado no diagrama a seguir:

Para validar se o redirecionamento está funcionando, use um comando curl:

curl http://IP_ADDRESS

Substitua IP_ADDRESS pelo endereço IP da Entrada.

A resposta mostra o código de resposta de redirecionamento que você configurou. Por exemplo, o exemplo a seguir refere-se a um FrontendConfig configurado com um redirecionamento 301: MovedPermanently:

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://35.244.160.59/">here</A>.</BODY></HTML>

Como configurar recursos do Ingress por meio de parâmetros BackendConfig

As seções a seguir mostram como configurar o BackendConfig para ativar recursos específicos do Ingress. As alterações em um recurso BackendConfig são constantemente reconciliadas. Portanto, você não precisa excluir e recriar seu Ingress para ver se as alterações do BackendConfig são refletidas.

Para informações sobre as limitações do BackendConfig, consulte a seção de limitações.

Tempo limite do serviço de back-end

É possível usar um BackendConfig para definir um tempo limite do serviço de back-end em segundos. Se você não especificar um valor, o valor padrão será de 30 segundos.

O manifesto BackendConfig a seguir especifica um tempo limite de 40 segundos:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  timeoutSec: 40

Cloud CDN

É possível ativar o Cloud CDN usando um BackendConfig.

Observação: não é possível ativar o IAP e o Cloud CDN em um BackendConfig. Se o BackendConfig não tiver um bloco iap, todas as configurações de IAP existentes no serviço de back-end serão herdadas.

O manifesto BackendConfig a seguir mostra todos os campos disponíveis ao ativar o Cloud CDN:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  cdn:
    enabled: CDN_ENABLED
    cachePolicy:
      includeHost: INCLUDE_HOST
      includeProtocol: INCLUDE_PROTOCOL
      includeQueryString: INCLUDE_QUERY_STRING
      queryStringBlacklist: QUERY_STRING_DENYLIST
      queryStringWhitelist: QUERY_STRING_ALLOWLIST
    cacheMode: CACHE_MODE
    clientTtl: CLIENT_TTL
    defaultTtl: DEFAULT_TTL
    maxTtl: MAX_TTL
    negativeCaching: NEGATIVE_CACHING
    negativeCachingPolicy:
      code: NEGATIVE_CACHING_CODE
      ttl: NEGATIVE_CACHING_TTL
    requestCoalescing: REQ_COALESCING
    serveWhileStale: SERVE_WHILE_STALE
    signedUrlCacheMaxAgeSec: SIGNED_MAX_AGE
    signedUrlKeys:
      keyName: KEY_NAME
      keyValue: KEY_VALUE
      secretName: SECRET_NAME

Substitua:

• CDN_ENABLED: se definido como true, o Cloud CDN estará ativado para este back-end do Ingress.
• INCLUDE_HOST: se definido como true, as solicitações para hosts diferentes serão armazenadas em cache separadamente.
• INCLUDE_PROTOCOL: se definido como true, as solicitações HTTP e HTTPS serão armazenadas em cache separadamente.
• INCLUDE_QUERY_STRING: se definido como true, os parâmetros da string de consulta serão incluídos na chave de cache de acordo com queryStringBlacklist ou queryStringWhitelist. Se nenhum dos dois estiver configurado, toda a string de consulta será incluída. Se definido como false, toda a string de consulta será excluída da chave de cache.
• QUERY_STRING_DENYLIST: especifique uma matriz de strings com os nomes dos parâmetros da string de consulta a serem excluídos das chaves de cache. Todos os outros parâmetros são incluídos. Você pode especificar queryStringBlacklist ou queryStringWhitelist, mas não ambos.
• QUERY_STRING_ALLOWLIST: especifique uma matriz de strings com os nomes dos parâmetros da string de consulta a serem incluídos nas chaves de cache. Todos os outros parâmetros são excluídos. Você pode queryStringBlacklist ou queryStringWhitelist, mas não ambos.

Os campos a seguir são compatíveis apenas com as versões 1.23.3-gke.900 e posteriores usando a Entrada do GKE. Eles não são compatíveis com a entrada de vários clusters:

• CACHE_MODE: o modo de cache.
• CLIENT_TTL, DEFAULT_TTL e MAX_TTL: configuração de TTL. Para mais informações, consulte Como usar configurações e modificações de TTL.
• NEGATIVE_CACHING: se definido como true, o armazenamento em cache negativo será ativado. Para mais informações, consulte Como usar o armazenamento em cache negativo.
• NEGATIVE_CACHING_CODE e NEGATIVE_CACHING_TTL: configuração de armazenamento em cache negativo. Para mais informações, consulte Como usar o armazenamento em cache negativo.
• REQ_COALESCING: se definido como true, o recolhimento será ativado. Para mais informações, consulte Recolhimento de solicitações (coalescência).
• SERVE_WHILE_STALE: tempo, em segundos, após a expiração da resposta, que o Cloud CDN continua exibindo uma versão desatualizada. Para mais informações, consulte Como exibir conteúdo desatualizado.
• SIGNED_MAX_AGE: o tempo máximo de resposta pode ser armazenado em cache, em segundos. Para mais informações, consulte Como personalizar opcionalmente o tempo máximo de cache.
• KEY_NAME, KEY_VALUE e SECRET_NAME: configuração de chave de URL assinado. Para mais informações, consulte Como criar chaves de solicitação assinadas.

Expanda a seção a seguir para ver um exemplo que implanta o Cloud CDN por meio do Ingress e depois valida que o conteúdo do aplicativo está sendo armazenado em cache.

Exemplo do Cloud CDN

Para usar um BackendConfig e configurar o Cloud CDN, execute as seguintes tarefas:

1. Crie um namespace dedicado para este exemplo ser executado em:
   

   kubectl create namespace cdn-how-to
   

2. Crie um arquivo de implantação chamado my-deployment.yaml com base no manifesto de implantação a seguir. Esse manifesto declara que você quer executar duas réplicas do aplicativo da Web ingress-gce-echo-amd64.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     namespace: cdn-how-to
     name: my-deployment
   spec:
     selector:
       matchLabels:
         purpose: demonstrate-cdn
     replicas: 2
     template:
       metadata:
         labels:
           purpose: demonstrate-cdn
       spec:
         containers:
         - name: echo-amd64
           image: us-docker.pkg.dev/google-samples/containers/gke/hello-app-cdn:1.0
   

3. Crie o recurso de implantação:

   kubectl apply -f my-deployment.yaml
   

4. Crie um BackendConfig chamado my-backendconfig.yaml com base no manifesto BackendConfig a seguir. No manifesto, uma política de cache do Cloud CDN é especificada e é declarado que o Cloud CDN precisa estar ativado:

     apiVersion: cloud.google.com/v1
     kind: BackendConfig
     metadata:
       namespace: cdn-how-to
       name: my-backendconfig
     spec:
       cdn:
         enabled: true
         cachePolicy:
           includeHost: true
           includeProtocol: true
           includeQueryString: false
   

5. Crie o recurso BackendConfig:

   kubectl apply -f my-backendconfig.yaml
   

6. Crie um arquivo chamado my-service.yaml com base no manifesto de Serviço a seguir:

   apiVersion: v1
   kind: Service
   metadata:
     namespace: cdn-how-to
     name: my-service
     labels:
       purpose: demonstrate-cdn
     annotations:
       cloud.google.com/backend-config: '{"ports": {"80":"my-backendconfig"}}'
   spec:
     type: NodePort
     selector:
       purpose: demonstrate-cdn
     ports:
     - port: 80
       protocol: TCP
       targetPort: 8080
   

7. Crie o recurso Serviço:

   kubectl apply -f my-service.yaml
   

8. Crie um endereço IP reservado:

   gcloud compute addresses create cdn-how-to-address --global
   

9. Crie um arquivo chamado my-ingress.yaml com base no manifesto do Ingress a seguir:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     namespace: cdn-how-to
     name: my-ingress
     annotations:
       kubernetes.io/ingress.global-static-ip-name: "cdn-how-to-address"
   spec:
     rules:
     - http:
         paths:
         - path: /*
           pathType: ImplementationSpecific
           backend:
             service:
               name: my-service
               port:
                 number: 80
   

10. Crie o recurso Ingress:

    kubectl apply -f my-ingress.yaml
    

11. Aguarde cerca de dez minutos para que o controlador de Entrada do Kubernetes configure um balanceador de carga do Google Cloud e, em seguida, recupere o endereço IP usado pelas regras de encaminhamento do balanceador de carga do recurso de Entrada.

    kubectl describe ingress my-ingress --namespace=cdn-how-to | grep "Address"
    

    Saída:

    Address:         ADDRESS
    

    ADDRESS é o endereço IP externo do Ingress.

Validar o armazenamento em cache do Cloud CDN

Para validar se o conteúdo está sendo armazenado em cache, digite este comando curl duas vezes:

curl -v ADDRESS/?cache=true

Substitua ADDRESS pelo endereço IP externo do Ingress.

A saída mostra os cabeçalhos e o corpo de resposta. Nos cabeçalhos, é possível ver que o conteúdo foi armazenado em cache. O cabeçalho Age informa por quantos segundos o conteúdo foi armazenado no cache:

HTTP/1.1 200 OK
Date: Fri, 25 Jan 2019 02:34:08 GMT
Content-Length: 70
Content-Type: text/plain; charset=utf-8
Via: 1.1 google
Cache-Control: max-age=86400,public
Age: 2716

Hello, world!
Version: 1.0.0
Hostname: my-deployment-7f589cc5bc-l8kr8
...

Se você achar que seu conteúdo não está sendo armazenado em cache, verifique se seu aplicativo está configurado corretamente para ativar o armazenamento em cache do conteúdo. Para mais informações, consulte Conteúdo armazenável em cache.

Limpar

Para evitar cobranças indesejadas na sua conta, libere o endereço IP estático reservado:

gcloud compute addresses delete cdn-how-to-address --global

Tempo limite de diminuição da conexão

É possível configurar o tempo limite de diminuição da conexão usando um BackendConfig. O tempo limite de diminuição da conexão é o tempo, em segundos, de espera pela redução das conexões. Para a duração especificada do tempo limite, as solicitações atuais do back-end removido têm tempo para serem concluídas. O balanceador de carga não envia novas solicitações para o back-end removido. Após a duração do tempo limite, todas as conexões restantes com o back-end são fechadas. A duração do tempo limite pode ser de 0 a 3.600 segundos. O valor padrão é 0, o que também desativa a diminuição da conexão.

Aviso: configurar um valor alto para drainingTimeoutSec (por exemplo, 3.600 segundos) em uma Entrada ou Serviço que usa grupos de instâncias causará atrasos proporcionais à duração definida em drainingTimeoutSec durante a atualização de outros recursos de Entrada no cluster. Isso ocorre porque todos os recursos de Entrada baseados em grupo de instâncias em um cluster compartilham o mesmo grupo de instâncias. Se você precisar de um valor alto, considere usar Serviços apoiados por grupos de endpoints de rede.

O manifesto BackendConfig a seguir especifica um tempo limite de diminuição de conexão de 60 segundos:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  connectionDraining:
    drainingTimeoutSec: 60

Configuração de verificação de integridade personalizada

O GKE usa várias maneiras para configurar as verificações de integridade do balanceador de carga do Google Cloud ao implantar por meio do Ingress. Para saber mais sobre como o Ingress do GKE implanta verificações de integridade, consulte Verificações de integridade do Ingress.

Um BackendConfig permite controlar com precisão as configurações de verificação de integridade do balanceador de carga.

Observação: o Ingress não é compatível com gRPC para configurações de verificação de integridade personalizadas.

É possível configurar vários serviços do GKE para referenciar o mesmo BackendConfig de um modelo reutilizável. Para os parâmetros healthCheck, uma verificação de integridade exclusiva do Google Cloud é criada para cada serviço de back-end correspondente a cada serviço do GKE.

O manifesto BackendConfig a seguir mostra todos os campos disponíveis ao se configurar uma verificação de integridade do BackendConfig:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  healthCheck:
    checkIntervalSec: INTERVAL
    timeoutSec: TIMEOUT
    healthyThreshold: HEALTH_THRESHOLD
    unhealthyThreshold: UNHEALTHY_THRESHOLD
    type: PROTOCOL
    requestPath: PATH
    port: PORT

Substitua:

• INTERVAL: especifique o check-interval, em segundos, para cada sonda de verificação de integridade. Esse é o momento entre o início da verificação de uma sonda e o começo da próxima verificação. Se você omitir esse parâmetro, será usado o padrão de cinco segundos do Google Cloud. Para mais detalhes sobre a implementação, consulte Várias sondagens e frequência.
• TIMEOUT: especifique o tempo que o Google Cloud aguarda por uma resposta a uma sondagem. O valor de TIMEOUT precisa ser menor ou igual ao valor de INTERVAL. As unidades são informadas em segundos. Cada sondagem requer que um código de resposta HTTP 200 (OK) seja entregue antes do tempo limite da sondagem.
• HEALTH_THRESHOLD e UNHEALTHY_THRESHOLD: especifique o número de tentativas de conexão sequencial que precisam ser bem-sucedidas ou reprovadas em pelo menos uma sondagem para alterar o estado de integridade de íntegra para não íntegra ou vice-versa. Se você omitir um desses parâmetros, o Google Cloud usará o valor padrão 2.
• PROTOCOL: especifique um protocolo usado pelos sistemas de sondagem para verificação de integridade. O BackendConfig só permite a criação de verificações de integridade usando os protocolos HTTP, HTTPS ou HTTP2. Para mais informações, consulte os critérios de sucesso para HTTP, HTTPS e HTTP/2. Não é possível omitir esse parâmetro.
• PATH: para verificações de integridade HTTP, HTTPS ou HTTP2, especifique o request-path ao qual o sistema de sondagem precisa se conectar. Se você omitir esse parâmetro, o Google Cloud usará o padrão /.

• PORT: um BackendConfig é compatível apenas com a especificação da porta de verificação de integridade do balanceador de carga usando um número de porta. Se você omitir esse parâmetro, o Google Cloud usará o valor padrão 80.

  • Ao usar o balanceamento de carga nativo de contêiner, você precisa selecionar uma porta correspondente a uma containerPort de um pod de exibição, seja containerPort referenciado ou não por um targetPort do Serviço. Como o balanceador de carga envia sondagens diretamente para o endereço IP do pod, você não está limitado às containerPorts referenciadas por uma targetPort do Serviço. Os sistemas de sondagem de verificação de integridade se conectam ao endereço IP de um pod de exibição na porta especificada.

  • Para back-ends de grupos de instâncias, você precisa selecionar uma porta que corresponda a um nodePort exposto pelo Serviço. Os sistemas de sondagem de verificação de integridade se conectam a cada nó nessa porta.

Para configurar a Entrada do GKE com uma verificação de integridade HTTP personalizada, consulte Entrada do GKE com verificação de integridade HTTP personalizada.

Política de segurança de Entrada do Google Cloud Armor

As políticas de segurança do Google Cloud Armor ajudam a proteger seus aplicativos com balanceamento de carga contra ataques baseados na Web. Depois de configurar uma política de segurança do Google Cloud Armor, você pode referenciá-la usando um BackendConfig.

Adicione o nome da política de segurança ao BackendConfig. O manifesto BackendConfig a seguir especifica uma política de segurança chamada example-security-policy:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  namespace: cloud-armor-how-to
  name: my-backendconfig
spec:
  securityPolicy:
    name: "example-security-policy"

Aviso: não modifique diretamente os recursos BackendService no Compute Engine para anexar as políticas do Google Cloud Armor aos serviços de back-end gerenciados pelo GKE.

Duas fontes de informações

Embora configuradas pelo GKE, as APIs BackendService do Compute Engine ainda podem ser usadas para modificar diretamente qual política de segurança aplicar. Isso cria duas fontes de verdade: GKE e Compute Engine. O comportamento do controlador de entrada do GKE em resposta ao campo securityPolicy em BackendConfig está documentado na tabela abaixo. Para evitar conflitos e comportamentos inesperados, recomendamos usar o BackendConfig do GKE para gerenciar qual política de segurança usar.

Campo BackendConfig	Valor	Comportamento
spec.securityPolicy.name	CloudArmorPolicyName	O controlador de entrada do GKE define a política do Google Cloud Armor chamada CloudArmorPolicyName como o balanceador de carga. O controlador de entrada do GKE substitui qualquer política que tenha sido definida anteriormente.
spec.securityPolicy.name	String vazia ("")	O controlador de entrada do GKE remove qualquer política configurada do Google Cloud Armor do balanceador de carga.
spec.securityPolicy	nil	O controlador de entrada do GKE usa a configuração definida no objeto BackendService configurado por meio da API Compute Engine usando o console do Google Cloud, a gcloud CLI ou o Terraform.

Para configurar a Entrada do GKE com a proteção do Google Cloud Armor, consulte Entrada ativada pelo Google Cloud Armor.

Geração de registros de acesso HTTP

Observação: a geração de registros de acesso para a entrada Multi Cluster assume o padrão "on" em todas as versões anteriores ao GKE 1.18, mas é exposta como um campo configurável a partir da versão 1.16. 8-gke.10 A geração de registros de acesso é desativada por padrão nos outros tipos de entrada.

O Ingress pode registrar todas as solicitações HTTP de clientes no Cloud Logging. É possível ativar e desativar a geração de registros de acesso usando BackendConfig, além de definir a taxa de amostragem da geração de registros de acesso.

Para configurar a geração de registros de acesso, use o campo logging no BackendConfig. Se logging for omitido, a geração de registros de acesso adotará o comportamento padrão. Isso depende da versão do GKE.

É possível configurar os seguintes campos:

• enable: se for definido como true, a geração de registros de acesso será ativada para este Ingress e os registros estarão disponíveis no Cloud Logging. Caso contrário, a geração de registros de acesso será desativada para este Ingress.
• sampleRate: especifique um valor de 0,0 a 1,0, em que 0,0 significa que nenhum pacote é registrado e 1,0 significa que 100% dos pacotes são registrados. Este campo só é relevante se enable estiver definido como true. sampleRate é um campo opcional, mas se estiver configurado, enable: true também precisará ser definido. Caso contrário, ele será interpretado como enable: false.

O manifesto BackendConfig a seguir ativa a geração de registros de acesso e define a taxa de amostra como 50% das solicitações HTTP para um determinado recurso Ingress:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  logging:
    enable: true
    sampleRate: 0.5

Identity-Aware Proxy

Se quiser configurar o BackendConfig para Identity-Aware Proxy IAP, você precisa especificar os valores enabled e secretName para seu bloco iap no BackendConfig. Para especificar esses valores, verifique se você tem a permissão compute.backendServices.update.

Observação: não é possível ativar o IAP e o Cloud CDN em um BackendConfig. Se o BackendConfig não tiver um bloco iap, todas as configurações de IAP existentes no serviço de back-end serão herdadas.

O manifesto BackendConfig a seguir ativa o Identity-Aware Proxy:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name:  my-backendconfig
spec:
  iap:
    enabled: true
    oauthclientCredentials:
      secretName: my-secret

Ativar o IAP com o cliente OAuth gerenciado pelo Google

A partir do GKE 1.29.2-gke.1035000, o IAP pode ser configurado para usar o cliente OAuth gerenciado pelo Google com um BackendConfig. Para decidir entre usar o cliente OAuth do Google ou um cliente OAuth personalizado, consulte Quando usar uma configuração de OAuth personalizada na documentação do IAP.

Para ativar o IAP com o cliente OAuth gerenciado pelo Google, não forneça as OAuthCredentials no BackendConfig. Para os usuários que já configuraram o IAP usando OAuthCredentials, não há caminho de migração para usar o cliente OAuth gerenciado pelo Google. Será necessário recriar o back-end. Remova o serviço da Entrada e anexe-o novamente. Sugerimos realizar essa operação durante uma janela de manutenção, porque ela causará inatividade. No caminho de migração oposto, é possível mudar do OAuthClient gerenciado pelo Google para o OAuthCredentials.

O manifesto BackendConfig a seguir ativa o Identity-Aware Proxy com o cliente OAuth gerenciado pelo Google:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name:  my-backendconfig
spec:
  iap:
    enabled: true

Para instruções completas, consulte Como ativar o IAP para o GKE na documentação do IAP.

Identity-Aware Proxy com Entrada interna

Para configurar a entrada interna do IAP, use o nível Premium. Se você não usar o nível Premium, não será possível visualizar ou criar balanceadores de carga de aplicativo internos com o Identity-Aware Proxy. Também é necessário ter uma assinatura do BeyondCorp Enterprise para usar o Ingress interno no IAP.

Para configurar a Entrada segura do GKE com autenticação baseada no Identity-Aware Proxy, consulte o exemplo, Entrada ativada pelo IAP.

Afinidade da sessão

É possível usar um BackendConfig para definir a afinidade da sessão como IP do cliente ou cookie gerado.

Importante: use um cluster nativo de VPC se quiser configurar a afinidade de sessão. A afinidade da sessão é útil apenas para serviços apoiados por grupos de endpoints da rede, e eles exigem um cluster nativo de VPC.

Afinidade de IP do cliente

Se quiser usar um BackendConfig para definir a afinidade de IP do cliente, defina affinityType como "CLIENT_IP". Veja no exemplo a seguir:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  sessionAffinity:
    affinityType: "CLIENT_IP"

Afinidade de cookie gerado

Se quiser usar um BackendConfig para configurar a afinidade de cookie gerado, defina affinityType como GENERATED_COOKIE no manifesto do BackendConfig. Também é possível usar affinityCookieTtlSec para definir o período de tempo que o cookie permanece ativo.

O seguinte manifesto define o tipo de afinidade para cookie gerado e dá aos cookies um TTL de 50 segundos:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  sessionAffinity:
    affinityType: "GENERATED_COOKIE"
    affinityCookieTtlSec: 50

Cabeçalhos de solicitação definidos pelo usuário

É possível usar um BackendConfig para configurar cabeçalhos de solicitação definidos pelo usuário. O balanceador de carga adiciona os cabeçalhos especificados às solicitações que ele encaminha para os back-ends.

Para ativá-los, especifique uma lista de cabeçalhos na propriedade customRequestHeaders do recurso BackendConfig. Especifique cada cabeçalho como uma string header-name:header-value.

O manifesto BackendConfig a seguir adiciona três cabeçalhos de solicitação:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  customRequestHeaders:
    headers:
    - "X-Client-Region:{client_region}"
    - "X-Client-City:{client_city}"
    - "X-Client-CityLatLong:{client_city_lat_long}"

Cabeçalhos de resposta personalizados

Para ativar cabeçalhos de resposta personalizados, especifique uma lista de cabeçalhos na propriedade customResponseHeaders do recurso BackendConfig. Especifique cada cabeçalho como uma string header-name:header-value.

O manifesto do BackendConfig a seguir é um exemplo para adicionar um cabeçalho de resposta do HTTP Strict Transport Security (HSTS):

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  customResponseHeaders:
    headers:
    - "Strict-Transport-Security: max-age=28800; includeSubDomains"

Exercício: como definir tempos limites do Ingress usando um serviço de back-end

O exercício a seguir mostra as etapas necessárias para configurar tempos limite e diminuição da conexão usando um Ingress com um recurso BackendConfig.

Para configurar as propriedades de back-end de um Ingress, conclua as tarefas a seguir:

1. Crie uma implantação.
2. Crie um BackendConfig.
3. Crie um serviço e associe uma das respectivas portas ao BackendConfig.
4. Crie um objeto Ingress e associe-o ao par (serviço, porta).
5. Valide as propriedades do serviço de back-end.
6. Limpeza.

Como criar uma implantação

Antes de criar um BackendConfig e um serviço, você precisa criar uma implantação.

O exemplo de manifesto a seguir é para uma implantação chamada my-deployment.yaml:

# my-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  selector:
    matchLabels:
      purpose: bsc-config-demo
  replicas: 2
  template:
    metadata:
      labels:
        purpose: bsc-config-demo
    spec:
      containers:
      - name: hello-app-container
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

Crie a implantação executando o seguinte comando:

kubectl apply -f my-deployment.yaml

Como criar um BackendConfig

Use o BackendConfig para especificar os recursos do Ingress que você quer usar.

Esse manifesto BackendConfig, chamado my-backendconfig.yaml, especifica:

• um tempo limite de 40 segundos;
• um tempo limite de diminuição da conexão de 60 segundos.

# my-backendconfig.yaml
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  timeoutSec: 40
  connectionDraining:
    drainingTimeoutSec: 60

Crie o BackendConfig executando o seguinte comando:

kubectl apply -f my-backendconfig.yaml

Crie um serviço

Um BackendConfig corresponde a uma única combinação Service-Port, mesmo que um serviço tenha várias portas. Cada porta pode ser associada a uma única CRD BackendConfig. Se uma porta do serviço for referenciada por um Ingress, e se ela estiver associada a um BackendConfig, o serviço de back-end de balanceamento de carga HTTP(S) fará parte da configuração a partir do BackendConfig.

Veja a seguir um exemplo de manifesto de serviço chamado my-service.yaml:

# my-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
  labels:
    purpose: bsc-config-demo
  annotations:
    cloud.google.com/backend-config: '{"ports": {"80":"my-backendconfig"}}'
    cloud.google.com/neg: '{"ingress": true}'
spec:
  type: ClusterIP
  selector:
    purpose: bsc-config-demo
  ports:
  - port: 80
    protocol: TCP
    targetPort: 8080

A anotação cloud.google.com/backend-config especifica um mapeamento entre portas e objetos BackendConfig. Em my-service.yaml:

• Qualquer pod que tenha o rótulo purpose: bsc-config-demo é um membro do serviço.
• A porta TCP 80 do Serviço está associada a um BackendConfig chamado my-backendconfig. A anotação cloud.google.com/backend-config especifica isso.
• Uma solicitação enviada para a porta 80 do serviço é encaminhada para um dos pods de membro na porta 8080.

Para criar o Serviço, execute este comando:

kubectl apply -f my-service.yaml

Como criar um Ingress

Veja a seguir um manifesto de entrada chamado my-ingress.yaml. Neste exemplo, as solicitações recebidas são roteadas para a porta 80 do serviço chamada my-service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - http:
      paths:
      - path: /*
        pathType: ImplementationSpecific
        backend:
          service:
            name: my-service
            port:
              number: 80

Para criar o Ingress, execute o seguinte comando:

kubectl apply -f my-ingress.yaml

Aguarde alguns minutos para que o controlador de Ingress configure um balanceador de carga de aplicativo externo e um serviço de back-end associado. Quando isso for concluído, você configurou o Ingress para usar um tempo limite de 40 segundos e um tempo limite de diminuição de conexão de 60 segundos.

Como validar as propriedades do serviço de back-end

Você pode validar se as configurações do balanceador de carga foram aplicadas corretamente por meio do BackendConfig. Para fazer isso, identifique o serviço de back-end que o Ingress implantou e inspecione as configurações para confirmar se eles correspondem aos manifestos de implantação.

Primeiro, descreva o recurso my-ingress e filtre a anotação que lista os serviços de back-end associados ao Ingress. Exemplo:

kubectl describe ingress my-ingress | grep ingress.kubernetes.io/backends

A resposta será assim:

ingress.kubernetes.io/backends: '{"k8s1-27fde173-default-my-service-80-8d4ca500":"HEALTHY","k8s1-27fde173-kube-system-default-http-backend-80-18dfe76c":"HEALTHY"}

A saída fornece informações sobre os serviços de back-end. Por exemplo, essa anotação contém dois serviços de back-end:

• "k8s1-27fde173-default-my-service-80-8d4ca500":"HEALTHY" fornece informações sobre o serviço de back-end associado ao serviço my-service do Kubernetes.
  • k8s1-27fde173 é um hash usado para descrever o cluster;
  • default é o namespace do Kubernetes;
  • HEALTHY indica que o back-end está íntegro.
• "k8s1-27fde173-kube-system-default-http-backend-80-18dfe76c":"HEALTHY" fornece informações sobre o serviço de back-end associado ao back-end padrão (Servidor 404);
  • k8s1-27fde173 é um hash usado para descrever o cluster;
  • kube-system é o namespace;
  • default-http-backend é o nome do serviço do Kubernetes;
  • 80 é a porta do host;
  • HEALTHY indica que o back-end está íntegro.

Em seguida, inspecione o serviço de back-end associado a my-service usando gcloud. Filtre por "drainingTimeoutSec" e "timeoutSec" para confirmar se eles foram definidos no plano de controle do balanceador de carga do Google Cloud. Exemplo:

# Optionally, set a variable
export BES=k8s1-27fde173-default-my-service-80-8d4ca500

# Filter for drainingTimeoutSec and timeoutSec
gcloud compute backend-services describe ${BES} --global | grep -e "drainingTimeoutSec" -e "timeoutSec"

Saída:

  drainingTimeoutSec: 60
  timeoutSec: 40

Ver drainingTimeoutSec e timeoutSec na saída confirma que os valores foram definidos corretamente por meio do BackendConfig.

Limpar

Para evitar cobranças indesejadas na sua conta, exclua os objetos do Kubernetes que você criou para este exercício:

kubectl delete ingress my-ingress
kubectl delete service my-service
kubectl delete backendconfig my-backendconfig
kubectl delete deployment my-deployment

Limitações do BackendConfig

O BackendConfigs tem as seguintes limitações:

• Um par (serviço, port) pode consumir apenas um BackendConfig, mesmo que vários objetos Ingress façam referência ao (serviço, port). Isso significa que todos os objetos Entrada que se referem ao mesmo serviço ou porta precisam usar a mesma configuração para o Google Cloud Armor, o IAP e o Cloud CDN.

• O IAP e o Cloud CDN não podem ser ativados para o mesmo serviço de back-end de balanceamento de carga HTTP(S). Isso significa que o IAP e o Cloud CDN não podem ser configurados no mesmo BackendConfig.

• Você precisa usar o kubectl 1.7 ou posterior para interagir com o BackendConfig.

Como remover a configuração especificada em um front-end ou BackendConfig

Para revogar um recurso do Ingress, desative explicitamente a configuração do recurso nas CRDs do FrontendConfig ou BackendConfig. O controlador do Ingress reconcilia apenas as configurações especificadas nessas CRDs.

Para limpar ou desativar uma configuração ativada anteriormente, defina o valor do campo como uma string vazia ("") ou um valor booleano false, dependendo do tipo de campo.

O manifesto BackendConfig a seguir desativa uma política de segurança do Google Cloud Armor e o Cloud CDN:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  cdn:
    enabled: false
  securityPolicy:
    name: ""

Como excluir um FrontendConfig ou BackendConfig

FrontendConfig

Para excluir um FrontendConfig, siga estas etapas:

1. Remova o nome do front-end da anotação networking.gke.io/v1beta1.FrontendConfig no manifesto do Ingress.

2. Aplique o manifesto do Ingress alterado ao cluster. Por exemplo, use kubectl apply.

3. Exclua o FrontendConfig. Por exemplo, use kubectl delete frontendconfig config my-frontendconfig.

Cuidado: não exclua um objeto FrontendConfig antes de remover o nome dele da anotação networking.gke.io/v1beta1.FrontendConfig e aplicar a atualização do manifesto Ingress. Se você fizer isso, a configuração não será removida do serviço de back-end de balanceamento de carga HTTP(S). Além disso, você verá erros como eventos do Kubernetes no objeto Ingress.

BackendConfig

Para excluir um BackedConfig, siga estas etapas:

1. Remova o nome do BackendConfig da anotação cloud.google.com/backend-config no manifesto Serviço.

2. Aplique o manifesto Serviço alterado ao cluster. Por exemplo, use kubectl apply.

3. Exclua o BackendConfig. Por exemplo, use kubectl delete backendconfig my-backendconfig.

Cuidado: não exclua um objeto BackendConfig antes de remover seu nome da anotação cloud.google.com/backend-config e aplicar o manifesto Serviço atualizado. Se você fizer isso, a configuração não será removida do serviço de back-end de balanceamento de carga HTTP(S). Além disso, você verá erros como eventos do Kubernetes no objeto Ingress.

Solução de problemas

É possível detectar configurações incorretas comuns usando a ferramenta de diagnóstico de entrada. Verifique também se todas as verificações de integridade estão configuradas corretamente.

BackendConfig não encontrado

Esse erro ocorre quando um BackendConfig de uma porta de serviço é especificado na anotação de serviço, mas o recurso BackendConfig real não é encontrado.

Para avaliar um evento do Kubernetes, execute o seguinte comando:

kubectl get event

O exemplo de saída a seguir indica que seu BackendConfig não foi encontrado:

KIND    ... SOURCE
Ingress ... loadbalancer-controller

MESSAGE
Error during sync: error getting BackendConfig for port 80 on service "default/my-service":
no BackendConfig for service port exists

Para resolver esse problema, verifique se você não criou o recurso BackendConfig no namespace errado ou se digitou incorretamente a referência na anotação do serviço.

Política de segurança de entrada não encontrada

Depois que o objeto de Entrada é criado, se a política de segurança não estiver adequadamente associada ao serviço LoadBalancer, avalie o evento do Kubernetes para ver se há um erro de configuração. Se o BackendConfig especificar uma política de segurança que não existe, um evento de aviso vai ser emitido periodicamente.

Para avaliar um evento do Kubernetes, execute o seguinte comando:

kubectl get event

O exemplo de saída a seguir indica que sua política de segurança não foi encontrada:

KIND    ... SOURCE
Ingress ... loadbalancer-controller

MESSAGE
Error during sync: The given security policy "my-policy" does not exist.

Para resolver esse problema, especifique o nome correto da política de segurança no BackendConfig.

Como solucionar erros da série 500 com NEGs durante o escalonamento de cargas de trabalho no GKE

Sintoma:

Ao usar NEGs provisionados pelo GKE para o balanceamento de carga, podem ocorrer erros 502 ou 503 nos serviços durante a redução da escala vertical das cargas de trabalho. Os erros 502 ocorrem quando os pods são encerrados antes do encerramento das conexões atuais, enquanto os erros 503 ocorrem quando o tráfego é direcionado para pods excluídos.

Esse problema pode afetar os clusters ao empregar produtos de balanceamento de carga gerenciado do GKE que usam NEGs, como NEGs de gateway, de entrada e independentes. Se você escalona as cargas de trabalho com frequência, seu cluster corre mais risco de ser afetado.

Diagnóstico:

Remover um pod no Kubernetes sem diminuir a conexão do endpoint dele e removê-lo do NEG primeiro resulta em erros da série 500. Para evitar problemas durante o encerramento do pod, considere a ordem das operações. As imagens a seguir mostram cenários em que BackendService Drain Timeout não está definido e BackendService Drain Timeout está definido com BackendConfig.

Observação a resolução a seguir não é eficaz para resolver outros erros da série 500 resultantes de preempções de pod ou nó no GKE, especialmente no caso do GKE com VMs spot e VMs preemptivas.

Cenário 1: BackendService Drain Timeout não está definido.

A imagem a seguir exibe um cenário em que BackendService Drain Timeout não está configurado.

Cenário 2: BackendService Drain Timeout está definido.

A imagem a seguir exibe um cenário em que BackendService Drain Timeout está definido.

O momento exato em que os erros da série 500 ocorrem depende dos seguintes fatores:

• Latência de remoção da API NEG: representa o tempo atual necessário para finalizar a operação de remoção no Google Cloud. Isso é afetado por vários fatores externos ao Kubernetes, como o tipo de balanceador de carga e a zona específica.

• Latência de diminuição da conexão: representa o tempo que o balanceador de carga leva a fim de começar a direcionar o tráfego para longe de uma parte específica do sistema. Depois que a diminuição da conexão é iniciada, o balanceador de carga para de enviar novas solicitações ao endpoint. No entanto, ainda há uma latência no acionamento dessa diminuição (latência de diminuição da conexão), que pode causar erros 503 temporários caso o pod não exista mais.

• Configuração da verificação de integridade: limites de verificação de integridade mais precisos reduzem a duração dos erros 503, porque podem sinalizar ao balanceador de carga que ele deve interromper o envio de solicitações aos endpoints, mesmo que a operação de remoção não tenha sido concluída.

• Período de carência para o encerramento: determina o tempo máximo que um pod tem para ser encerrado. No entanto, lembre-se de que um pod pode ser encerrado antes do término desse período. Se um pod demorar mais do que isso para ser encerrado, o encerramento ocorrerá de modo forçado ao final do período. Essa configuração é feita no pod e precisa ser realizada na definição da carga de trabalho.

Possível resolução:

Para evitar erros 5XX, aplique as configurações a seguir. Os valores de tempo limite são sugestões, e talvez seja necessário ajustá-los para aplicativos específicos. Na seção a seguir, você encontra instruções sobre o processo de personalização.

A seguinte imagem mostra como manter o pod ativo com preStopHook:

Para evitar erros da série 500, siga estas etapas:

1. Defina BackendService Drain Timeout para o serviço como 1 minuto.

   Observação: se o tempo médio de solicitação for maior que 30 segundos, consulte Personalizar tempos limite para personalizar BackendService Drain Timeout.

   • Para usuários do Ingress, consulte Definir o tempo limite no BackendConfig.

   • Para usuários de gateway, consulte Configurar o tempo limite no GCPBackendPolicy.

   • Se você gerencia BackendServices diretamente usando NEGs independentes, consulte Definir o tempo limite diretamente no serviço de back-end.

2. Estenda terminationGracePeriod no pod.

   Defina terminationGracePeriodSeconds no pod como 3,5 minutos. Quando combinado com as configurações recomendadas, isso permite que os pods tenham uma janela de 30 a 45 segundos para realizar um encerramento normal depois da remoção do endpoint associado do NEG. Se você precisar de mais tempo para o encerramento normal, estenda o período de carência ou siga as instruções na seção Personalizar tempos limite.

   O seguinte manifesto BackendConfig especifica um tempo limite de diminuição da conexão de 210 segundos (3,5 minutos):

   apiVersion: v1
   kind: BackendConfig
   metadata:
     name: my-backendconfig
   spec:
     terminationGracePeriodSeconds: 210
     containers:
     - name: my-app
       image: my-app-image:latest
       ports:
       - containerPort: 80
   

3. Aplique um preStopHook a todos os contêineres.

   Aplique um preStopHook que garanta que o pod fique ativo por mais 120 segundos enquanto ocorre a diminuição da conexão do endpoint dele no balanceador de carga e a remoção desse endpoint do NEG.

   Observação: aplique preStopHook a todos os contêineres do pod. Sem isso, os contêineres sem o hook são encerrados assim que o pod é excluído. Ao usar uma ferramenta que injeta contêineres, verifique se eles têm o preStopHook necessário.

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-pod
   spec:
     containers:
     - name: my-app
       # Container configuration details...
       lifecycle:
         preStop:
           exec:
             command: ["/bin/sh", "-c", "sleep 120s"]
   

Personalizar tempos limite

Para que você possa garantir a continuidade do pod e evitar erros da série 500, ele precisa estar ativo até que o endpoint seja removido do NEG. Especialmente para evitar os erros 502 e 503, considere a implementação de uma combinação de tempos limite e de preStopHook.

Observação: se a configuração da verificação de integridade for definida para detectar falhas de modo imediato, isso poderá fazer com que os balanceadores de carga parem de enviar solicitações mais cedo, o que poderá reduzir a ocorrência de erros 503. No entanto, observe que erros 503 ainda podem ocorrer durante o limite não íntegro. É essencial entender que a configuração de verificações de integridade não evita erros 502, que ocorrem quando as conexões atuais são encerradas antes da hora certa.

Para manter o pod ativo por mais tempo durante o processo de encerramento, adicione preStopHook a ele. Execute preStopHook antes que o encerramento de um pod seja solicitado. Assim, preStopHook pode ser usado para mantê-lo ativo até que o endpoint associado seja removido do NEG.

Para manter um pod ativo por mais tempo durante o processo de encerramento, insira preStopHook na configuração dele, da seguinte maneira:

spec:
  containers:
  - name: my-app
    ...
    lifecycle:
      preStopHook:
        exec:
          command: ["/bin/sh", "-c", "sleep <latency time>"]

Observação: em pods com vários contêineres, adicione preStopHook a cada contêiner para manter todos eles ativos. Sem isso, apenas aqueles com o hook são executados, e o restante é encerrado. Ao usar uma ferramenta que adiciona contêineres, verifique se esses contêineres também têm o preStopHook necessário.

É possível definir tempos limite e configurações relacionadas para gerenciar o encerramento normal de pods durante as reduções de escala vertical das cargas de trabalho. Você pode ajustar os tempos limites com base em casos de uso específicos. Recomendamos que você comece com tempos limite mais longos e reduza a duração conforme necessário. É possível personalizar os tempos limite configurando parâmetros relacionados a eles e preStopHook das seguintes maneiras:

Tempo limite de diminuição da conexão do serviço de back-end

O parâmetro Backend Service Drain Timeout não é definido por padrão e não tem efeito. Se você definir o parâmetro Backend Service Drain Timeout e ativá-lo, o balanceador de carga deixará de encaminhar novas solicitações ao endpoint e aguardará o tempo limite antes de encerrar as conexões atuais.

É possível definir o parâmetro Backend Service Drain Timeout usando BackendConfig com o Ingress, GCPBackendPolicy com o gateway ou de modo manual em BackendService, no caso de NEGs independentes. O tempo limite precisa ser de 1,5 a 2 vezes maior que o tempo necessário para processar uma solicitação. Isso garante que uma solicitação que tenha chegado antes do início da diminuição da conexão seja concluída antes do tempo limite. Definir o parâmetro Backend Service Drain Timeout como um valor maior que 0 ajuda a reduzir erros 503, porque nenhuma nova solicitação é enviada aos endpoints programados para remoção. Para que esse tempo limite seja eficaz, é preciso usá-lo com preStopHook, a fim de garantir que o pod permaneça ativo enquanto ocorre a diminuição da conexão. Sem essa combinação, as solicitações atuais que não foram concluídas vão receber um erro 502.

Tempo em preStopHook

Ao configurar preStopHook, é preciso atrasar o encerramento do pod o suficiente para que haja tempo de concluir a latência de diminuição da conexão e o tempo limite de diminuição da conexão do serviço de back-end. Com isso, você garante a diminuição adequada da conexão e a remoção do endpoint do NEG antes do encerramento do pod.

Para resultados ideais, verifique se o tempo de execução de preStopHook é menor ou igual à soma de Backend Service Drain Timeout e da latência de diminuição da conexão.

Isso pode ser calculado com a seguinte fórmula:

preStopHook >= Backend Service Drain Timeout + Drain Latency

Recomendamos definir a latência de diminuição da conexão para 1 minuto. Se erros 500 continuarem acontecendo, estime a duração total da ocorrência e adicione o dobro desse tempo à latência. Isso garante que haja tempo suficiente para a diminuição adequada da conexão do pod antes da remoção dele do serviço. É possível ajustar esse valor se ele for muito grande para seu caso de uso específico.

Também é possível estimar esse tempo analisando o carimbo de data/hora da exclusão do pod e o carimbo de data/hora de quando o endpoint foi removido do NEG nos Registros de auditoria do Cloud.

Parâmetro do período de carência para o encerramento

Configure o parâmetro terminationGracePeriod a fim de que haja tempo suficiente para que preStopHook seja concluído e o pod realize um encerramento normal.

Por padrão, quando terminationGracePeriod não é definido de modo explícito, a duração é de 30 segundos. É possível calcular o terminationGracePeriod ideal usando a seguinte fórmula:

terminationGracePeriod >= preStopHook Time + Pod shutdown time

Defina terminationGracePeriod na configuração do pod da seguinte maneira:

  spec:
    terminationGracePeriodSeconds: <terminationGracePeriod>
    containers:
    - name: my-app
      ...
    ...

NEG não encontrado ao criar um recurso de Entrada interna

O seguinte erro pode ocorrer ao criar uma entrada interna no GKE:

Error syncing: error running backend syncing routine: googleapi: Error 404: The resource 'projects/PROJECT_ID/zones/ZONE/networkEndpointGroups/NEG' was not found, notFound

Esse erro ocorre porque o Ingress para balanceadores de carga internos de aplicativos requer grupos de endpoints de rede (NEGs, na sigla em inglês) como back-ends.

Em ambientes de VPC compartilhada ou clusters com políticas de rede ativadas, adicione a anotação cloud.google.com/neg: '{"ingress": true}' ao manifesto de serviço.

504 tempo limite do gateway: tempo limite da solicitação upstream

O seguinte erro pode ocorrer quando você acessa um serviço de uma entrada interna no GKE:

HTTP/1.1 504 Gateway Timeout
content-length: 24
content-type: text/plain

upsteam request timeout

Esse erro ocorre porque o tráfego enviado para balanceadores de carga de aplicativo internos é enviado por proxies Envoy no intervalo de sub-redes somente proxy.

Para permitir o tráfego do intervalo de sub-rede somente proxy, crie uma regra de firewall no targetPort do serviço.

Erro 400: valor inválido para o campo "resource.target"

O seguinte erro pode ocorrer quando você acessa um serviço de uma entrada interna no GKE:

Error syncing:LB_NAME does not exist: googleapi: Error 400: Invalid value for field 'resource.target': 'https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/regions/REGION_NAME/targetHttpProxies/LB_NAME. A reserved and active subnetwork is required in the same region and VPC as the forwarding rule.

Para resolver esse problema, implante uma sub-rede apenas de proxy.

Erro durante a sincronização: erro ao executar a rotina de sincronização do balanceador de carga: o balanceador de carga não existe

Um dos seguintes erros pode ocorrer quando o plano de controle do GKE é atualizado ou quando você modifica um objeto de Entrada:

"Error during sync: error running load balancer syncing routine: loadbalancer
INGRESS_NAME does not exist: invalid ingress frontend configuration, please
check your usage of the 'kubernetes.io/ingress.allow-http' annotation."

Ou:

Error during sync: error running load balancer syncing routine: loadbalancer LOAD_BALANCER_NAME does not exist:
googleapi: Error 400: Invalid value for field 'resource.IPAddress':'INGRESS_VIP'. Specified IP address is in-use and would result in a conflict., invalid

Para resolver esses problemas, siga estas etapas:

• Adicione o campo hosts na seção tls do manifesto de entrada e exclua o Ingress. Aguarde cinco minutos para que o GKE exclua os recursos de Entrada não utilizados. Em seguida, recrie a Entrada. Para mais informações, consulte Campo "Hosts" de um objeto de Entrada.
• Reverta as alterações feitas no Ingress. Em seguida, adicione um certificado usando uma anotação ou secret do Kubernetes.

Problemas conhecidos

Não é possível ativar redirecionamentos HTTPS com o esquema de nomenclatura de Entrada V1

Não é possível ativar redirecionamentos HTTPS nos recursos de Entrada do GKE criados nas versões 1.16.8-gke.12 e anteriores do GKE. É necessário recriar a Entrada antes de ativar os redirecionamentos HTTPS. Caso contrário, um evento de erro é criado e a Entrada não é sincronizada.

A mensagem de evento de erro é semelhante a esta:

Error syncing: error running load balancer syncing routine: loadbalancer lb-name does not exist: ensureRedirectUrlMap() = error: cannot enable HTTPS Redirects with the V1 Ingress naming scheme. Please recreate your ingress to use the newest naming scheme.

Os campos da política de segurança do Google Cloud Armor foram removidos do BackendConfig

Há um problema conhecido em que a atualização de um recurso BackendConfig usando a API v1beta1 remove uma política de segurança ativa do Google Cloud Armor do Serviço. Esse problema afeta as seguintes versões do GKE:

• 1.18.19-gke.1400 a 1.18.20-gke.5099
• 1.19.10-gke.700 a 1.19.14-gke.299
• 1.20.6-gke.700 a 1.20.9-gke.899

Se você não configurar o Google Cloud Armor nos recursos de Entrada pelo BackendConfig, esse problema não afetará os clusters.

Para clusters do GKE que configuram o Google Cloud Armor pelo BackendConfig, é altamente recomendável atualizar recursos BackendConfig usando somente a API v1. Aplicar um BackendConfig ao cluster usando recursos do BackendConfig v1beta1 removerá a política de segurança do Google Cloud Armor do Serviço que ela está referenciando.

Para atenuar esse problema, faça atualizações no BackendConfig usando somente a API BackendConfig v1. O BackendConfig v1 é compatível com os mesmos campos que v1beta1 e não faz alterações interruptivas. Portanto, o campo da API pode ser atualizado de forma transparente. Substitua o campo apiVersion dos manifestos BackendConfig ativos com cloud.google.com/v1 e não use cloud.google.com/v1beta1. O manifesto de amostra a seguir descreve um recurso BackendConfig que usa a API v1:

  apiVersion: cloud.google.com/v1
  kind: BackendConfig
  metadata:
    name: my-backend-config
  spec:
    securityPolicy:
      name: "ca-how-to-security-policy"

Se você tiver sistemas ou ferramentas de CI/CD que atualizam regularmente os recursos do BackendConfig, verifique se o grupo de APIs cloud.google.com/v1 está sendo usado nesses sistemas.

Se o BackendConfig já foi atualizado com a API v1beta1, a política de segurança do Google Cloud Armor pode ter sido removida. É possível determinar se isso aconteceu executando o seguinte comando:

kubectl get backendconfigs -A -o json | jq -r '.items[] | select(.spec.securityPolicy == {}) | .metadata | "\(.namespace)/\(.name)"'

Se a resposta retornar a saída, o cluster é afetado pelo problema. A saída desse comando retorna uma lista de recursos BackendConfig (<namespace>/<name>) que são afetados pelo problema. Se a saída estiver vazia, o BackendConfig não foi atualizado usando a API v1beta1 desde que o problema foi identificado. As atualizações futuras do BackendConfig precisam usar somente v1.

Se a política de segurança do Google Cloud Armor foi removida, determine quando ela foi removida usando a seguinte consulta do Logging:

resource.type="gce_backend_service"
protoPayload.methodName="v1.compute.backendServices.setSecurityPolicy"
protoPayload.authenticationInfo.principalEmail:"container-engine-robot.iam.gserviceaccount.com"
protoPayload.response.status = "RUNNING"
NOT protoPayload.authorizationInfo.permission:"compute.securityPolicies.use"

Se algum dos clusters tiver sido afetado, isso poderá ser corrigido enviando uma atualização para o recurso BackendConfig que usa a API v1.

Faça upgrade do plano de controle do GKE para uma das versões atualizadas a seguir que corrige esse problema e permite que os recursos v1beta1 BackendConfig sejam usados com segurança:

• 1.18.20-gke.5100 e posterior
• 1.19.14-gke.300 e posterior
• 1.20.9-gke.900 e posterior

A seguir

• GKE Ingress para balanceamento de carga de cluster único.

• Tutorial do Ingress para implantar o roteamento HTTP(S) em aplicativos do GKE.

• Implemente o Ingress do GKE com uma verificação de integridade HTTP personalizada.