v1.21 서비스 메시 문서를 보고 있습니다.

사용 가능한 버전

Cloud Service Mesh
1.22 보관 파일
1.21 보관 파일
1.20 보관 파일
1.19 보관 파일
1.18 보관 파일

관리형 Cloud Service Mesh 문제 해결

이 문서에서는 포드가 istio.istio-system과 함께 삽입되면 설치 도구에서 HTTP 400 상태 코드 및 클러스터 멤버십 오류와 같은 오류를 생성하는 경우와 같은 일반적인 Cloud Service Mesh 문제와 해결 방법을 설명합니다

Cloud Service Mesh 문제 해결에 추가 지원이 필요하면 지원 받기를 참조하세요.

버전이 비정상 오류로 보고됨

관리형 Cloud Service Mesh의 서비스 에이전트에 필요한 Identity and Access Management(IAM) 역할이 없으면 일반적인 Revision(s) reporting unhealthy 오류가 표시될 수 있습니다. 일반적으로 이는 Terraform, Puppet 또는 CI/CD 재구성을 통해 역할이 취소되면 발생합니다.

이 오류를 해결하는 단계는 Google Cloud 콘솔 또는 Google Cloud CLI 중 무엇을 사용하는지에 따라 다릅니다.

Google Cloud 콘솔

Google Cloud 콘솔에서 IAM 및 관리자 > IAM으로 이동합니다.
Google 제공 역할 부여 포함을 선택합니다.
주 구성원 목록을 검토합니다.

필요한 IAM 역할이 있는 서비스 에이전트가 목록에 표시되면 올바르게 구성된 것입니다.

참고: 서비스 에이전트 식별자의 형식은 service-PROJECT_NUMBER@gcp-sa-servicemesh.iam.gserviceaccount.com이며 필요한 IAM 역할은 Anthos Service Mesh 서비스 에이전트(roles/anthosservicemesh.serviceAgent)입니다.

목록에 서비스 에이전트와 필수 역할이 포함되어 있지 않으면 다음 단계를 진행합니다.
프로젝트의 Cloud Service Mesh 서비스 에이전트에 Anthos Service Mesh 서비스 에이전트 역할(roles/anthosservicemesh.serviceAgent)을 부여합니다. 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

참고: 이 변경사항을 되돌리는 자동화된 도구가 없는지 확인하세요. 오류가 반복되면 관련 구성이나 허용 목록을 업데이트하세요.

Google Cloud CLI

Google Cloud CLI에서 다음 명령어를 실행하여 필요한 IAM 역할이 부여되었는지 확인합니다.

gcloud projects get-iam-policy PROJECT_ID  \
--flatten="bindings[].members" \
--filter="bindings.members:serviceAccount:service-PROJECT_NUMBER@gcp-sa-servicemesh.iam.gserviceaccount.com AND bindings.role:roles/anthosservicemesh.serviceAgent" \
--format='table(bindings.role)'

ROLE 목록을 검토하세요.

목록에 역할이 표시되면 올바르게 구성된 것입니다.

목록에 역할이 표시되지 않는다면 필요한 역할이 취소된 것입니다.
서비스 에이전트에게 필요한 역할을 부여하려면 다음 명령어를 실행합니다.
```
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-servicemesh.iam.gserviceaccount.com" \
 --role="roles/anthosservicemesh.serviceAgent"
```
참고: 이 변경사항을 되돌리는 자동화된 도구가 없는지 확인하세요. 오류가 반복되면 관련 구성이나 허용 목록을 업데이트하세요.

설치 도구로 HTTP 400 오류 발생

설치 도구는 다음과 같이 HTTP 400 오류를 발생시킬 수 있습니다.

HealthCheckContainerError, message: Cloud Run error: Container failed to start.
Failed to start and then listen on the port defined by the PORT environment
variable. Logs for this revision might contain more information.

이 오류는 Kubernetes 클러스터에서 워크로드 아이덴티티를 사용 설정하지 않았을 때 발생할 수 있으며, 사용 설정하려면 다음 명령어를 사용하면 됩니다.

export CLUSTER_NAME=...
export PROJECT_ID=...
export LOCATION=...
gcloud container clusters update $CLUSTER_NAME --zone $LOCATION \
    --workload-pool=$PROJECT_ID.svc.id.goog

관리형 데이터 영역 상태

다음 명령어는 관리형 데이터 영역의 상태를 표시합니다.

