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 수준 호환성

state.servicemesh.conditions에서 Fleet의 전체 현대화 상태를 확인합니다.

  • Fleet이 호환됨: Fleet이 호환되면 코드 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

  • Fleet이 호환되지 않음: Fleet이 아직 현대화와 호환되지 않는 경우 코드 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

    차량의 호환성이 없는 경우 특정 격차의 조건을 검토하세요. membershipStates.servicemesh에서 차단 문제를 해결하기 위해 추가 WARNING 또는 ERROR 심각도 Fleet 수준 조건과 클러스터 수준 조건을 확인합니다.

클러스터 수준 호환성

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 조건이 status: "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 조건이 표시되지 않습니다.

호환되지 않는 Fleet 규모 해결

MODERNIZATION_INCOMPATIBLE_FLEET_SCALE 코드는 Fleet의 리소스 규모가 현대화에 지원되는 한도를 초과하므로 TRAFFIC_DIRECTOR 컨트롤 플레인으로 현대화할 수 없음을 나타냅니다.

이 단계에서는 다음과 같은 제한으로 차량을 현대화하는 것을 지원합니다.

  • 전체 fleet에서 최대 1,500개의 데이터 플레인 엔드포인트 (프록시)
  • 전체 Fleet에 걸쳐 최대 200개의 Cloud Service Mesh 서비스