Como configurar recursos da Entrada

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. O Ingress for Google Kubernetes Engine (GKE) e o Ingress for Anthos fornecem balanceamento de carga de classe empresarial com forte integração à sua rede VPC do 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 Ingress em vários clusters
Controlador de entrada Controlador de entrada hospedado no cluster Controlador de entrada hospedado pelo Google
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
Compatibilidade das versões Tudo GKE 1.16.5+ GKE 1.14+
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 do Google 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.700G
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

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

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

Como configurar recursos da Entrada

Ao criar um Ingress usando o controlador padrão, você pode escolher o tipo de balanceador de carga HTTP(S) (externo ou interno) com 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 da Entrada, e os BackendConfigs são referenciados por um objeto do 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.

Visão geral do BackendConfig e do FrontendConfig
Figura: visão geral do BackendConfig e do FrontendConfig

Como associar o FrontendConfig ao Ingress

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

Entrada de vários clusters

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

Um Serviço ou MultiClusterService pode usar a anotação cloud.google.com/backend-config ou beta.cloud.google.com/backend-config para especificar o nome de um BackendConfig. Quando associado a um Serviço ou MultiClusterService, o recurso BackendConfig solicita que o Google Cloud crie ou modifique as configurações do serviço de back-end.

Nos exemplos a seguir:

Se você estiver usando a versão 1.16-gke.3 ou posterior do GKE, use a anotação cloud.google.com/backend-config, mesmo que a anotação beta.cloud.google.com/backend-config também funcione. Para versões anteriores, você deve usar a anotação beta.cloud.google.com/backend-config.

Mesmo BackendConfig para todas as portas de Serviço

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

1.16-gke.3+

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

Todas as versões compatíveis

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

BackendConfig exclusivo por porta de serviço

É possível especificar um BackendConfig personalizado para uma ou mais portas específicas de um Serviço ou MultiClusterService, usando uma chave correspondente ao nome ou ao 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.

1.16-gke.3+

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

No GKE, 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). No exemplo acima, é possível substituir SERVICE_REFERENCE_A por PORT_NUMBER_1 ou PORT_NAME_1 e substituir SERVICE_REFERENCE_B por PORT_NUMBER_2 ou PORT_NAME_2.

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.

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:

Um balanceador de carga HTTP externo somente de redirecionamento, que consiste em uma regra de encaminhamento, proxy HTTP de destino e um mapa de URL com redirecionamento para um balanceador de carga HTTPS completo com serviços de back-end

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.

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_BLACKLIST
      queryStringWhitelist: QUERY_STRING_WHITELIST

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_BLACKLIST: 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_WHITELIST: 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.

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.

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.

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.

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

Política de segurança 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"

Geração de registros de acesso HTTP

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.

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

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

Afinidade da sessão

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

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"

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}"

Exercício: como definir tempos limite de entrada 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

Para a lista completa de recursos que podem ser definidos usando um BackendConfig, consulte a seção BackendConfig da tabela de recursos.

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 até que o controlador do Ingress configure um balanceamento de carga HTTP(S) 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.

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.

Resolver problemas

BackendConfig não encontrado

Este erro ocorre quando um BackendConfig para uma porta de serviço é especificado na anotação do serviço, mas o recurso BackendConfig real não é encontrado. Isso pode ocorrer se você não criou o recurso BackendConfig, se ele foi criado no namespace errado ou se digitou incorretamente a referência na anotação Serviço.

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

kubectl get event

O seguinte tipo de saída 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

Política de segurança não encontrada

Depois que o objeto de Entrada for criado, se a política de segurança não estiver adequadamente associada ao serviço de balanceador de carga, avalie o evento do Kubernetes para ver se há um erro de configuração. Se o BackendConfig especificar uma política inexistente, um evento de alerta será emitido periodicamente. Para corrigir esse problema, especifique a política de segurança correta, por nome, no BackendConfig.

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

kubectl get event

O seguinte tipo de saída 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.

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 to GCP: 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