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, 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 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/v1.29/...
       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/v1.29/...
       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 e garanta 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/v1.29/...
       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 de 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 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.

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: