Connect 게이트웨이 사용

이 페이지에서는 Connect 게이트웨이를 사용하여 등록된 클러스터에 연결하는 방법을 설명합니다. 이 가이드를 읽기 전 개요에 설명된 개념을 숙지해야 합니다. 이 가이드에서는 프로젝트 관리자가 게이트웨이를 이미 설정했고 사용자에게 필요한 역할 및 권한을 부여했다고 가정합니다.

시작하기 전에

• 다음 명령줄 도구가 설치되었는지 확인합니다.

  • Google Cloud와 상호작용하는 명령줄 도구인 Google Cloud CLI 최신 버전
  • kubectl

  Google Cloud와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 이러한 도구가 자동으로 설치됩니다.

• 프로젝트에 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.

Google Cloud 계정에 로그인

고유한 Google Cloud 계정 또는 Google Cloud 서비스 계정을 사용하여 게이트웨이 API를 통해 연결된 클러스터와 상호작용할 수 있습니다.

Google Cloud CLI 도구 승인의 안내를 따라 사용자 계정에 로그인합니다. Connect 게이트웨이는 서비스 계정 가장을 지원합니다. 따라서 다음 섹션에 표시된 것처럼 자신의 고유 사용자 계정에 로그인되어 있더라도 특정 서비스 계정을 사용하여 클러스터와 상호작용할 수 있습니다.

등록된 클러스터 선택

액세스하려는 클러스터 이름을 모르는 경우 다음 명령어를 실행하여 현재 Fleet에 등록된 클러스터를 모두 확인할 수 있습니다.

gcloud container fleet memberships list

여기에는 멤버십 이름과 외부 ID를 포함하여 Fleet의 모든 클러스터가 나열됩니다. Fleet의 각 클러스터에는 고유한 멤버십 이름이 있습니다. GKE 클러스터의 경우 멤버십 이름은 클러스터 이름을 등록 시에 프로젝트 내에서 고유하게 지정하지 않는 한 일반적으로 클러스터를 만들 때 지정한 이름과 일치합니다.

클러스터의 게이트웨이 kubeconfig 가져오기

다음 명령어를 사용하여 지정된 클러스터와 상호작용하는 데 필요한 kubeconfig를 가져옵니다.

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

MEMBERSHIP_NAME을 클러스터의 Fleet 멤버십 이름으로 바꿉니다.

이 명령어는 게이트웨이를 통해 클러스터에 연결할 수 있는 특수한 Connect 게이트웨이별 kubeconfig를 반환합니다.

사용자 고유 Google Cloud 계정 대신 서비스 계정을 사용하려는 경우 gcloud config를 사용하여 auth/impersonate_service_account를 서비스 계정 이메일 주소로 설정합니다.

서비스 계정을 사용하여 Connect 게이트웨이와 상호작용하는 데 사용되는 클러스터 사용자 인증 정보를 가져오려면 다음 명령어를 실행합니다. 다음 사항에 유의하세요.

• 베어 메탈 및 VMware용 Google Distributed Cloud(소프트웨어 전용) 클러스터: 멤버십 이름은 클러스터 이름과 동일합니다.

• AWS용 GKE: gcloud container aws clusters get-credentials를 사용합니다.

• Azure용 GKE: gcloud container azure clusters get-credentials를 사용합니다.

사용자 고유 Google Cloud 계정 대신 서비스 계정을 사용하려는 경우 gcloud config를 사용하여 auth/impersonate_service_account를 서비스 계정 이메일 주소로 설정합니다. 사용자가 서비스 계정을 가장하도록 허용하는 방법은 서비스 계정에 대한 액세스 관리를 참조하세요.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

SA_EMAIL_ADDRESS를 서비스 계정의 이메일 주소로 바꿉니다. 사용자가 서비스 계정을 가장하도록 허용하는 방법은 서비스 계정에 대한 액세스 관리를 참조하세요.

클러스터에 대해 명령어 실행

필요한 사용자 인증 정보가 있으면 일반적인 Kubernetes 클러스터에서와 마찬가지로 kubectl 또는 go-client를 사용하여 명령어를 실행할 수 있습니다. 출력이 다음과 같이 표시됩니다.

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

제한사항

다음 kubectl 명령어는 gcloud container fleet memberships get-credentials 명령어를 사용하는 게이트웨이에서 지원되지 않습니다.

• attach
• cp
• exec
• port-forward

명령어 미리보기 지원

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

attach, cp, exec 명령어(port-forward 제외)는 베타 명령어 gcloud beta container fleet memberships get-credentials에서 지원됩니다. 이 명령어를 사용하면 Connect 게이트웨이의 미리보기 기능을 사용할 수 있습니다.

다음 요구사항을 참고하세요.

• 미리보기에서는 Google Cloud 기반 GKE가 지원되지 않습니다.

• 클러스터 버전이 1.30 이상이어야 합니다.

