Controlar a comunicação com endereços IP permanentes nos pods do GKE

Padrão

Nesta página, mostramos como implementar endereços IP persistentes em pods do Google Kubernetes Engine (GKE). Você pode assumir o controle da sua rede de pods do GKE com mapeamento de endereços IP persistentes e personalizados. Para saber mais sobre endereços IP permanentes, os casos de uso e as vantagens deles, consulte Sobre endereços IP permanentes para o pod do GKE.

Requisitos

GKE versão 1.29 ou mais recente
Escolha entre reservar os endereços IP fornecidos pelo Google (endereços IP fornecidos pelo Google) ou usar seus próprios endereços IP (BYOIP).
Configure o aplicativo em execução nos pods para reconhecer e usar endereços IP permanentes atribuídos.
Os endereços IP permanentes para pods do GKE exigem o GKE Dataplane V2 e clusters ativados para várias redes.

Limitações

A rede padrão não oferece suporte a endereços IP persistentes. Você precisa ativar o recurso de várias redes durante a criação do cluster.
Configure seus aplicativos para usar endereços IP permanentes atribuídos. O GKE não adiciona automaticamente a configuração de endereço IP às interfaces de rede do pod.
É possível associar cada endereço IP persistente a um pod por vez. Quando há vários pods disponíveis, o GKE normalmente envia o tráfego para o pod mais recente. No entanto, o GKE só faz isso se o pod mais recente estiver íntegro, o que significa que ele tem o status de condição Ready como True por padrão. Você pode configurar esse comportamento e alterá-lo usando a configuração reactionMode em GKEIPRoute.
O GKE só aceita endereços IPv4 como endereços IP permanentes.
O GKE só oferece suporte às várias redes dos tipos Layer 3 ou Device para endereços IP permanentes.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Ativar a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Preços

O suporte a endereços IP permanentes para o recurso de pods está em Pré-lançamento e é apenas compatível com clusters que estão em projetos ativados com o GKE Enterprise. Para entender as cobranças que se aplicam à ativação da edição Enterprise do Google Kubernetes Engine (GKE), consulte Preços do GKE Enterprise.

Implementar endereços IP permanentes para pods do GKE

Com os endereços IP permanentes no GKE, é possível dar aos pods uma identidade de rede estável, mesmo que os próprios pods sejam atualizados ou movidos ao redor.

Esta seção resume o fluxo de trabalho para implementar endereços IP persistentes para pods do GKE:

Criar um cluster: crie um cluster que tenha a API Gateway. GKE Dataplane V2 e várias redes ativadas.
Reserve um endereço IP: decida se você precisa de um endereço IP externo (acessível publicamente) ou interno (somente Google Cloud) e reserve ele. Escolha a mesma região do seu cluster do GKE.
Crie um gateway: configure o objeto do gateway do Kubernetes que contém seus endereços IP persistentes e permite criar regras (GKEIPRoutes) sobre quais pods no cluster podem usar esses endereços IP persistentes.
Crie ou identifique cargas de trabalho com redes adicionais para endereços IP permanentes: Prepare pods para usar endereços IP persistentes ativando várias interfaces de redes e definindo a rede em que os endereços IP persistentes residem.
Crie o objeto GKEIPRoute para cargas de trabalho selecionadas: configure GKEIPRoute para atribuir o endereço IP persistente a um pod específico. É possível usar rótulos para direcionar os pods certos e, opcionalmente, configurar como o roteamento reage às alterações no pod.
Configure o reconhecimento do aplicativo: configure seu aplicativo no pod para usar ativamente o endereço IP persistente.
Monitoramento: acompanhe o status dos objetos GKEIPRoute e gateway para garantir que tudo esteja funcionando conforme o esperado.

Para implementar um endereço IP permanente para pods do GKE, execute as etapas a seguir:

Etapa 1: criar um GKE Dataplane V2 e um cluster do GKE ativado para várias redes

Para ativar os recursos avançados de roteamento de rede e gerenciamento de endereços IP necessários para implementar endereços IP permanentes em pods do GKE, você precisa criar um GKE Dataplane V2 e um cluster com várias redes ativado.

Etapa 2: reservar endereços IP permanentes

Para estabelecer identidades de rede confiáveis para os pods e configurar endereços IP permanentes, é preciso primeiro adquirir endereços IP persistentes. Você pode escolher entre reservar endereços IP fornecidos pelo Google ou usar seus próprios endereços IP (BYOIP).

Etapa 2a: reservar endereços IP fornecidos pelo Google