gcloud container fleet mesh describe --project PROJECT_ID

다음 표에는 가능한 모든 관리형 데이터 영역 상태가 나와 있습니다.

상태	코드	설명
`ACTIVE`	`OK`	관리형 데이터 영역이 정상적으로 실행 중입니다.
`DISABLED`	`DISABLED`	이를 사용하도록 구성된 네임스페이스나 버전이 없으면 관리형 데이터 영역이 이 상태가 됩니다. 안내에 따라 Fleet API를 통해 관리형 Cloud Service Mesh를 사용 설정하거나 `asmcli`로 관리형 Cloud Service Mesh를 프로비저닝한 후 관리형 데이터 영역을 사용 설정합니다. 관리형 데이터 영역 상태 보고는 네임스페이스나 버전에 주석을 추가하여 관리형 데이터 영역을 사용 설정한 경우에만 사용 가능합니다. 개별 포드에 주석을 추가하면 해당 포드가 관리되지만 주석이 추가된 네임스페이스나 버전이 없으면 기능이 `DISABLED` 상태가 됩니다.
`FAILED_PRECONDITION`	`MANAGED_CONTROL_PLANE_REQUIRED`	관리형 데이터 영역에는 활성 관리형 Cloud Service Mesh 컨트롤 플레인이 필요합니다.
`PROVISIONING`	`PROVISIONING`	관리형 데이터 영역을 프로비저닝하는 중입니다. 이 상태가 10분 넘게 지속되면 오류가 발생했을 수 있으며 지원팀에 문의해야 합니다.
`STALLED`	`INTERNAL_ERROR`	내부 오류 조건으로 인해 관리형 데이터 영역이 작동하지 못하도록 차단되었습니다. 문제가 지속되면 지원팀에 문의하세요.
`NEEDS_ATTENTION`	`UPGRADE_FAILURES`	서비스를 정상 상태로 되돌리려면 관리형 데이터 영역에 수동으로 개입해야 합니다. 이 문제에 대한 자세한 내용과 해결 방법은 `NEEDS_ATTENTION` 상태를 참조하세요.

`NEEDS_ATTENTION` state

gcloud container fleet mesh describe 명령어에서 관리형 데이터 영역 상태가 NEEDS_ATTENTION 상태이고 코드가 UPGRADE_FAILURES인 경우 관리형 데이터 영역이 특정 워크로드를 업그레이드하지 않은 것입니다. 추가 분석을 위해 관리형 데이터 영역 서비스에서 이러한 워크로드에 dataplane-upgrade: failed 라벨을 지정합니다. 프록시를 업그레이드하려면 수동으로 다시 시작해야 합니다. 주의를 필요한 포드 목록을 가져오려면 다음 명령어를 실행합니다.

kubectl get pods --all-namespaces -l dataplane-upgrade=failed

클러스터 멤버십 오류(ID 공급업체가 지정되지 않음)

다음과 같은 클러스터 멤버십 오류와 함께 설치 도구가 실패할 수 있습니다.

asmcli: [ERROR]: Cluster has memberships.hub.gke.io CRD but no identity
provider specified. Please ensure that an identity provider is available for the
registered cluster.

이 오류는 클러스터를 등록하기 전에 GKE 워크로드 아이덴티티를 사용 설정하지 않은 경우에 발생할 수 있습니다. gcloud container fleet memberships register --enable-workload-identity 명령어를 사용하여 명령줄에서 클러스터를 다시 등록할 수 있습니다.

관리형 컨트롤 플레인 상태 확인

관리형 컨트롤 플레인 상태를 확인하려면 gcloud container fleet mesh describe --project FLEET_PROJECT_ID를 실행합니다.

응답의 membershipStates[].servicemesh.controlPlaneManagement.details 필드에서 구체적인 오류를 설명할 수 있습니다.

더 많은 세부정보가 필요하면 클러스터에서 관리형 컨트롤 플레인이 프로비저닝되거나 프로비저닝에 실패할 때 업데이트되는 ControlPlaneRevision 커스텀 리소스를 확인합니다.

리소스 상태를 검사하려면 NAME을 asm-managed, asm-managed-stable 또는 asm-managed-rapid 채널에 해당하는 값으로 바꿉니다.

kubectl describe controlplanerevision NAME -n istio-system

