Connect 게이트웨이 사용

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

시작하기 전에

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

    • Google Cloud와의 상호작용을 위한 명령줄 도구인 gcloud가 포함된 Cloud SDK의 최신 버전
    • kubectl

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

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

Google Cloud 계정에 로그인

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

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

등록된 클러스터 선택

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

gcloud container hub memberships list

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

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

다음 명령어를 사용하여 지정된 클러스터와 상호작용하는 데 필요한 kubeconfig를 가져옵니다. MEMBERSHIP_NAME은 클러스터의 Fleet 멤버십 이름으로 바꿉니다. 이 명령어는 게이트웨이를 통해 클러스터에 연결할 수 있는 특수한 Connect 게이트웨이별 kubeconfig를 반환합니다.

# Fetch cluster credential used to interact with Connect gateway
gcloud container hub memberships get-credentials MEMBERSHIP_NAME

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

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container hub memberships get-credentials MEMBERSHIP_NAME

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

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

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

다음 kubectl 명령어는 게이트웨이에서 지원되지 않습니다.

  • exec
  • proxy

문제해결

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

  • 클러스터의 활성 연결을 찾을 수 없음(프로젝트: 12345, 멤버십: my-cluster): Connect 에이전트의 연결이 끊어지거나 에이전트가 설치되지 않은 경우 이 오류가 표시될 수 있습니다. 이는 Cloud Console에 등록되었거나 Terraform/Config 커넥터를 사용하는 GKE 클러스터에서 발생할 수 있습니다. 이 문제를 해결하려면 클러스터에 gke-connect 네임스페이스가 있는지 확인해야 합니다. 이 네임스페이스가 없다면 gcloud 명령줄 도구로 클러스터 등록을 참조하세요. 클러스터에 gke-connect 네임스페이스가 있는 경우에는 연결 문제 해결 페이지를 참조하여 연결 문제를 해결하세요.
  • 서버에 '네임스페이스' 리소스 유형이 없음: 이 오류 메시지는 kubectl get ns와 같은 간단한 명령어가 실패할 때 표시될 수 있습니다. 이 오류가 발생할 수 있는 이유는 여러 가지입니다. kubectl get ns -v 10과 같이 상세 모드에서 kubectl 명령어를 실행하여 자세한 정보를 확인합니다.
  • 이 서버에서 요청된 URL을 찾을 수 없음: 이 오류는 kubeconfig에 잘못된 서버 주소가 포함되었을 때 표시될 수 있습니다. 사용 중인 Cloud SDK 버전이 최신 버전인지 확인하고 kubeconfig 게이트웨이 생성을 다시 시도합니다. 예상치 않은 오류가 발생하지 않도록 kubeconfig 파일을 직접 수정하지 마세요.
  • 사용자 ID에 게이트웨이 API를 사용하는데 충분한 권한이 없음: API를 사용하려면 roles/gkehub.gatewayAdmin 또는 roles/gkehub.gatewayReader 역할이 필요합니다. 자세한 내용은 게이트웨이 설정 가이드의 IAM 권한 부여를 참조하세요.
  • Connect 에이전트가 사용자 요청을 전송하도록 승인되지 않음: Connect 에이전트가 사용자 대신 요청을 전송하도록 허용해야 합니다. 이 설정은 클러스터에서 가장 정책을 사용하여 지정됩니다. gateway-impersonate 역할에 사용자 추가 예시는 게이트웨이 설정 가이드에서 RBAC 정책 구성을 참조하세요.
  • 사용자 ID에 작업을 수행하는 데 충분한 RBAC 권한이 없음: 선택한 작업을 수행하려면 클러스터에 대해 적합한 권한이 있어야 합니다. 적합한 ClusterRole에 사용자를 추가하는 예시는 게이트웨이 설정 가이드의 RBAC 정책 구성을 참조하세요.
  • Connect 에이전트가 비정상입니다. Connect 문제 해결 페이지를 참조하여 클러스터가 연결되었는지 확인하세요.

다음 단계

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