Noções básicas sobre a compatibilidade do Cloud Service Mesh

A implementação do plano de controle ISTIOD foi descontinuada. É necessário avaliar a compatibilidade, resolver as condições de bloqueio nas frotas e modernizar antes do prazo de fim do suporte.

Neste guia, detalhamos 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 do 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 mudanças na frota ou nos clusters, 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. 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 pelo Cloud Service Mesh na frota para verificar a compatibilidade com a modernização.

Desativar verificações

Para interromper o relatório 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 assinatura (cluster). O sistema realiza várias verificações em momentos diferentes, 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 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ê verá 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 identificar lacunas específicas. Verifique se há outras condições de nível de frota com gravidade WARNING ou ERROR, além de condições de nível de cluster em membershipStates.servicemesh, para resolver possíveis 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 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 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 incompatíveis ou inválidas. Encontre todos os pods com as chaves de anotação problemáticas.

  2. Corrigir e verificar:

    1. Modifique as especificações YAML das implantações ou dos 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 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 não compatíveis ou que contêm valores inválidos.
  • Configurações inválidas ou incompatíveis do MeshConfig do Istio.
  • 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 script de exemplo a seguir para listar os recursos personalizados (CRs, na sigla em inglês) do Istio que não passam nas verificações de compatibilidade. Este script é fornecido como exemplo. Analise-o para garantir que ele atenda aos requisitos operacionais e de ambiente antes de executá-lo no cluster. O script requer que kubectl e jq estejam instalados. A saída inclui os detalhes de erro específicos 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 compatíveis ou substituindo valores inválidos por outros compatíveis. Para ajuda, consulte a documentação Recursos compatíveis do Cloud Service Mesh gerenciado e Suporte à API no Cloud Service Mesh gerenciado. Por exemplo, no exemplo fornecido, atualize a resolução de 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 corrigidos precisa 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. Depois que todos os problemas relacionados forem resolvidos, a condição MODERNIZATION_INCOMPATIBLE_CONFIG não vai mais aparecer para essa assinatura.

Resolver 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 aceitos para modernização.

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