출력은 다음과 비슷합니다.

    Name:         asm-managed

    …

    Status:
      Conditions:
        Last Transition Time:  2021-08-05T18:56:32Z
        Message:               The provisioning process has completed successfully
        Reason:                Provisioned
        Status:                True
        Type:                  Reconciled
        Last Transition Time:  2021-08-05T18:56:32Z
        Message:               Provisioning has finished
        Reason:                ProvisioningFinished
        Status:                True
        Type:                  ProvisioningFinished
        Last Transition Time:  2021-08-05T18:56:32Z
        Message:               Provisioning has not stalled
        Reason:                NotStalled
        Status:                False
        Type:                  Stalled

Reconciled 조건에 따라 관리형 제어 영역이 올바르게 실행되는지 여부가 결정됩니다. true이면 제어 영역이 성공적으로 실행됩니다. Stalled는 관리형 제어 영역 프로비저닝 프로세스에 오류가 발생했는지 여부를 결정합니다. Stalled이면 Message 필드에 특정 오류에 대한 추가 정보가 포함됩니다. 발생 가능한 오류에 대한 자세한 내용은 중단 코드를 참조하세요.

ControlPlaneRevision 중단 코드

ControlPlaneRevisions 상태에서 Stalled 조건이 true가 될 수 있는 이유는 다양합니다.

이유	메시지	설명
PreconditionFailed	GKE 멤버십만 지원되지만 ${CLUSTER_NAME}은(는) GKE 클러스터가 아닙니다.	현재 클러스터가 GKE 클러스터로 표시되지 않습니다. 관리형 제어 영역이 GKE 클러스터에서만 작동합니다.
	지원되지 않는 ControlPlaneRevision 이름: ${NAME}	ControlPlaneRevision의 이름은 다음 중 하나여야 합니다. asm-managed asm-managed-rapid asm-managed-stable
	지원되지 않는 ControlPlaneRevision 네임스페이스: ${NAMESPACE}	ControlPlaneRevision의 네임스페이스는 `istio-system`이어야 합니다.
	이름이 ${NAME}인 ControlPlaneRevision에 대해 지원되지 않는 채널 ${CHANNEL}. ${OTHER_CHANNEL} 필요	ControlPlaneRevision의 이름은 다음과 같이 ControlPlaneRevision의 채널과 일치해야 합니다. asm-managed -> 일반 asm-managed-rapid -> 신속 asm-managed-stable -> 정식
	채널을 생략하거나 비워 둘 수 없습니다.	`Channel`은 ControlPlaneRevision의 필수 필드입니다. 커스텀 리소스에 없거나 비어 있습니다.
	지원되지 않는 제어 영역 버전 유형: ${TYPE}	`managed_service`는 ControlPlaneRevisionType의 유일한 허용 필드입니다.
	지원되지 않는 Kubernetes 버전: ${VERSION}	Kubernetes 버전 1.15 이상이 지원됩니다.
	워크로드 아이덴티티가 사용 설정되지 않음	클러스터에서 워크로드 아이덴티티를 사용 설정하세요.
	지원되지 않는 워크로드 풀: ${POOL}	워크로드 풀은 `${PROJECT_ID}.svc.id.goog` 형식이어야 합니다.
	ProvisioningFailed	클러스터 리소스를 업데이트하는 중 오류 발생	Google에서 CRD 및 웹훅과 같은 클러스터 내 리소스를 업데이트할 수 없습니다.
MutatingWebhookConfiguration 'istiod-asm-managed'에는 URL이 예상된 ${EXPECTED_URL}을(를) 제외하고 ${EXISTING_URL}인 웹훅이 포함됩니다.		Google은 설치 손상을 방지하기 위해 기존 웹훅을 덮어쓰지 않습니다. 이 작업을 수행하려면 이를 수동으로 업데이트하세요.
ValidatingWebhookConfiguration ${NAME}에 URL이 예상된 ${EXPECTED_URL}을(를) 제외하고 ${EXISTING_URL}인 웹훅이 포함됩니다.		Google은 설치 손상을 방지하기 위해 기존 웹훅을 덮어쓰지 않습니다. 이 작업을 수행하려면 이를 수동으로 업데이트하세요.

관리형 Cloud Service Mesh를 GKE 클러스터에 연결할 수 없음

2022년 6월부터 2022년 9월까지 Google은 Google Kubernetes Engine(GKE)에서 승인된 네트워크, Cloud Run, Cloud Run Functions와 관련된 보안 작업을 완료했습니다. 이전에는 관리형 Cloud Service Mesh를 사용했지만 마이그레이션 전에 사용을 중지한 프로젝트에는 Cloud Run과 GKE 간의 통신에 필요한 API가 없습니다.

