Información sobre la compatibilidad de Cloud Service Mesh

En esta guía, se detalla cómo evaluar la compatibilidad de una flota para la modernización del plano de control. Para ello, se confirma que su configuración, infraestructura y escala sean compatibles con la implementación del plano de control TRAFFIC_DIRECTOR.

Habilita o inhabilita las verificaciones de compatibilidad

Para iniciar las verificaciones de compatibilidad, habilita el modo de validación para la flota, lo que activa una auditoría continua de todas las configuraciones de Istio, las configuraciones de infraestructura y los parámetros de escala. Habilitar estas verificaciones no realiza ningún cambio en tu flota ni en tus clústeres; solo habilita los informes de compatibilidad.

Habilita las verificaciones

Para comenzar la auditoría de compatibilidad, ejecuta el siguiente comando gcloud:

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

Reemplaza FLEET_PROJECT_ID por el ID de tu proyecto host de la flota. Por lo general, FLEET_PROJECT_ID tiene el mismo nombre que el proyecto.

Una vez habilitado, Cloud Service Mesh comienza a evaluar la flota y todos los clústeres aprovisionados de Cloud Service Mesh en la flota para la compatibilidad de modernización.

Inhabilita las verificaciones

Para detener la generación de informes de los resultados de compatibilidad, ejecuta el siguiente comando:

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

Este comando quita las condiciones de compatibilidad de modernización de los estados de membresía, así como el estado ModernizationCompatible de las CR de Istio individuales.

Información sobre la compatibilidad

La compatibilidad de modernización se informa mediante condiciones a nivel de la flota y de la membresía (clúster). El sistema realiza varias verificaciones en diferentes momentos, y todas las verificaciones se ejecutan al menos una vez al día. Espera hasta un día para que se actualice el estado después de habilitar las verificaciones o aplicar correcciones.

Para ver estos resultados, recupera el estado más reciente de la malla con el siguiente comando:

gcloud container fleet mesh describe --project FLEET_PROJECT_ID

Compatibilidad a nivel de clúster

Busca condiciones con gravedad WARNING o ERROR en membershipStates.servicemesh para cada clúster aprovisionado de Cloud Service Mesh en la flota. Si existen incompatibilidades, el resultado será similar al siguiente:

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
...

Sigue el documentationLink que se proporciona en cada condición para comprender y resolver la incompatibilidad específica.

Resuelve problemas de compatibilidad

Resuelve anotaciones de pod incompatibles

El código MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION indica que el clúster no se puede modernizar al plano de control TRAFFIC_DIRECTOR porque ciertos pods tienen anotaciones de Istio no compatibles o no válidas.

Resultado de ejemplo del comando gcloud container fleet mesh describe con la condición MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION establecida para la membresía:

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 estas anotaciones de pod, haz lo siguiente:

  1. Identifica las anotaciones problemáticas: Revisa el campo details de la condición de estado para encontrar las claves de anotación no compatibles o no válidas. Busca todos los pods con las claves de anotación problemáticas.

  2. Corrige y verifica:

    1. Modifica las especificaciones de YAML para tus implementaciones o pods para quitar o modificar las anotaciones identificadas y asegurarte de que no incluyan anotaciones no compatibles. Vuelve a aplicar el YAML actualizado a tu clúster.
    2. Una vez que se corrijan todas las anotaciones de pod, la condición MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION ya no aparecerá para esa membresía.

Resuelve configuraciones incompatibles

El código MODERNIZATION_INCOMPATIBLE_CONFIG indica que el clúster no se puede modernizar al plano de control TRAFFIC_DIRECTOR debido a configuraciones incompatibles. Estas incompatibilidades pueden deberse a lo siguiente:

  • Recursos personalizados (CR) de Istio específicos que usan funciones o campos no compatibles o que contienen valores no válidos
  • Configuración de Istio MeshConfig no válida o no compatible
  • Superación de los límites de escalabilidad
  • Uso de anotaciones de servicio o espacio de nombres no compatibles

Resultado de ejemplo del comando gcloud container fleet mesh describe con la condición MODERNIZATION_INCOMPATIBLE_CONFIG establecida para la membresía:

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 estas configuraciones, haz lo siguiente:

  1. Analiza los detalles de la condición: Revisa el campo details de la condición de estado. Resume los errores individuales y, además, identifica los tipos de recursos con problemas de configuración. En el ejemplo de detalles proporcionado, deberás abordar los problemas de escala y MeshConfig, y también inspeccionar los recursos Gateway y ServiceEntry en busca de errores.

  2. Identifica y analiza los recursos incompatibles: Usa la siguiente secuencia de comandos para enumerar todos los recursos personalizados (CR) de Istio que no superan las verificaciones de compatibilidad. La secuencia de comandos requiere que se instalen kubectl y jq. El resultado incluye los detalles específicos del error que se encuentran en status.conditions (tipo: ModernizationCompatible, estado: "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

    Resultado de ejemplo:

    --- 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. Corrige y aplica las configuraciones: Modifica tu YAML quitando los campos no compatibles o reemplazando los valores no válidos por valores compatibles. Para obtener ayuda, consulta la documentación sobre las funciones compatibles de Cloud Service Mesh administrado y las APIs de Istio no compatibles. (Por ejemplo, en el ejemplo proporcionado, actualiza la ServiceEntry resolución de DNS_ROUND_ROBIN a DNS).

  4. Verifica las correcciones: Después de aplicar las correcciones, espera hasta 24 horas para que las verificaciones periódicas actualicen el estado.

    • La condición ModernizationCompatible de los recursos corregidos debe cambiar a estado: "True". Verifica el estado del recurso con lo siguiente:

      kubectl get resource name -n namespace -o yaml

      Resultado de ejemplo:

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

    • Vuelve a ejecutar el comando gcloud container fleet mesh describe. Una vez que se resuelvan todos los problemas relacionados, la condición MODERNIZATION_INCOMPATIBLE_CONFIG ya no aparecerá para esa membresía.