이 문서에서 설명하는 제품인 AWS용 GKE는 현재 유지보수 모드에 있으며 2027년 3월 17일에 종료될 예정입니다.

클러스터 생성 또는 업데이트 문제 해결

이 페이지에서는 AWS용 GKE 설치 또는 업그레이드와 관련된 문제를 해결하는 방법을 설명합니다.

추가 지원이 필요하면 Cloud Customer Care에 문의하세요.

클러스터 만들기 실패

클러스터 만들기를 요청하면 AWS용 GKE는 먼저 일련의 실행 전 테스트를 실행하여 요청을 확인합니다. 클러스터 생성에 실패한다면 실행 전 테스트 중 하나가 실패했거나 클러스터 생성 프로세스 자체의 단계가 완료되지 않았기 때문일 수 있습니다.

실행 전 테스트가 실패하면 클러스터가 리소스를 만들지 않고 오류에 대한 정보를 사용자에게 직접 반환합니다. 예를 들어 이름이 invalid%%%name인 클러스터를 만들려고 하면 유효한 클러스터 이름에 대한 실행 전 테스트가 실패하고 요청에서 다음과 같은 오류를 반환합니다.

ERROR: (gcloud.container.aws.clusters.create) INVALID_ARGUMENT: must be
between 1-63 characters, valid characters are /[a-z][0-9]-/, should start with a
letter, and end with a letter or a number: "invalid%%%name",
field: aws_cluster_id

실행 전 테스트를 통과한 후에도 클러스터 생성에 실패할 수 있습니다. 이런 일은 클러스터 생성이 시작된 후, AWS용 GKE가 Google Cloud 및 AWS에서 리소스를 생성한 지 몇 분 후에 일어나기도 합니다. 이 경우 AWS 리소스는 상태가 ERROR로 설정된 Google Cloud 프로젝트에 위치하게 됩니다.

실패에 대한 세부정보를 가져오려면 다음 명령어를 실행하세요.

gcloud container aws clusters describe CLUSTER_NAME \
    --location GOOGLE_CLOUD_LOCATION \
    --format "value(state, errors)"

다음을 바꿉니다.

CLUSTER_NAME: 상태를 쿼리하는 클러스터의 이름
GOOGLE_CLOUD_LOCATION: 이 AWS 클러스터를 관리하는 Google Cloud 리전의 이름

또는 생성 클러스터 API 호출과 연결된 Operation 리소스를 설명하여 생성 실패에 대한 세부정보를 가져올 수 있습니다.

gcloud container aws operations describe OPERATION_ID

OPERATION_ID: 클러스터를 만든 작업의 ID. 클러스터 만들기 요청의 작업 ID가 없으면 다음 명령어를 사용하여 이 ID를 가져올 수 있습니다.

gcloud container aws operations list \
    --location GOOGLE_CLOUD_LOCATION

타임스탬프 또는 관련 정보를 사용하여 원하는 클러스터 만들기 작업을 식별하세요.

예를 들어 권한이 부족한 AWS IAM 역할로 인해 클러스터를 만들지 못한 경우 이 명령어와 결과는 다음 예시와 유사합니다.

gcloud container aws operations describe b6a3d042-8c30-4524-9a99-6ffcdc24b370 \
  --location GOOGLE_CLOUD_LOCATION

출력은 다음과 유사합니다.

done: true
error:
  code: 9
  message: 'could not set deregistration_delay timeout for the target group: AccessDenied
    User: arn:aws:sts::0123456789:assumed-role/foo-1p-dev-oneplatform/multicloud-service-agent
    is not authorized to perform: elasticloadbalancing:ModifyTargetGroupAttributes
    on resource: arn:aws:elasticloadbalancing:us-west-2:0123456789:targetgroup/gke-4nrk57tlyjva-cp-tcp443/74b57728e7a3d5b9
    because no identity-based policy allows the elasticloadbalancing:ModifyTargetGroupAttributes
    action'
metadata:
  '@type': type.googleapis.com/google.cloud.gkemulticloud.v1.OperationMetadata
  createTime: '2021-12-02T17:47:31.516995Z'
  endTime: '2021-12-02T18:03:12.590148Z'
  statusDetail: Cluster is being deployed
  target: projects/123456789/locations/us-west1/awsClusters/aws-prod1
name: projects/123456789/locations/us-west1/operations/b6a3d042-8c30-4524-9a99-6ffcdc24b370

승인 오류로 클러스터 생성 또는 작업 실패

승인 실패를 보여주는 오류는 일반적으로 클러스터 생성 명령어 중에 지정한 두 AWS IAM 역할 중 하나가 잘못 생성되었음을 의미합니다. 예를 들어 API 역할에 elasticloadbalancing:ModifyTargetGroupAttributes 권한이 없으면 다음과 유사한 오류 메시지가 표시되면서 클러스터 생성에 실패합니다.

