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 dela 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 da frota, que aciona uma auditoria contínua de todas as configurações do Istio, configurações de infraestrutura e parâmetros de escala. A ativação dessas verificações não faz mudanças na frota ou nos clusters. Ela apenas ativa os 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. Geralmente, 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 a compatibilidade de 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 de modernização é informada usando condições no nível da frota e da associação (cluster). O sistema realiza várias verificações em momentos diferentes, com todas as verificações sendo executadas pelo menos uma vez por dia. Aguarde até um dia para que o status seja atualizado após ativar as verificações ou aplicar 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/...
       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 o documentationLink fornecido 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 determinados pods têm anotações do Istio não compatíveis ou inválidas.

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

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 não compatíveis ou inválidas. Encontre todos os pods com as chaves de anotação problemáticas.

  2. Corrija e verifique:

    1. Modifique as especificações YAML das implantações ou dos pods para remover ou modificar as anotações identificadas, garantindo que elas não incluam anotações não compatíveis. Reaplique o YAML atualizado ao cluster.
    2. Depois que todas as anotações de pod forem corrigidas, a condição MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION não vai mais aparecer para essa associação.

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 surgir de:

  • Recursos personalizados (CRs) específicos do Istio que usam recursos ou campos não compatíveis ou contêm valores inválidos.
  • Configurações inválidas ou não compatí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 associação:

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. Para o exemplo de detalhes fornecido, você precisará resolver os problemas de escala e MeshConfig e inspecionar os recursos Gateway e ServiceEntry em busca de erros.

  2. Identifique e investigue recursos incompatíveis: use o seguinte script para listar todos os recursos personalizados (CRs) do Istio que falham nas verificações de compatibilidade. O script exige que kubectl e jq sejam 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. Corrija e aplique configurações: modifique o YAML removendo os campos não compatíveis ou substituindo valores inválidos por valores compatíveis. Para receber ajuda, consulte a documentação Recursos compatíveis do Cloud Service Mesh gerenciado e APIs do Istio não compatíveis. Por exemplo, no exemplo fornecido, atualize a ServiceEntry resolução de DNS_ROUND_ROBIN para DNS).

  4. Verifique as 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 corrigidos precisa 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 associação.

Resolver a escala de frota incompatível

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 compatíveis com a modernização.

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