Entender a compatibilidade do Cloud Service Mesh

Este guia detalha como avaliar a compatibilidade de uma frota para a modernização do plano de controle, confirmando se a configuração, a infraestrutura e a escala são compatíveis com a implementação do plano de controle TRAFFIC_DIRECTOR.

Ativar ou desativar as verificações de compatibilidade

Para iniciar as verificações de compatibilidade, ative o modo de validação para a frota, que aciona uma auditoria contínua de todas as configurações do Istio, da infraestrutura e dos parâmetros de escalonamento. A ativação dessas verificações não faz nenhuma mudança na sua frota ou nos clusters. Ela apenas ativa a geração de relatórios de compatibilidade.

Ativar verificações

Para iniciar a auditoria de compatibilidade, execute o seguinte comando gcloud:

gcloud alpha container fleet mesh update --modernization-compatibility validation-enabled --project FLEET_PROJECT_ID

Substitua FLEET_PROJECT_ID pelo ID do projeto host da frota. Em geral, o FLEET_PROJECT_ID tem o mesmo nome do projeto.

Depois de ativado, o Cloud Service Mesh começa a avaliar a frota e todos os clusters provisionados do Cloud Service Mesh nela para verificar a compatibilidade com a modernização.

Desativar verificações

Para interromper a geração de relatórios de resultados de compatibilidade, execute o seguinte comando:

gcloud alpha container fleet mesh update --modernization-compatibility validation-disabled --project FLEET_PROJECT_ID

Esse comando remove as condições de compatibilidade de modernização dos estados de associação, bem como o status ModernizationCompatible dos CRs individuais do Istio.

Entender a compatibilidade

A compatibilidade com a modernização é informada usando condições no nível da frota e da associação (cluster). O sistema realiza várias verificações em diferentes momentos, e todas elas são executadas pelo menos uma vez por dia. Aguarde até um dia para que o status seja atualizado depois de ativar as verificações ou aplicar as correções.

Para ver esses resultados, recupere o status mais recente da malha com o seguinte comando:

gcloud container fleet mesh describe --project FLEET_PROJECT_ID

Compatibilidade no nível do cluster

Procure condições com gravidade WARNING ou ERROR em membershipStates.servicemesh para cada cluster provisionado do Cloud Service Mesh na frota. Se houver incompatibilidades, a saída será semelhante a esta:

membershipSpecs:
 projects/project_id/locations/global/memberships/cluster-a:
   mesh:
     management:MANAGEMENT_AUTOMATIC
membershipStates:
  projects/project_id/locations/global/memberships/cluster-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION
       details: 'Pod pod-a in namespace test-namespace: invalid annotations: ["status.sidecar.istio.io/port": failed to parse port - "invalid", port must be a number and should be in the range 1..65535]; unsupported annotations: ["ambient.istio.io/redirection"] .'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING
     - code: WORKLOAD_IDENTITY_REQUIRED
       details: 'Workload Identity is not enabled for the cluster or at least one of the node pools.'
       documentationLink: https://cloud.google.com/...
       severity: ERROR
...

Siga as documentationLink fornecidas em cada condição para entender e resolver a incompatibilidade específica.

Observação:as verificações de compatibilidade estão ativadas apenas para o canal de lançamento rápido do GKE. O suporte a outros canais de lançamento (Regular e Stable) será adicionado em breve. A lista de códigos de incompatibilidade fornecida não é exaustiva. Outros bloqueadores de modernização podem existir, e os detalhes deles serão adicionados com o tempo.

Resolver problemas de compatibilidade

Resolver anotações de pod incompatíveis

O código MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION indica que o cluster não pode ser modernizado para o plano de controle TRAFFIC_DIRECTOR porque determinados pods têm anotações do Istio inválidas ou sem suporte.

Exemplo de saída do comando gcloud container fleet mesh describe com a condição MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION definida para a assinatura:

membershipStates:
  projects/project_id/locations/global/memberships/membership-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION
       details: 'Pod pod-a in namespace test-namespace: invalid annotations: ["status.sidecar.istio.io/port": failed to parse port - "invalid", port must be a number and should be in the range 1..65535]; unsupported annotations: ["ambient.istio.io/redirection"] .'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING

Para resolver essas anotações de pod:

1. Identificar anotações problemáticas: verifique o campo details da condição de status para encontrar as chaves de anotação inválidas ou sem suporte. Encontre todos os pods com as chaves de anotação problemáticas.