ERROR: (gcloud.container.aws.clusters.create) could not set
deregistration_delay timeout for the target group: AccessDenied User:
arn:aws:sts::0123456789:assumed-role/cloudshell-user-dev-api-role/multicloud-
service-agent is not authorized to perform:
elasticloadbalancing:ModifyTargetGroupAttributes on resource:
arn:aws:elasticloadbalancing:us-east-1:0123456789:targetgroup/gke-u6au6c65e4iq-
cp-tcp443/be4c0f8d872bb60e because no identity-based policy allows the
elasticloadbalancing:ModifyTargetGroupAttributes action

클러스터가 성공적으로 생성된 것처럼 보이는 경우에도 잘못 지정된 IAM 역할로 인해 나중에 kubectl logs와 같은 명령어를 사용할 때와 같은 클러스터 작업 중에 오류가 발생할 수 있습니다.

이러한 승인 오류를 해결하려면 클러스터를 만드는 중에 지정한 IAM 역할 두 개에 연결된 정책이 올바른지 확인합니다. 특히 AWS IAM 역할 만들기의 설명과 일치하는지 확인한 후 클러스터를 삭제하고 다시 만듭니다. 개별 역할 설명은 API 역할 및 컨트롤 플레인 역할에서 제공됩니다.

상태 확인 단계에서 클러스터 만들기 또는 작업 실패

상태 확인 중에 다음과 유사한 작업 상태로 클러스터 만들기가 실패하는 경우가 있습니다.

done: true
error:
  code: 4
  message: Operation failed
metadata:
  '@type': type.googleapis.com/google.cloud.gkemulticloud.v1.OperationMetadata
  createTime: '2022-06-29T18:26:39.739574Z'
  endTime: '2022-06-29T18:54:45.632136Z'
  errorDetail: Operation failed
  statusDetail: Health-checking cluster
  target: projects/123456789/locations/us-west1/awsClusters/aws-prod1
name: projects/123456789/locations/us-west1/operations/8a7a3b7f-242d-4fff-b518-f361d41c6597

이 오류는 IAM 역할이 없거나 잘못된 IAM 역할이 지정된 것이 원인일 수 있습니다. AWS CloudTrail을 사용하여 IAM 문제인지 확인할 수 있습니다.

예를 들면 다음과 같습니다.

API 역할에 컨트롤 플레인 기본 볼륨 KMS 키에 대한 kms:GenerateDataKeyWithoutPlaintext 권한이 없으면 다음 이벤트가 표시됩니다.

"eventName": "AttachVolume",
"errorCode": "Client.InvalidVolume.NotFound",
"errorMessage": "The volume 'vol-0ff75940ce333aebb' does not exist.",

및

"errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/foo-1p-dev-oneplatform/multicloud-service-agent is not authorized to perform: kms:GenerateDataKeyWithoutPlaintext on resource: arn:aws:kms:us-west1:0123456789:key/57a61a45-d9c1-4038-9021-8eb08ba339ba because no identity-based policy allows the kms:GenerateDataKeyWithoutPlaintext action",

컨트롤 플레인 역할에 컨트롤 플레인 기본 볼륨 KMS 키에 대한 kms:CreateGrant 권한이 없으면 다음 이벤트가 표시됩니다.

"eventName": "AttachVolume",
"errorCode": "Client.CustomerKeyHasBeenRevoked",
"errorMessage": "Volume vol-0d022beb769c8e33b cannot be attached. The encrypted volume was unable to access the KMS key.",

및

"errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/foo-controlplane/i-0a11fae03eb0b08c1 is not authorized to perform: kms:CreateGrant on resource: arn:aws:kms:us-west1:0123456789:key/57a61a45-d9c1-4038-9021-8eb08ba339ba because no identity-based policy allows the kms:CreateGrant action",

컨트롤 플레인 루트 볼륨 KMS 키를 사용할 수 있는 kms:CreateGrant 권한과 함께 AWSServiceRoleForAutoScaling이라는 서비스 연결 역할을 부여하지 않았으면 다음 이벤트가 표시됩니다.

"errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/AWSServiceRoleForAutoScaling/AutoScaling is not authorized to perform: kms:CreateGrant on resource: arn:aws:kms:us-west1:0123456789:key/c77a3a26-bc91-4434-bac0-0aa963cb0c31 because no identity-based policy allows the kms:CreateGrant action",

컨트롤 플레인 루트 볼륨 KMS 키를 사용할 수 있는 kms:GenerateDataKeyWithoutPlaintext 권한과 함께 AWSServiceRoleForAutoScaling이라는 서비스 연결 역할을 부여하지 않았으면 다음 이벤트가 표시됩니다.

"errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/AWSServiceRoleForAutoScaling/AutoScaling is not authorized to perform: kms:GenerateDataKeyWithoutPlaintext on resource: arn:aws:kms:us-west1:0123456789:key/c77a3a26-bc91-4434-bac0-0aa963cb0c31 because no identity-based policy allows the kms:CreateGrant action",

클러스터에 조인할 노드 대기