이 시나리오에서는 관리형 Cloud Service Mesh 프로비저닝이 실패하고 Cloud Logging에 다음 오류 메시지가 표시됩니다.

Connect Gateway API has not been used in project [*PROJECT_NUMBER*] before or it is disabled.
Enable it by visiting https://console.developers.google.com/apis/api/connectgateway.googleapis.com/overview?project=[*PROJECT_NUMBER*] then retry.
If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.

다음 쿼리를 사용하여 이 메시지를 필터링합니다.

resource.type="istio_control_plane"
resource.labels.project_id=[*PROJECT_ID*]
resource.labels.location=[*REGION*]
severity=ERROR
jsonPayload.message=~"Connect Gateway API has not been used in project"

그동안 사이드카 삽입 및 Cloud Service Mesh 관련 Kubernetes 커스텀 리소스 배포도 실패하고 Cloud Logging에 다음 경고 메시지가 표시됩니다.

Error creating: Internal error occurred: failed calling webhook
"rev.namespace.sidecar-injector.istio.io": failed to call webhook: an error on
the server ("unknown") has prevented the request from succeeding.

다음 쿼리를 사용하여 이 메시지를 필터링합니다.

resource.type="k8s_cluster"
resource.labels.project_id=[*PROJECT_ID*]
resource.labels.location=[*REGION*]
resource.labels.cluster_name=[*CLUSTER_NAME*]
severity=WARNING
jsonPayload.message=~"Internal error occurred: failed calling webhook"

문제를 해결하려면 다음 안내를 따르세요.

필요한 connectgateway API를 사용 설정합니다.

 gcloud services enable connectgateway.googleapis.com --project=[*PROJECT_ID*]

관리형 Cloud Service Mesh를 재설치합니다.
워크로드에서 순차적 재시작을 수행합니다.

Google Cloud API가 사용 설정되어 있지 않음

관리형 Cloud Service Mesh Fleet에서 TRAFFIC_DIRECTOR 컨트롤 플레인 구현을 사용하는 경우에는 특정 API를 사용 설정해야 합니다.

관리형 Cloud Service Mesh를 사용하지 않을 때 '사용 중지할 수 있음'으로 표시된 API를 포함한 모든 필수 API를 사용 설정합니다.

gcloud services enable --project=[*PROJECT_ID*] \
    trafficdirector.googleapis.com \
    networkservices.googleapis.com \
    networksecurity.googleapis.com

이 변경사항을 되돌리는 자동화된 도구가 없는지 확인합니다. 오류가 반복되면 관련 구성이나 허용 목록을 업데이트합니다.

NodePool GKE용 워크로드 아이덴티티 제휴가 사용 중지됨

다음 명령어는 관리형 Cloud Service Mesh의 상태를 표시합니다.

    gcloud container fleet mesh describe

멤버십의 Conditions 필드에 NODEPOOL_WORKLOAD_IDENTITY_FEDERATION_REQUIRED 오류 코드가 표시될 수 있습니다.

    membershipStates:
      projects/test-project/locations/us-central1/memberships/my-membership:
        servicemesh:
          conditions:
          - code: NODEPOOL_WORKLOAD_IDENTITY_FEDERATION_REQUIRED
            details: One or more node pools have workload identity federation disabled.
            documentationLink: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity
            severity: ERROR
          controlPlaneManagement:
            details:
            - code: REVISION_FAILED_PRECONDITION
              details: Required in-cluster components are not ready. This will be retried
                within 15 minutes.
            implementation: TRAFFIC_DIRECTOR
            state: FAILED_PRECONDITION

Cloud Service Mesh 설치의 기본 요건이므로 GKE 클러스터의 모든 노드 풀에 워크로드 아이덴티티 제휴가 사용 설정되어 있지 않으면 이 오류가 표시됩니다.

이 오류 메시지를 해결하려면 모든 노드 풀에서 워크로드 아이덴티티 제휴 사용 설정 안내를 따라야 합니다. 사용 설정 여부는 특정 클러스터 케이스에 따라 다를 수 있습니다.

사용 설정 후 오류 메시지가 자동으로 삭제되고 클러스터가 ACTIVE 상태로 돌아갑니다. 문제가 지속되고 추가 지원이 필요하면 지원 받기를 참조하세요.