Para reservar endereços IP externos, execute o seguinte comando:

gcloud compute addresses create ADDRESS_NAME \
   --region=REGION

Substitua:

ADDRESS_NAME: o nome que você quer associar a esse endereço.
REGION: a região em que você quer reservar o endereço. Ela precisa ser a mesma região do Pod ao qual o endereço IP será anexado.

Observação: especifique uma região ao reservar um endereço IP porque as regras de encaminhamento, que lidam com o roteamento de tráfego para endereços IP persistentes, são regionais. Seu endereço IP e o cluster do GKE precisam estar na mesma região para que o roteamento funcione corretamente.

Para reservar endereços IP internos, execute o seguinte comando:

gcloud compute addresses create ADDRESS_NAME \
    --region REGION
    --subnet SUBNETWORK \
    --addresses IP_ADDRESS

Substitua:

ADDRESS_NAME: os nomes de um ou mais endereços que você quer reservar. No caso de vários endereços, especifique todos os endereços como uma lista separados por espaços. Por exemplo, example-address-1 example-address-2 example-address-3
REGION: a região desta solicitação
SUBNETWORK: a sub-rede deste endereço IPv4 interno

Para garantir que o tráfego seja roteado corretamente dentro da rede privada, o IP interno precisa pertencer a uma sub-rede designada.

Para mais informações sobre endereços IP internos e externos, consulte Reservar um endereço IP externo estático e Reservar um endereço IP interno estático.

Etapa 2b: usar seus próprios endereços IP (BYOIP)

Você pode trazer seus próprios endereços IP (BYOIP), em vez de depender dos endereços IP fornecidos pelo Google. O BYOIP é um método útil se você precisa de endereços IP específicos para seus aplicativos ou está migrando sistemas atuais para o Google Cloud. Para usar o método BYOIP, o Google valida que você é proprietário do intervalo de endereços IP e após a importação dos endereços para o Google Cloud, é possível atribuí-los como endereços IP persistentes para pods do GKE. Para mais informações, consulte Usar seus próprios endereços IP.

Etapa 3: criar objetos de gateway

Os objetos de gateway contêm os endereços IP e definem quais pods são qualificados para uso. Para controlar como endereços IP persistentes são atribuídos aos seus pods do GKE, você vai usar objetos de gateway.

Crie um objeto de gateway do Kubernetes da classe apropriada:
- gke-persistent-regional-external-managed para endereços IP externos (públicos).
- gke-persistent-regional-internal-managed para endereços IP internos (somente Google Cloud).
Na seção de endereços do gateway, liste os endereços IP permanentes (fornecido pelo Google ou BYOIP) gerenciados pelo gateway.
Use a seção Listeners para determinar quais pods (e os objetos GKEIPRoute associados) podem usar os endereços IP do gateway. Listeners atua como um filtro com base no namespace do GKEIPRoute, em que um objeto GKEIPRoute existe.

É possível escolher uma das seguintes opções de seleção de namespace do Kubernetes:
- Todos os namespaces: qualquer GKEIPRoute no cluster.
- Seletor: GKEIPRoute nos namespaces de GKEIPRoute correspondentes a um rótulo específico.
- Mesmo namespace: somente GKEIPRoutes no mesmo namespace de GKEIPRoute que o gateway.

O exemplo a seguir fornece acesso em todo o cluster aos endereços IP permanentes externos, permitindo que qualquer pod os utilize.

Salve o seguinte manifesto de amostra como allowed-pod-ips.yaml:

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  namespace: default
  name: allowed-pod-ips
spec:
  gatewayClassName: gke-persistent-regional-external-managed

  listeners:
    - name: default
      port: 443
      protocol: none
      allowedRoutes:
        namespaces:
          from: All

  addresses:
    - value: "34.123.10.1/32"
      type: "gke.networking.io/cidr"
    - value: "34.123.10.2/32"
      type: "gke.networking.io/cidr"

em que:

endereços: lista todos os endereços IP com permissões gerenciadas pelo gateway específico.
listeners: usado para identificar os namespaces dos quais objetos GKEIPRoute pode fazer referência a esse gateway.

Aplique o manifesto ao cluster:

kubectl apply -f allowed-pod-ips.yaml

Etapa 4: criar ou identificar cargas de trabalho com redes extras para endereços IP persistentes

Configurar pods de várias redes e criar objetos de rede indicando as redes às quais o endereço IP permanente pertence.

Etapa 5: criar o objeto `GKEIPRoute` para cargas de trabalho selecionadas

