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 que 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, o 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 na frota 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 conferir 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 da frota

Confira o status geral de modernização da sua frota em state.servicemesh.conditions.

• A frota é compatível: se a frota for compatível, você vai encontrar uma condição com o código MODERNIZATION_COMPATIBLE:

  name: projects/project_id/locations/global/features/servicemesh
  state:
    servicemesh:
      conditions:
      - code: MODERNIZATION_COMPATIBLE
        details: 'Fleet is eligible for modernization.'
        documentationLink: https://cloud.google.com/service-mesh/...
        severity: INFO
  

• A frota não é compatível: se a frota ainda não for compatível com a modernização, você vai encontrar uma condição com o código MODERNIZATION_INCOMPATIBLE:

  name: projects/project_id/locations/global/features/servicemesh
  state:
    servicemesh:
      conditions:
      - code: MODERNIZATION_INCOMPATIBLE
        details: 'Fleet is not yet eligible for modernization.'
        documentationLink: https://cloud.google.com/service-mesh/...
        severity: INFO
  

  Se a frota for incompatível, revise as condições para lacunas específicas. Verifique outras condições de gravidade WARNING ou ERROR no nível da frota e do cluster em membershipStates.servicemesh para resolver bloqueios.

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.

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 alguns pods têm anotações do Istio sem suporte ou inválidas.

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. Identifique 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 para suas implantações ou pods para garantir que eles usem apenas anotações compatíveis (todas as outras anotações não são compatíveis). Remova as anotações incompatíveis, corrija os valores inválidos e reaplique 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, na sigla em inglês) específicos do Istio que usam recursos ou campos sem suporte ou contêm valores inválidos.
• Configurações MeshConfig do Istio inválidas ou sem suporte.
• 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. Identifique e investigue recursos incompatíveis: use o seguinte script de exemplo para listar recursos personalizados (CRs) do Istio que não passaram nas verificações de compatibilidade. Este script é fornecido como um exemplo. Revise e analise para garantir que ele atenda aos requisitos operacionais e do ambiente antes de executá-lo no cluster. 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 envoyfilters gateways peerauthentications proxyconfigs 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 não aceitos 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 vai mudar para o 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. Quando todos os problemas relacionados forem resolvidos, a condição MODERNIZATION_INCOMPATIBLE_CONFIG não vai mais aparecer para essa assinatura.

Observação:a validação de compatibilidade para ConfigMaps não é compatível com relatórios de canais. Os recursos disponíveis apenas em canais de lançamento específicos são informados como não compatíveis em todos os canais durante as verificações de qualificação. Para mais informações sobre a disponibilidade de recursos, consulte Recursos compatíveis do Cloud Service Mesh gerenciado.

Resolver incompatibilidade de escala da frota

O código MODERNIZATION_INCOMPATIBLE_FLEET_SCALE indica que a frota não pode ser modernizada para o plano de controle TRAFFIC_DIRECTOR porque a escala de recursos na frota excede os limites aceitos para modernização.

Nesta fase, oferecemos suporte à modernização de frotas com os seguintes limites:

• Até 1.500 endpoints (proxies) do plano de dados em toda a frota.
• Até 200 serviços do Cloud Service Mesh na frota.

Observação:os limites para modernização são menores do que os limites de escalonamento de estado estável compatíveis com o plano de controle TRAFFIC_DIRECTOR. Para mais informações sobre os serviços e o escalonamento do Cloud Service Mesh, consulte Limites de escalonamento do Cloud Service Mesh no GKE.