2. Corrigir e verificar:

   1. Modifique as especificações YAML das suas implantações ou pods para remover ou alterar as anotações identificadas, garantindo que elas não incluam nenhuma anotação sem suporte. Aplique novamente o YAML atualizado ao cluster.
   2. Depois que todas as anotações do pod forem corrigidas, a condição MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION não vai mais aparecer para essa assinatura.

Resolver configurações incompatíveis

O código MODERNIZATION_INCOMPATIBLE_CONFIG indica que o cluster não pode ser modernizado para o plano de controle TRAFFIC_DIRECTOR devido a configurações incompatíveis. Essas incompatibilidades podem ser causadas por:

• Recursos personalizados (CRs) específicos do Istio que usam recursos ou campos sem suporte ou contêm valores inválidos.
• Configurações inválidas ou incompatíveis do Istio MeshConfig.
• Exceder os limites de escalonabilidade.
• Uso de anotações de serviço ou namespace não compatíveis.

Exemplo de saída do comando gcloud container fleet mesh describe com a condição MODERNIZATION_INCOMPATIBLE_CONFIG definida para a assinatura:

membershipSpecs:
 projects/project_id/locations/global/memberships/membership-a:
   mesh:
     management:MANAGEMENT_AUTOMATIC
membershipStates:
  projects/project_id/locations/global/memberships/membership-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_CONFIG
       details: 'One or more configs have warnings. Due to the following reason(s): Istio sidecar scale exceeds limit, MeshConfig "accessLogFile" is unsupported. Invalid Config Types: [Gateway, ServiceEntry], where more details are shown on individual config resources.See documentation link for more detail.'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING

Para resolver essas configurações:

1. Analise os detalhes da condição: verifique o campo details da condição de status. Ele resume erros individuais e identifica os tipos de recursos com problemas de configuração. No exemplo de detalhes fornecido, você precisaria resolver os problemas de escalonamento e MeshConfig e inspecionar os recursos Gateway e ServiceEntry em busca de erros.

2. Identificar e investigar recursos incompatíveis: use o seguinte script para listar todos os recursos personalizados (CRs) do Istio que não passaram nas verificações de compatibilidade. O script exige que kubectl e jq estejam instalados. A saída inclui os detalhes específicos do erro encontrados em status.conditions (tipo: ModernizationCompatible, status: "False") de cada recurso.

   for resource in authorizationpolicies destinationrules gateways proxyconfigs peerauthentications requestauthentications serviceentries sidecars telemetries virtualservices wasmplugins workloadentries workloadgroups; do
     echo "--- Checking $resource ---"
     kubectl get $resource --all-namespaces -o json | \
     jq -r '.items[] | select(.status.conditions != null and any(.status.conditions[]; .type == "ModernizationCompatible" and .status == "False")) | {"kind": .kind, "name": .metadata.name, "namespace": .metadata.namespace, "message": [.status.conditions[] | select(.type == "ModernizationCompatible").message]}'
   done
   

   Exemplo de resposta:

   --- Checking serviceentries ---
   {
     "kind": "ServiceEntry",
     "name": "demo-service-entry",
     "namespace": "se",
     "message": [
       "WARNING: unsupported resolution type: DNS_ROUND_ROBIN"
     ]
   }
   ..
   --- Checking workloadentries ---
   {
     "kind": "WorkloadEntry",
     "name": "demo-we",
     "namespace": "default",
     "message": [
       "WARNING: This API is not supported"
     ]
   }
   

3. Corrigir e aplicar configurações: modifique o YAML removendo os campos sem suporte ou substituindo valores inválidos por compatíveis. Para receber ajuda, consulte a documentação Recursos compatíveis com o Cloud Service Mesh gerenciado e APIs do Istio não compatíveis. Por exemplo, no exemplo fornecido, atualize a resolução ServiceEntry de DNS_ROUND_ROBIN para DNS.

4. Verificar correções: depois de aplicar as correções, aguarde até 24 horas para que as verificações periódicas atualizem o status.

   • A condição ModernizationCompatible nos recursos fixos deve mudar para status: "True". Verifique o status do recurso usando:

     kubectl get resource name -n namespace -o yaml
     

     Exemplo de saída:

     status:
       conditions:
       - lastTransitionTime: "2026-06-05T06:12:52.219963391Z"
         message: Resource is compatible for modernization
         reason: Compatible
         status: "True"
         type: ModernizationCompatible
     

   • Execute novamente o comando gcloud container fleet mesh describe. Depois que todos os problemas relacionados forem resolvidos, a condição MODERNIZATION_INCOMPATIBLE_CONFIG não vai mais aparecer para essa assinatura.