노드 풀을 만들 때 다음 오류가 발생하면 VPC에 연결된 보조 IPv4 CIDR 블록이 없는지 확인합니다.

errorDetail: Operation failed
statusDetail: Waiting for nodes to join the cluster (0 out of 1 are ready)

이 문제를 해결하려면 모든 CIDR 블록이 포함된 보안 그룹을 만들고 해당 그룹을 클러스터에 추가합니다. 자세한 내용은 VPC 보조 CIDR 블록의 노드 풀을 참조하세요.

인스턴스의 시스템 로그 가져오기

컨트롤 플레인 또는 노드 풀 인스턴스가 시작되지 않으면 시스템 로그를 검사할 수 있습니다. 시스템 로그를 검사하려면 다음을 수행합니다.

AWS EC2 인스턴스 콘솔을 엽니다.
인스턴스를 클릭합니다.
이름으로 인스턴스를 찾습니다. AWS용 GKE는 일반적으로 컨트롤 플레인 노드의 경우 CLUSTER_NAME-cp 또는 노드 풀 노드의 경우 CLUSTER_NAME-np라는 인스턴스를 만듭니다.
작업 -> 모니터링 및 문제해결 -> 시스템 로그 가져오기를 선택합니다. 인스턴스의 시스템 로그가 표시됩니다.

클러스터 업데이트 실패

클러스터를 업데이트할 때, 새 클러스터를 만들 때와 마찬가지로 AWS용 GKE는 먼저 실행 전 테스트 집합을 실행하여 요청을 확인합니다. 클러스터 업데이트에 실패한다면 실행 전 테스트 중 하나가 실패했거나 클러스터 업데이트 프로세스 자체의 단계가 완료되지 않았기 때문일 수 있습니다.

실행 전 테스트가 실패하면 클러스터가 리소스를 업데이트하지 않고 오류에 대한 정보를 사용자에게 직접 반환합니다. 예를 들어 이름이 test_ec2_keypair인 SSH 키 쌍을 사용하도록 클러스터를 업데이트하려고 하면 실행 전 테스트는 EC2 키 쌍을 가져오려고 시도하지만 실패하며 요청은 다음과 같은 오류를 반환합니다.

ERROR: (gcloud.container.aws.clusters.update) INVALID_ARGUMENT: key pair
"test_ec2_keypair" not found,
field: aws_cluster.control_plane.ssh_config.ec2_key_pair

실행 전 테스트를 통과한 후에도 클러스터 업데이트에 실패할 수 있습니다. 클러스터 업데이트는 시작된 후 몇 분 정도 걸릴 수 있으며 Google Cloud 프로젝트의 AWS 리소스 상태는 DEGRADED로 설정됩니다.

실패 및 관련 작업에 대한 세부정보를 가져오려면 클러스터 만들기 실패에 설명된 단계를 따르세요.

컨트롤 플레인 태그를 업데이트할 때 클러스터 업데이트 실패

AWS 업데이트 API는 컨트롤 플레인 태그 업데이트를 지원합니다. 태그를 업데이트하려면 Kubernetes 버전 1.24 이상의 클러스터가 필요합니다. 또한 컨트롤 플레인 업데이트의 경우 AWS IAM 역할에 업데이트 클러스터 페이지에 나열된 적절한 권한이 있는지 확인해야 합니다.

인증 실패를 보여주는 오류는 일반적으로 일부 IAM 권한을 추가하지 않았음을 나타냅니다. 예를 들어 API 역할에 ec2:DeleteTags 권한이 포함되어 있지 않으면 다음과 같은 오류 메시지와 함께 태그 클러스터 업데이트가 실패할 수 있습니다(편의를 위해 <encoded_auth_failure_message>가 수정됨).

ERROR: (gcloud.container.aws.clusters.update) could not delete tags:
UnauthorizedOperation You are not authorized to perform this operation.
Encoded authorization failure message: <encoded_auth_failure_message>

위의 인코딩된 실패 메시지를 디버깅하려면 다음 명령어와 같이 AWS STS decode-authorization-message API에 요청을 보내면 됩니다.

aws sts decode-authorization-message --encoded-message
<encoded_auth_failure_message> --query DecodedMessage --output
text | jq '.' | less

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

...
"principal": {
  "id": "AROAXMEL2SCNPG6RCJ72B:iam-session",
  "arn": "arn:aws:sts::1234567890:assumed-role/iam_role/iam-session"
},
"action": "ec2:DeleteTags",
"resource": "arn:aws:ec2:us-west-2:1234567890:security-group-rule/sgr-00bdbaef24a92df62",
...

위 응답은 AWS 클러스터의 EC2 보안 그룹 규칙 리소스에 ec2:DeleteTags 작업을 수행할 수 없음을 나타냅니다. 이에 따라 API 역할을 업데이트하고 업데이트 API 요청을 다시 보내 컨트롤 플레인 태그를 업데이트합니다.

다음 단계

추가 지원이 필요하면 Cloud Customer Care에 연락합니다.