Cloud Service Mesh 호환성 이해

이 가이드에서는 구성, 인프라, 규모가 TRAFFIC_DIRECTOR 컨트롤 플레인 구현과 호환되는지 확인하여 Fleet의 컨트롤 플레인 현대화 호환성을 평가하는 방법을 자세히 설명합니다.

호환성 검사 선택 또는 선택 해제

호환성 검사를 시작하려면 Fleet의 유효성 검사 모드를 사용 설정합니다. 그러면 모든 Istio 구성, 인프라 구성, 규모 매개변수에 대한 지속적인 감사가 트리거됩니다. 이러한 검사를 사용 설정해도 Fleet 또는 클러스터가 변경되지는 않습니다. 호환성 보고만 사용 설정됩니다.

검사 사용 설정

호환성 감사를 시작하려면 다음 gcloud 명령어를 실행합니다.

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

FLEET_PROJECT_ID를 Fleet 호스트 프로젝트의 ID로 바꿉니다. 일반적으로 FLEET_PROJECT_ID는 프로젝트와 이름이 같습니다.

사용 설정되면 Cloud Service Mesh는 Fleet 및 Fleet에서 프로비저닝된 모든 Cloud Service Mesh 클러스터의 현대화 호환성을 평가하기 시작합니다.

검사 사용 중지

호환성 결과 보고를 중지하려면 다음 명령어를 실행합니다.

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

이 명령어는 멤버십 상태에서 현대화 호환성 조건을 삭제하고 개별 Istio CR에서 ModernizationCompatible 상태를 삭제합니다.

호환성 이해

현대화 호환성은 Fleet 및 멤버십 (클러스터) 수준 모두에서 조건을 사용하여 보고됩니다. 시스템은 다양한 시간에 다양한 검사를 수행하며 모든 검사는 하루에 한 번 이상 실행됩니다. 검사를 사용 설정하거나 수정을 적용한 후 상태가 업데이트되는 데 최대 하루가 걸릴 수 있습니다.

이러한 결과를 보려면 다음 명령어를 사용하여 최신 메시 상태를 가져옵니다.

gcloud container fleet mesh describe --project FLEET_PROJECT_ID

클러스터 수준 호환성

Fleet의 각 Cloud Service Mesh 프로비저닝 클러스터에 대해 membershipStates.servicemesh 아래에 WARNING 또는 ERROR 심각도가 있는 조건을 찾습니다. 비호환성이 있는 경우 출력은 다음과 비슷합니다.

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

각 조건 내에 제공된 documentationLink를 따라 특정 비호환성을 이해하고 해결합니다.

호환성 문제 해결

호환되지 않는 포드 주석 해결

MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION 코드는 특정 포드에 지원되지 않거나 잘못된 Istio 주석이 있으므로 클러스터를 TRAFFIC_DIRECTOR 컨트롤 플레인으로 현대화할 수 없음을 나타냅니다.

멤버십에 대해 MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION 조건이 설정된 gcloud container fleet mesh describe 명령어의 출력 예시:

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

이러한 포드 주석을 해결하려면 다음 단계를 따르세요.

  1. 문제 주석 식별: 상태 조건의 details 필드를 확인하여 지원되지 않거나 잘못된 주석 키를 찾습니다. 문제가 있는 주석 키가 있는 모든 포드를 찾습니다.

  2. 수정 및 확인:

    1. 배포 또는 포드의 YAML 사양을 수정하여 식별된 주석을 삭제하거나 수정하고 지원되지 않는 주석이 포함되지 않도록 합니다. 업데이트된 YAML을 클러스터에 다시 적용합니다.
    2. 모든 포드 주석이 수정되면 해당 멤버십에 더 이상 MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION 조건이 표시되지 않습니다.

호환되지 않는 구성 해결

MODERNIZATION_INCOMPATIBLE_CONFIG 코드는 호환되지 않는 구성으로 인해 클러스터를 TRAFFIC_DIRECTOR 컨트롤 플레인으로 현대화할 수 없음을 나타냅니다. 이러한 비호환성은 다음에서 비롯될 수 있습니다.

  • 지원되지 않는 기능 또는 필드를 사용하거나 잘못된 값을 포함하는 특정 Istio 커스텀 리소스 (CR).
  • 잘못되었거나 지원되지 않는 Istio MeshConfig 설정.
  • 확장성 한도 초과.
  • 지원되지 않는 서비스 또는 네임스페이스 주석 사용.

멤버십에 대해 MODERNIZATION_INCOMPATIBLE_CONFIG 조건이 설정된 gcloud container fleet mesh describe 명령어의 출력 예시:

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

이러한 구성을 해결하려면 다음 단계를 따르세요.

  1. 조건 세부정보 분석: 상태 조건의 details 필드를 확인합니다. 개별 오류를 요약하고 구성 문제가 있는 리소스 유형을 식별합니다. 제공된 세부정보 예시의 경우 규모 및 MeshConfig 문제를 해결하고 Gateway 및 ServiceEntry 리소스에서 오류를 검사해야 합니다.

  2. 호환되지 않는 리소스 식별 및 조사: 다음 스크립트를 사용하여 호환성 검사에 실패한 모든 Istio 커스텀 리소스 (CR)를 나열합니다. 스크립트를 실행하려면 kubectl 및 jq가 설치되어 있어야 합니다. 출력에는 각 리소스의 status.conditions (유형: ModernizationCompatible, 상태: "False") 아래에 있는 특정 오류 세부정보가 포함됩니다.

    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

    출력 예시:

    --- 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. 구성 수정 및 적용: 지원되지 않는 필드를 삭제하거나 잘못된 값을 호환되는 값으로 바꿔 YAML을 수정합니다. 도움이 필요하면 관리형 Cloud Service Mesh의 지원되는 기능 및 지원되지 않는 Istio API 문서를 참조하세요. (예를 들어 제공된 예시에서 ServiceEntry 확인을 DNS_ROUND_ROBIN에서 DNS로 업데이트합니다.)

  4. 수정 확인: 수정을 적용한 후 주기적인 검사에서 상태를 업데이트하는 데 최대 24시간이 걸릴 수 있습니다.

    • 수정된 리소스의 ModernizationCompatible 조건이 상태: "True"로 변경되어야 합니다. 다음을 사용하여 리소스의 상태를 확인합니다.

      kubectl get resource name -n namespace -o yaml

      출력 예시:

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

    • gcloud container fleet mesh describe 명령어를 다시 실행합니다. 모든 관련 문제가 해결되면 해당 멤버십에 더 이상 MODERNIZATION_INCOMPATIBLE_CONFIG 조건이 표시되지 않습니다.