Para atribuir um endereço IP persistente a um pod selecionado, crie um objeto GKEIPRoute.

Salve o seguinte manifesto de amostra como my-ip-route.yaml:

kind: GKEIPRoute
apiVersion: networking.gke.io/v1
metadata:
  namespace: default
  name: my-ip-route
spec:
  parentRefs:
  - name: allowed-pod-ips
    namespace: default
  addresses:
  - value: "34.123.10.1/32"
    type: "gke.networking.io/cidr"
  network: blue-network
  reactionMode: ReadyCondition
  podSelector: # Only one pod is selected.
    matchLabels:
      component: proxy

em que:

parentRefs: aponta para o gateway do qual os endereços IP persistentes são usados. Este campo não pode ser modificado.
endereços: lista todos os endereços IP persistentes que são roteados para o pod identificado com podSelector. Este campo pode ser modificado. Para IPv4, somente endereços /32 são aceitos.
podSelector: especifica os rótulos que identificam o pod para onde os endereços IP são roteados. Este campo é mutável e se aplica ao mesmo namespace em que GKEIPRoute é colocado. Se você selecionar vários pods, dois fatores adicionais são considerados: o tempo de criação dos pods (o GKE escolhe o mais recente) e a configuração do campo reactionMode.
reactionMode: especifica como esse recurso se comporta quando um pod específico (selecionado por podSelector) é criado ou excluído. Este campo é opcional, e o padrão é ReadyCondition. O campo ReadyCondition é imutável. É possível definir reactionMode para controlar como o recurso funciona quando os pods são criados, excluídos ou atualizados.
network: aponta para a interface de rede em um pod ao qual os endereços IP são roteados. Este campo não pode ser modificado.

Aplique o manifesto ao cluster:

kubectl apply -f my-ip-route.yaml

Atribuir endereços IP permanentes aos pods do StatefulSet

Para atribuir um endereço IP permanente a um pod específico em um StatefulSet, use o nome do host previsível do pod e o Kubernetes com rotulagem automática, conforme mostrado no exemplo a seguir:

Salve o seguinte manifesto de amostra como my-pod-ips.yaml:

kind: GKEIPRoute
apiVersion: networking.gke.io/v1
metadata:
  namespace: proxy-ss-ns
  name: my-pod-ips
spec:
  parentRefs:
  - name: allowed-pod-ips
    namespace: default
  addresses:
  - value: "34.123.10.1/32"
    type: "gke.networking.io/cidr"
  - value: "34.123.10.2/32"
    type: "gke.networking.io/cidr"
  network: blue-network
  reactionMode: ReadyCondition
  podSelector:
    matchLabels:
      statefulset.kubernetes.io/pod-name: proxy-ss-1
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  namespace: proxy-ss-ns
  name: proxy-ss
spec:
  selector:
    matchLabels:
      component: proxy
  serviceName: "proxy"
  replicas: 3
  template:
    metadata:
      annotations:
        networking.gke.io/default-interface: 'eth0'
        networking.gke.io/interfaces: '[{"interfaceName":"eth0","network":"default"}, {"interfaceName":"eth1","network":"blue-network"}]'
      labels:
        component: proxy
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

Aplique o manifesto ao cluster (verifique se você tem uma rede chamada "blue-network"):

kubectl apply -f my-pod-ips.yaml

Atribuir endereços IP persistentes aos pods de implantação

Para atribuir um endereço IP persistente ao pod mais recente em uma implantação, aplique GKEIPRoute com a seguinte configuração:

Salve o seguinte manifesto de amostra como my-pod-ips.yaml:

kind: GKEIPRoute
apiVersion: networking.gke.io/v1
metadata:
  namespace: proxy-deploy-ns
  name: my-pod-ips
spec:
  parentRefs:
  - name: allowed-pod-ips
    namespace: default
  addresses:
  - value: "34.123.10.1/32"
    type: "gke.networking.io/cidr"
  - value: "34.123.10.2/32"
    type: "gke.networking.io/cidr"
  network: blue-network
  reactionMode: ReadyCondition
  podSelector:
    matchLabels:
      component: proxy
---
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: proxy-deploy-ns
  name: proxy-deploy
spec:
  selector:
    matchLabels:
      component: proxy
  replicas: 4 # Latest Pod is used
  template:
    metadata:
      annotations:
        networking.gke.io/default-interface: 'eth0'
        networking.gke.io/interfaces: '[{"interfaceName":"eth0","network":"default"}, {"interfaceName":"eth1","network":"blue-network"}]'
      labels:
        component: proxy
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

