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를 가져옵니다. MEMBERSHIP_NAME은 클러스터의 Fleet 멤버십 이름으로 바꿉니다. 이 명령어는 게이트웨이를 통해 클러스터에 연결할 수 있는 특수한 Connect 게이트웨이별 kubeconfig를 반환합니다.
# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet 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 fleet 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 명령어는 게이트웨이에서 지원되지 않습니다.
attachcpexecport-forward
문제 해결
게이트웨이를 통해 클러스터에 연결하는 데 문제가 있는 경우, 사용자 또는 관리자가 다음과 같은 일반적인 문제를 확인할 수 있습니다.
- 서버에 리소스 유형이 없음:
kubectl get ns명령어가 실패하면 이 오류 메시지가 표시될 수 있습니다. 이 오류가 발생할 수 있는 이유는 여러 가지입니다.kubectl get ns -v 10과 같이 세부정보 수준 모드에서kubectl명령어를 실행하여 자세한 정보를 확인합니다. - 클러스터(프로젝트: 12345, 멤버십: my-cluster)의 활성 연결을 찾을 수 없음: Connect Agent에서 연결을 손실했거나 제대로 설치되지 않은 경우에 이 오류가 표시될 수 있습니다. 이 문제를 해결하려면 클러스터에
gke-connect네임스페이스가 있는지 확인해야 합니다. 그렇지 않으면 Google Cloud CLI를 사용하여 클러스터 등록을 참조하세요. 클러스터에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 게이트웨이를 사용하는 방법의 예시를 참조하세요.