Como usar o GKE Dataplane V2

Nesta página, explicamos como ativar e resolver problemas do GKE Dataplane V2 para clusters do Google Kubernetes Engine (GKE).

O GKE Dataplane V2 está sempre ativado em novos clusters do Autopilot. Se você tiver problemas ao usar o GKE Dataplane V2, pule para a Solução de problemas.

Antes de começar

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

  • Ative a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

Funções exigidas

Para receber as permissões necessárias para criar um cluster do GKE, peça ao administrador para conceder a você o papel do IAM de administrador do cluster do Kubernetes Engine (container.clusterAdmin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como criar um cluster do GKE com o GKE Dataplane V2

Só é possível ativar o GKE Dataplane V2 ao criar um novo cluster do GKE. Não é possível modificar essa configuração para um cluster atual.

Para criar um cluster padrão que usa o GKE Dataplane V2, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud , acesse a página Criar um cluster do Kubernetes.

    Acessar "Criar um cluster do Kubernetes"

  2. No menu de navegação, clique em Rede.

  3. Abra a seção Interface de rede de contêiner (CNI).

  4. Marque a caixa de seleção Dataplane V2.

  5. Clique em Criar.

gcloud

Execute este comando:

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-dataplane-v2

Substitua:

  • CLUSTER_NAME: um nome para o novo cluster.
  • CONTROL_PLANE_LOCATION: um local do plano de controle do cluster.

API

Para criar um novo cluster com o GKE Dataplane V2, especifique o campo datapathProvider no objeto networkConfig em sua solicitação create do cluster.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • CONTROL_PLANE_LOCATION: um local para o plano de controle do cluster.
  • CLUSTER_NAME: um nome para o novo cluster.

Método HTTP e URL: 

POST https://container.googleapis.com/v1/projects/PROJECT_ID/locations/CONTROL_PLANE_LOCATION/clusters

Corpo JSON da solicitação:

{
  "cluster":{
    "name": "CLUSTER_NAME",
    "location": "CONTROL_PLANE_LOCATION",
    "initialNodeCount": 1,
    "networkConfig":{
      "datapathProvider":"ADVANCED_DATAPATH"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "operation-1234567890",
  "zone": "us-central1-b",
  "operationType": "CREATE_CLUSTER",
  "status": "RUNNING",
  "selfLink": "https://container.googleapis.com/v1/projects/1234567890/zones/us-central1-b/operations/operation-1234567890",
  "targetLink": "https://container.googleapis.com/v1/projects/1234567890/zones/us-central1-b/clusters/example-cluster",
  "startTime": "2026-09-21T14:42:56.222681067Z"
}

Solução de problemas com o GKE Dataplane V2

Nesta seção, mostramos como investigar e resolver problemas com o GKE Dataplane V2.

  1. Confirme se o GKE Dataplane V2 está ativado:

    kubectl -n kube-system get pods -l k8s-app=cilium -o wide

    Se o GKE Dataplane V2 estiver em execução, a saída incluirá pods com o prefixo anetd-. O anetd é o controlador de rede do GKE Dataplane V2.

  2. Se o problema for com a aplicação da política de serviços ou rede, verifique os registros do pod anetd: Use os seguintes seletores de registros no Cloud Logging:

    resource.type="k8s_container"
labels."k8s-pod/k8s-app"="cilium"
resource.labels.cluster_name="CLUSTER_NAME"

  3. Se a criação do pod falhar, verifique as dicas nos registros do kubelet. Use os seguintes seletores de registros no Cloud Logging:

    resource.type="k8s_node"
log_name=~".*/logs/kubelet"
resource.labels.cluster_name="CLUSTER_NAME"

    Substitua CLUSTER_NAME pelo nome do cluster ou remova-o completamente para visualizar os registros de todos os clusters.

  4. Se os pods anetd não estiverem em execução, examine o ConfigMap cilium-config para verificar se há modificações. Evite alterar os campos atuais no ConfigMap, porque essas mudanças podem desestabilizar o cluster e interromper o anetd. O ConfigMap só é corrigido de volta ao estado padrão se novos campos forem adicionados a ele. As mudanças nos campos atuais não são corrigidas, e recomendamos não mudar nem personalizar o ConfigMap.

Problemas conhecidos

Ao usar o GKE Dataplane V2, você pode encontrar os seguintes problemas conhecidos.

As sondagens de verificação de integridade são originadas de 169.254.4.6 no GKE 1.35 e versões mais recentes

Em clusters do GKE Dataplane V2 que executam a versão 1.35.1-gke.1516000 e mais recentes, a configuração de CNI usa um plug-in cilium-cni unificado em vez de encadear ptp e cilium-cni. Com essa configuração, o Cilium define o gateway padrão do pod como o endereço IP da interface cilium_host local do nó (169.254.4.6) em vez do endereço .1 do intervalo CIDR do pod do nó (por exemplo, 10.x.x.1).

Ao definir o gateway padrão do pod como a interface cilium_host local do nó, as sondagens de atividade, prontidão e inicialização kubelet locais do nó (kube-probe) e o tráfego NodeLocal DNSCache se originam de 169.254.4.6. Os recursos padrão do Kubernetes NetworkPolicy permitem automaticamente sondagens de integridade locais do nó (reserved:host). Portanto, não é necessário aplicar mudanças à configuração do NetworkPolicy. No entanto, se os aplicativos aplicarem listas de permissão de IP no nível do aplicativo ou ACLs do servidor da Web em endpoints de verificação de integridade, atualize essas listas para permitir o endereço IP 169.254.4.6/32 (ou 169.254.0.0/16).

Tempos limite de conexão para pods não prontos

Quando um pod não está pronto, as conexões com o serviço associado podem atingir o tempo limite. Esse é o comportamento esperado do GKE Dataplane V2, que é diferente do kube-proxy, que pode retornar um erro connection refused mais rápido.

A filtragem de rótulos relevantes para a identidade do Cilium não entra em vigor, e os pods ficam presos no estado "ContainerCreating".

Versões afetadas: 1.34, 1.35

Em clusters do GKE Dataplane V2, o uso emergencial da filtragem de rótulos relevantes para identidade via ConfigMap kube-system/cilium-config-emergency-override não é aplicado corretamente nas versões afetadas.

Essa abordagem limita quais rótulos de pod são usados para a geração de identidade do Cilium.

Quando outros mecanismos de prevenção/remoção de chaves/valores de rótulos de alta cardinalidade de pods não estão disponíveis (por exemplo, quando os rótulos são aplicados por uma ferramenta ou estrutura), o filtro de rótulos relevantes para a identidade pode ser usado para excluir as chaves de rótulos do cálculo da identidade do Cilium. Para mais informações sobre como configurar essas regras, consulte Rótulos relevantes para a identidade na documentação do Cilium.

Para as versões afetadas do GKE, as identidades do Cilium criadas pelo operador continuam incluindo os rótulos excluídos.

Sintomas

  • Os pods com rótulos que precisam ser filtrados para a geração de identidade do Cilium podem não iniciar e ficar presos no estado ContainerCreating. Os eventos do pod podem mostrar erros de tempo limite:

      {"level":"warning", "msg":"Error changing endpoint identity", "error":"unable to resolve identity: timed out waiting for cilium-operator to allocate CiliumIdentity for key ...;, error: exponential backoff cancelled via context: context canceled", "k8sPodName":"...", "subsys":"endpoint"}

  • Em vez de compartilhar identidades com base em rótulos filtrados, os pods com valores de rótulo exclusivos continuam gerando identidades do Cilium exclusivas. Isso pode levar a um aumento acentuado de identidades, esgotando potencialmente as identidades do Cilium disponíveis (até um limite de 65.536) e causando problemas de escalonabilidade.

Versões corrigidas

Para corrigir esse problema, faça upgrade do cluster para uma das seguintes versões do GKE:

  • 1.34.6-gke.1307000 ou mais recente
  • 1.35.2-gke.1962000 ou mais recente

Alternativa

Como solução alternativa, aplique as regras de filtragem de rótulos ao campo data.labels no ConfigMap cilium-config principal e remova-as de cilium-config-emergency-override. Essa situação persiste durante as operações do plano de controle, como upgrades, porque o GKE preserva as modificações do usuário em campos que não gerencia no ConfigMap cilium-config.

  1. Remova a chave labels da seção data do ConfigMap cilium-config-emergency-override, se ela existir.

  2. Edite o ConfigMap cilium-config adicionando ou modificando a chave labels na seção data. Por exemplo, para evitar que rótulos chamados uuid sejam usados para geração de identidade:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: cilium-config
  namespace: kube-system
data:
  # ... other existing keys
  labels: "!uuid"
  # ... other existing keys

  3. Reinicie o anet-operator no plano de controle fazendo upgrade para a mesma versão em que ele está sendo executado. Isso força o operador a reiniciar e recarregar a configuração:

    gcloud container clusters upgrade CLUSTER_NAME \
    --location CLUSTER_LOCATION \
    --project PROJECT_ID \
    --cluster-version $(gcloud container clusters describe CLUSTER_NAME --location CLUSTER_LOCATION --project PROJECT_ID --format="value(currentMasterVersion)") \
    --master

  4. Depois que o plano de controle for reiniciado, reinicie o DaemonSet anetd para garantir que os agentes de nó também apliquem as mudanças necessárias:

    kubectl rollout restart daemonset anetd -n kube-system

Problemas de conectividade intermitente relacionados a conflitos de intervalo NodePort em clusters do GKE Dataplane V2

Nos clusters do GKE Dataplane V2, podem ocorrer problemas de conectividade intermitente para tráfego mascarado ou com uso temporário de portas. Esses problemas são causados por possíveis conflitos de porta com o intervalo NodePort reservado e geralmente acontecem nos seguintes cenários:

  • ip-masq-agent personalizado:se você usa um ip-masq-agent personalizado (versão 2.10 ou mais recente), em que o cluster tem serviços NodePort ou de balanceador de carga, é possível observar problemas de conectividade intermitentes devido ao conflito com o intervalo NodePort. A partir da versão 2.10, ip-masq-agent tem o argumento --random-fully implementado internamente por padrão. Para mitigar isso, defina explicitamente --random-fully=false (aplicável desde a versão 2.11) em argumentos na configuração ip-masq-agent. Para detalhes de configuração, consulte Como configurar um agente de mascaramento de IP em clusters padrão.

  • Overlap de intervalo de porta temporário:se o intervalo de porta temporário definido por net.ipv4.ip_local_port_range nos nós do GKE se sobrepõe ao intervalo NodePort (30000-32767), o que também pode gerar problemas de conectividade. Para evitar esse problema, verifique se esses dois intervalos não se sobrepõem.

Revise a configuração de ip-masq-agent e as configurações do intervalo de porta temporário para garantir que elas não conflitem com o intervalo de NodePort. Se você encontrar problemas de conectividade intermitente, considere essas possíveis causas e ajuste sua configuração de acordo.

Problemas de conectividade com hostPort em clusters do GKE Dataplane V2

Versões afetadas do GKE:todas as versões disponíveis

Em clusters que usam o GKE Dataplane V2, podem ocorrer falhas de conectividade quando o tráfego tem como destino o IP:porta de um nó, em que a porta é o hostPort definido no pod. Esses problemas surgem em dois cenários principais:

  • Nós com hostPort atrás de um balanceador de carga de rede de passagem:

    O hostPort vincula um pod à porta de um nó específico, e um balanceador de carga de rede de passagem distribui o tráfego entre todos os nós. Quando você expõe pods à Internet usando hostPort e um balanceador de carga de rede de passagem, ele pode enviar tráfego para um nó em que o pod não está em execução, causando falhas de conexão. Isso ocorre devido a uma limitação conhecida no GKE Dataplane V2, em que o tráfego do balanceador de carga de rede de passagem não é encaminhado de maneira consistente para pods hostPort.

    Solução alternativa:ao expor hostPorts de um pod no nó com um balanceador de carga de rede de passagem, especifique o endereço IP interno ou externo do balanceador de carga de rede no campo hostIP do pod.

    ports:
- containerPort: 62000
  hostPort: 62000
  protocol: TCP
  hostIP: 35.232.62.64
- containerPort: 60000
  hostPort: 60000
  protocol: TCP
  hostIP: 35.232.62.64
  # Assuming 35.232.62.64 is the external IP address of a passthrough Network Load Balancer.

  • hostPort conflita com o intervalo reservado NodePort:

    Se o hostPort de um pod entrar em conflito com o intervalo NodePort reservado (30000-32767), o Cilium poderá não encaminhar o tráfego para o pod. Esse comportamento ocorre porque o Cilium gerencia recursos de hostPort, substituindo o método Portmap anterior. Esse é um comportamento esperado do Cilium e está mencionado na documentação pública dele.

Não planejamos corrigir essas limitações em versões posteriores. A causa raiz desses problemas está relacionada ao comportamento do Cilium e fora do controle direto do GKE.

Recomendação:migre para os serviços NodePort em vez de hostPort para melhorar a confiabilidade. NodePort Os serviços oferecem recursos semelhantes.

Os intervalos de portas para políticas de rede não entram em vigor

Versões afetadas do GKE:anteriores à 1.32

Se você especificar o campo endPort em um objeto NetworkPolicy em um cluster que tem o GKE Dataplane V2 ativado e executa uma versão do GKE anterior à 1.32, o Kubernetes vai ignorar o campo.

A API NetworkPolicy do Kubernetes permite especificar um intervalo de portas em que o Kubernetes aplica a política de rede. Essa API é compatível com clusters com política de rede do Calico e com clusters com o GKE Dataplane V2 que executam a versão 1.32 ou mais recente do GKE. A API não é compatível com clusters do GKE Dataplane V2 que executam versões anteriores à 1.32.

Para verificar o comportamento dos objetos NetworkPolicy, leia-os depois de serem gravados no servidor da API. Se o objeto ainda contiver o campo endPort, o Kubernetes vai aplicar o recurso. Se o campo endPort estiver ausente, o Kubernetes não vai aplicar o recurso. O objeto armazenado no servidor de API é a fonte de verdade da política de rede.

Para mais informações, consulte KEP-2079: política de rede compatível com intervalos de portas.

Versões corrigidas

Para resolver esse problema, faça upgrade do cluster para a versão 1.32 ou mais recente do GKE.

Nós no estado NodeNotReady devido ao erro containerID ausente

Quando os clusters são atualizados para a versão 1.35.1-gke.1616000 do GKE e posteriormente, os nós podem entrar imediatamente em um estado NodeNotReady se o GKE Dataplane V2 e o Cloud Service Mesh estiverem ativados.

Causa

A partir da versão 1.35.1-gke.1616000 do GKE, os clusters do GKE Dataplane V2 usam a versão 1.1.0 da CNI nos arquivos de configuração da CNI. Essa mudança exige que plug-ins CNI downstream, como o Istio gerenciado pelo Google, também ofereçam suporte à versão 1.1.0 da CNI. Devido a um atraso no lançamento do Managed Istio, alguns clusters ainda não receberam a versão compatível (1.23), o que causou a falha na inicialização.

Sintomas

Os nós afetados aparecem imediatamente como NodeNotReady. A seguinte mensagem de erro aparece nos registros do containerd:

NetworkPluginNotReady message:Network plugin returns error: missing containerID

Alternativa

Para atenuar o problema, faça downgrade do cluster afetado para uma versão do GKE anterior a 1.35.1-gke.1616000.

Interferência de programas eBPF personalizados

O GKE usa programas eBPF para gerenciar a rede do GKE Dataplane V2. Se você implantar programas eBPF personalizados em interfaces de rede de nós gerenciados pelo GKE, eles poderão interferir nos programas eBPF gerenciados pelo GKE e causar problemas de rede.

O GKE não é compatível com programas eBPF personalizados anexados às seguintes interfaces de rede:

  • eth*
  • ens4
  • lo
  • cilium*
  • gke*
  • veth*

A presença de programas eBPF personalizados nessas interfaces pode interferir nos programas instalados pelo agente anetd do GKE Dataplane V2, o que pode prejudicar a rede do cluster. Recomendamos que você remova do cluster todos os programas eBPF personalizados ou cargas de trabalho que injetam esses programas.

Descobrir programas eBPF personalizados

Para descobrir programas eBPF personalizados em execução nos nós do cluster, crie um DaemonSet configurado com a configuração hostNetwork: true, que usa bpftool para consultar esses programas eBPF:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: bpftool-logger
  labels:
    app: bpftool-logger
spec:
  selector:
    matchLabels:
      app: bpftool-logger
  template:
    metadata:
      labels:
        app: bpftool-logger
    spec:
      hostPID: true
      hostNetwork: true
      containers:
      - name: bpftool
        image: ubuntu:22.04
        securityContext:
          privileged: true
        env:
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        command:
        - /bin/bash
        - -c
        - |
          echo "Installing dependencies..."
          apt-get update -y > /dev/null 2>&1
          apt-get install -y curl tar > /dev/null 2>&1

          echo "Downloading and setting up bpftool..."
          curl -sL https://github.com/libbpf/bpftool/releases/download/v7.7.0/bpftool-v7.7.0-amd64.tar.gz | tar xz
          chmod +x bpftool
          mv bpftool /usr/local/bin/

          echo "========== $(date) | Node: ${NODE_NAME} =========="
          bpftool net | grep -E '^(eth|ens4|lo|cilium|gke|veth)' | grep -v ' cil_'
          sleep infinity

  1. Salve o manifesto como ebpf-discovery.yaml e aplique o DaemonSet:

    kubectl apply -f ebpf-discovery.yaml

  2. Aguarde até que os pods estejam em execução:

    kubectl rollout status ds/bpftool-logger

  3. Verifique os registros dos pods para descobrir programas eBPF:

    kubectl logs -l app=bpftool-logger

  4. Quando terminar, exclua o DaemonSet:

    kubectl delete -f ebpf-discovery.yaml

A seguir