• kubectl 클라이언트 버전이 1.29 이상이어야 합니다. 버전 1.29를 사용하는 경우 다음 환경 변수를 설정해야 합니다.

  export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
  

  kubectl 버전 1.30 이상에는 환경 변수가 필요하지 않습니다.

  클라이언트 버전을 확인하려면 kubectl version 명령어의 출력을 확인하세요. 최신 버전의 kubectl을 설치하려면 도구 설치를 참고하세요.

roles/gkehub.gatewayAdmin IAM 역할 및 cluster-admin ClusterRole이 있는 사용자와 서비스 계정에는 attach, cp, exec 명령어를 실행하는 데 필요한 권한이 있습니다. 사용자 및 서비스 계정에 맞춤 IAM 역할 또는 맞춤 RBAC 역할이 부여된 경우 추가 권한을 부여해야 할 수 있습니다. 자세한 내용은 다음 섹션을 참조하세요.

필요한 경우 추가 권한 부여

Connect 게이트웨이를 통해 attach, cp, exec 명령어를 실행하려면 gkehub.gateway.stream IAM 권한이 필요합니다. 이 권한은 roles/gkehub.gatewayAdmin에 포함되어 있습니다.

프로젝트 소유자가 아닌 사용자 또는 프로젝트에서 roles/gkehub.gatewayAdmin 권한이 부여되지 않은 사용자 또는 서비스 계정의 경우 roles/gkehub.gatewayAdmin 권한을 부여하거나 기타 필수 역할 및 gkehub.gateway.stream 권한이 포함된 맞춤 역할을 만들어야 합니다. 맞춤 역할을 만드는 방법에 대한 자세한 내용은 IAM 문서의 맞춤 역할 만들기 및 관리를 참고하세요.

필요한 경우 RBAC 정책을 추가로 만들어 적용

cluster-admin ClusterRole이 있는 사용자와 서비스 계정에는 attach, cp, exec 명령어를 실행하는 데 필요한 권한이 있습니다.

명령어를 실행하려면 최소한 다음 규칙이 필요합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

kubectl exec/cp/attach 문제 해결

명령어 실행에서 반환된 오류는 문제를 디버그하기에 충분히 명확하지 않은 경우가 많습니다. 이 경우 더 높은 상세 로깅 수준(예: kubectl exec -v 5 ...)으로 명령어를 다시 실행합니다.

Connect 게이트웨이 베타 트랙이 사용되지 않음

400 Bad Request 오류가 발생하면 gcloud CLI 베타 트랙을 사용하여 연결 게이트웨이 kubeconfig 파일을 다시 생성해 오류가 수정되는지 확인합니다.