Aplique o manifesto ao cluster (verifique se você tem uma rede chamada "blue-network"):

kubectl apply -f my-ip-route.yaml

Etapa 6: usar endereços IP persistentes no pod

Como atribuir um endereço IP persistente a um pod do GKE usando um GKEIPRoute não torna os endereços IP utilizáveis automaticamente pelo aplicativo. Os endereços IP persistentes são tratados no nível de roteamento de rede, mas a configuração padrão do pod não terá conhecimento dela. Você precisa configurar as propriedades do aplicativo para reconhecer e usar o endereço no pod. Para isso, seu pod vai precisar de permissões de privilégios.

Para configurar o aplicativo, considere as seguintes opções:

net.ipv4.ip_nonlocal_bind: modifique uma configuração do sistema para permitir que o aplicativo use endereços IP não atribuídos diretamente à interface.
ip address add: use esse comando na lógica do aplicativo para adicionar manualmente o endereço IP persistente a uma interface.
Soquetes brutos: para ter ainda mais controle, o aplicativo pode interagir diretamente com a pilha de rede (avançado).
Pilha de endereços IP do espaço do usuário: em casos especializados, um aplicativo específico pode ser executado no pod para gerenciar o endereço IP (muito avançado).

Personalizar o comportamento do endereço IP persistente durante alterações no pod

Nesta seção, descrevemos como o endereço IP permanente do pod do GKE se comporta quando o pod de destino é criado ou excluído. O controlador do GKE monitora seus pods e a configuração de GKEIPRoute. Quando ele detecta que uma atualização está acontecendo, ele reatribui automaticamente o endereço IP persistente para um pod adequado de acordo com a reactionMode escolhida.

Entender como o recurso de endereço IP permanente processa automaticamente as alterações de pods e as opções de configuração disponíveis para você:

Decida entre ReadyCondition ou Exists no reactionMode da configuração de GKEIPRoute. Considere as necessidades do seu aplicativo com relação à rapidez com que o endereço IP é atribuído em comparação aos requisitos de prontidão.
Se você está usando ReadyCondition para garantir a disposição, certifique-se de que os pods implementaram corretamente as sondagens de prontidão do Kubernetes. Caso contrário, o endereço IP persistente pode não funcionar como pretendido.
Recomendamos que você monitore o status dos seus pods e do campo Conditions do objeto GKEIPRoute para garantir que o sistema esteja funcionando corretamente. O status true da condição Ready indica que o sistema está funcionando corretamente.

Resolver problemas de comunicação com endereços IP persistentes para pods

Nesta seção, mostramos como resolver problemas relacionados a endereços IP persistentes para pods.

`NoPodsFound` quando não há pods correspondentes encontrados

Sintoma

O objeto GKEIPRoute especifica um podSelector (um conjunto de rótulos) para identificar quais pods estão associados ao endereço IP persistente. O status NoPodsFound indica que não há pods nos namespacesGKEIPRoute's de destino com rótulos correspondentes.

Causas possíveis

Rótulos incorretos: o pod em que você pretende usar o endereço IP permanente que podem ter rótulos incorretos ou nenhum rótulo.
Não há pods: se reactionMode == Exists, verifique se o pod está atribuído a um nó ao verificar o campo pod.Spec.nodeName. Pode haver nenhum pod em execução no namespace GKEIPRoute's que corresponda ao seletor.
O pod não está pronto: se reactionMode == ReadyCondition, verifique se o status do pod é READY. Mesmo que exista um pod correspondente, se ele não estiver em um estado Ready, ele não poderá veicular tráfego e, por isso, não será selecionado.

Resolução

Verificar seus rótulos: confira se os rótulos em GKEIPRoute's podSelector correspondem aos rótulos aplicados ao pod pretendido.
Verificar a existência do pod: confirme se um pod com os rótulos corretos existe nos namespaces GKEIPRoute's especificados por Listeners do gateway. Se reactionMode == Exists, verifique se o pod está atribuído a um nó ao verificar o campo pod.Spec.nodeName
Confirme a prontidão do pod: se reactionMode == ReadyCondition, verifique se o status do pod é READY. Verifique se o pod está no estado Ready usando o seguinte comando:
```
kubectl get pods -n <namespace>
```
Os pods em outros estados (por exemplo, "Pendente", "Erro") não são selecionados.
Configure seus pods para responder no endereço IP permanente atribuído.

`Mutated` quando um pod correspondente foi encontrado e a programação de endereços IP persistentes está em andamento