gcloud beta container fleet memberships get-credentials my-membership`

그래도 400 Bad Request 오류가 발생하면 다음 섹션의 단계를 따르세요.

kubectl 환경 플래그가 설정되지 않음

사용 중인 kubectl 클라이언트 버전이 1.29인 경우 환경 변수 KUBECTL_REMOTE_COMMAND_WEBSOCKETS를 사용 설정해야 합니다. 이 기능이 사용 설정되지 않으면 400 Bad Request 오류가 발생합니다. 환경 변수가 사용 설정되어 있는지 확인하려면 다음 명령어를 실행합니다.

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

변수가 설정되어 있지 않으면 다음 환경 변수를 설정하여 사용 설정합니다.

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

kubectl 버전 1.30 이상에서는 기본적으로 사용 설정되어 있으므로 이 플래그가 필요하지 않습니다.

1.29 이하 kubectl 버전에서는 이 기능이 작동하지 않습니다.

누락된 IAM 권한

error: error reading from error stream... 메시지가 표시되면 명령어를 실행하는 데 필요한 IAM 권한이 부여되지 않은 것일 수 있습니다. 이 기능을 사용하려면 사용자에게 gkehub.gateway.stream IAM 권한이 있어야 하며, 이 권한은 roles/gkehub.gatewayAdmin 역할에 기본적으로 포함되어 있습니다. 자세한 내용은 IAM 권한 섹션을 참고하세요.

오류 메시지 generic::failed_precondition: 클러스터 내에서 오류 발생

generic::failed_precondition: error encountered within the cluster 오류가 발생하면 클러스터의 Connect 에이전트 로그를 확인하여 근본 원인을 파악합니다.

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Connect 에이전트에서 확인해야 하는 로그는 failed to create the websocket connection...입니다.

필수 RBAC 권한 누락

Connect 에이전트 로그의 오류 메시지에 403 Forbidden이 포함된 경우 RBAC 권한이 없음을 나타냅니다. 클러스터에 이러한 kubectl 명령어를 실행하기 위한 RBAC 권한 집합이 있습니다. 필요한 RBAC 권한을 설정하려면 RBAC 정책 섹션을 참고하세요.

오류 메시지 generic::resource_exhausted: 게이트웨이의 active_streams 할당량이 소진됨

Fleet 호스트 프로젝트당 활성 스트림은 10개로 할당량이 제한됩니다. 이는 connectgateway.googleapis.com/active_streams 할당량에 정의되어 있습니다. 할당량 관리에 관한 안내는 할당량 보기 및 관리를 참고하세요.

오류 메시지 generic::failed_precondition: 에이전트 연결 실패/종료됨

명령어 실행 즉시 이 오류가 발생하면 클러스터의 Google 연결에 문제가 있는 것입니다. 자세한 내용은 일반 문제 해결 가이드를 참고하세요.

세션이 활성화된 후 약 5~10분 후에 이 오류가 발생하면 이는 예상된 기능 제한입니다. 연결을 다시 설정해야 합니다.

문제 해결

게이트웨이를 통해 클러스터에 연결하는 데 문제가 있는 경우, 사용자 또는 관리자가 다음과 같은 일반적인 문제를 확인할 수 있습니다.

• 서버에 리소스 유형이 없음: kubectl get ns 명령어가 실패하면 이 오류 메시지가 표시될 수 있습니다. 이 오류가 발생할 수 있는 이유는 여러 가지입니다. kubectl get ns -v 10과 같이 세부정보 수준 모드에서 kubectl 명령어를 실행하여 자세한 정보를 확인합니다.
• 클러스터(프로젝트: 12345, 멤버십: my-cluster)의 활성 연결을 찾을 수 없음: Connect 에이전트에서 연결을 손실했거나 제대로 설치되지 않은 경우에 이 오류가 표시될 수 있습니다(Google Cloud 외부의 클러스터만 해당). 이 문제를 해결하려면 클러스터에 gke-connect 네임스페이스가 있는지 확인해야 합니다. 클러스터에 gke-connect 네임스페이스가 있으면 Connect 문제 해결 페이지를 참조하여 연결 문제를 해결합니다.
• 이 서버에서 요청된 URL을 찾을 수 없음: 이 오류는 kubeconfig에 잘못된 서버 주소가 포함되었을 때 표시될 수 있습니다. 사용 중인 Google Cloud CLI 버전이 최신 버전인지 확인하고 kubeconfig 게이트웨이를 다시 생성합니다. 예상치 않은 오류가 발생하지 않도록 kubeconfig 파일을 직접 수정하지 마세요.
• 사용자 ID에 게이트웨이 API를 사용하는데 충분한 권한이 없음: API를 사용하려면 roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader 또는 roles/gkehub.gatewayEditor 역할이 필요합니다. 자세한 내용은 게이트웨이 설정 가이드의 사용자에게 IAM 역할 부여를 참조하세요.
• Connect 에이전트가 사용자 요청을 전송하도록 승인되지 않음: Connect 에이전트가 사용자 대신 요청을 전송하도록 허용해야 합니다. 이 설정은 클러스터에서 가장 정책을 사용하여 지정됩니다. gateway-impersonate 역할에 사용자 추가 예시는 게이트웨이 설정 가이드에서 RBAC 승인 구성을 참조하세요.
• 사용자 ID에 작업을 수행하는 데 충분한 RBAC 권한이 없음: 선택한 작업을 수행하려면 클러스터에 대해 적합한 권한이 있어야 합니다. 적합한 ClusterRole에 사용자를 추가하는 예시는 게이트웨이 설정 가이드의 RBAC 승인 구성을 참조하세요.
• 사용자 ID에 Google 그룹스 또는 서드 파티 지원을 사용할 때 작업을 수행할 수 있는 충분한 권한이 없음: ID 정보와 관련된 로그를 검사하는 방법에 대한 안내는 GKE Identity Service 로그 수집을 참조하세요.
• Connect 에이전트가 비정상임: Connect 문제 해결 페이지를 참조하여 클러스터가 연결되었는지 확인하세요.
• executable gke-gcloud-auth-plugin not found 또는 no Auth Provider found for gcp: kubectl 버전 1.26 이상에서 GKE v1.26으로 시작하는 kubectl 인증에 대한 변경으로 인해 이 오류가 표시될 수 있습니다. Google Cloud CLI의 최신 버전으로 gke-gcloud-auth-plugin을 설치하고 gcloud container fleet memberships get-credentials MEMBERSHIP_NAME을 다시 실행합니다.
• 이전 버전의 Google Cloud CLI로 인해 게이트웨이 연결 실패: GKE 클러스터의 경우 게이트웨이가 작동하는 데 Connect 에이전트가 더 이상 필요하지 않으므로 멤버십 등록 중에 기본적으로 Connect가 설치되지 않습니다. 이전 버전의 Google Cloud CLI(399.0.0 이하)는 클러스터에 Connect 에이전트가 있다고 가정합니다. 이러한 이전 버전으로 게이트웨이를 사용하려고 하면 최신 버전의 Google Cloud CLI에 등록된 클러스터에서 실패할 수 있습니다. 이 문제를 해결하려면 Google Cloud CLI 클라이언트를 새 버전으로 업그레이드하거나 --install-connect-agent 플래그를 사용하여 멤버십 등록 명령어를 다시 실행합니다.

다음 단계

• Cloud Build와 통합 튜토리얼에서 DevOps 자동화의 일부로 Connect 게이트웨이를 사용하는 방법의 예시를 참조하세요.