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를 사용합니다.
사용자가 서비스 계정을 가장하도록 허용하는 방법은 서비스 계정에 대한 액세스 관리를 참조하세요.
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 exec/cp/attach/port-forward 명령어
다음 kubectl 명령어는 스트리밍 명령어이며 추가 요구사항이 있습니다.
attachcpexecport-forward
다음 요구사항을 참고하세요.
attach,cp,exec명령어의 경우 클러스터 버전이 1.30 이상이어야 하며,port-forward명령어의 경우 1.31 이상이어야 합니다.kubectl클라이언트 버전이 1.31 이상이어야 합니다.클라이언트 버전을 확인하려면
kubectl version명령어의 출력을 확인하세요. 최신 버전의kubectl을 설치하려면 도구 설치를 참고하세요.
roles/gkehub.gatewayAdmin IAM 역할 및 cluster-admin ClusterRole이 있는 사용자와 서비스 계정에는 attach, cp, exec, port-forward 명령어를 실행하는 데 필요한 권한이 있습니다. 사용자 및 서비스 계정에 커스텀 IAM 역할 또는 커스텀 RBAC 역할이 부여된 경우 추가 권한을 부여해야 할 수 있습니다. 자세한 내용은 다음 섹션을 참조하세요.
필요한 경우 추가 권한 부여
Connect 게이트웨이를 통해 attach, cp, exec, port-forward 명령어를 실행하려면 gkehub.gateway.stream IAM 권한이 필요합니다. 이 권한은 roles/gkehub.gatewayAdmin에 포함되어 있습니다.
프로젝트 소유자가 아닌 사용자 또는 프로젝트에서 roles/gkehub.gatewayAdmin 권한이 부여되지 않은 사용자 또는 서비스 계정의 경우 roles/gkehub.gatewayAdmin 권한을 부여하거나 기타 필수 역할 및 gkehub.gateway.stream 권한이 포함된 맞춤 역할을 만들어야 합니다. 맞춤 역할을 만드는 방법에 대한 자세한 내용은 IAM 문서의 맞춤 역할 만들기 및 관리를 참고하세요.
필요한 경우 RBAC 정책을 추가로 만들어 적용
cluster-admin ClusterRole이 있는 사용자와 서비스 계정에는 attach, cp, exec, port-forward 명령어를 실행하는 데 필요한 권한이 있습니다.
명령어를 실행하려면 최소한 다음 규칙이 필요합니다.
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: stream-role
namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
resources: ["pods/exec", "pods/attach", "pods/portforward"]
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 get ns명령어가 실패하면 이 오류 메시지가 표시될 수 있습니다. 이 오류가 발생할 수 있는 이유는 여러 가지입니다.kubectl get ns -v 10과 같이 세부정보 수준 모드에서kubectl명령어를 실행하여 자세한 정보를 확인합니다. - 클러스터(프로젝트: 12345, 멤버십: my-cluster)의 활성 연결을 찾을 수 없음: Connect Agent에서 연결을 손실했거나 제대로 설치되지 않은 경우에 이 오류가 표시될 수 있습니다( 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플래그를 사용하여 멤버십 등록 명령어를 다시 실행합니다.gke-security-groups그룹 아래에서 반환된 그룹의 크기가 8KB HTTP 헤더 크기 제한을 초과합니다. 그룹 계층 구조를 재구성하고 다시 시도: 그룹 수에는 엄격한 제한이 없지만 그룹 이름이 길면 요청이 8KB HTTP 헤더 크기 제한을 초과하여 그룹 계층 구조를 재구성해야 할 수 있는 오류가 발생할 수 있습니다.
kubectl exec/cp/attach/port-forward 문제 해결
명령어 실행에서 반환된 오류는 문제를 디버그하기에 충분할 정도로 명확하지 않은 일반적인 400 Bad Request 오류인 경우가 많습니다. 더 자세한 오류 메시지를 반환하려면 kubectl 클라이언트 버전 1.32 이상을 사용하여 수준 4 이상의 상세 수준으로 명령어를 실행합니다(예: kubectl exec -v 4 ...).
반환된 로그에서 다음 응답이 포함된 로그를 찾습니다.
-
kubectl exec/cp/attach명령어에 대해:RemoteCommand fallback: -
kubectl port-forward명령어에 대해:fallback to secondary dialer from primary dialer err:
kubectl exec -v 4 ... 명령어에서 발생할 수 있는 일반적인 오류 메시지를 해결하려면 다음 섹션을 참고하세요.
누락된 IAM 권한
오류 메시지에 generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource가 포함된 경우 명령어를 실행하는 데 필요한 IAM 권한이 부여되지 않은 것일 수 있습니다. 이 기능을 사용하려면 사용자에게 gkehub.gateway.stream IAM 권한이 있어야 하며, 이 권한은 roles/gkehub.gatewayAdmin 역할에 기본적으로 포함되어 있습니다. 자세한 내용은 IAM 권한 섹션을 참조하세요.
필수 RBAC 권한 누락
오류 메시지에 ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden...가 포함된 경우 RBAC 권한이 없음을 나타냅니다. 이러한 kubectl 명령어를 실행하려면 클러스터에 RBAC 권한 집합이 필요합니다.
필요한 RBAC 권한을 설정하는 방법에 관한 자세한 내용은 필요한 경우 RBAC 정책을 추가로 만들어 적용을 참고하세요.
오류 메시지 generic::resource_exhausted: 게이트웨이의 active_streams 할당량이 소진됨
Fleet 호스트 프로젝트당 활성 스트림은 10개로 할당량이 제한됩니다. 이는 connectgateway.googleapis.com/active_streams 할당량에 정의되어 있습니다. 할당량 관리에 관한 안내는 할당량 보기 및 관리를 참조하세요.
오류 메시지 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...입니다.
오류 메시지 generic::failed_precondition: 에이전트 연결 실패/종료됨
명령어 실행 즉시 이 오류가 발생하면 클러스터의 Google 연결에 문제가 있는 것입니다. 자세한 내용은 일반 문제 해결 가이드를 참조하세요.
세션이 활성화된 후 약 20~30분 후에 이 오류가 발생한다면 이는 예상된 제한사항으로, 보안상의 이유 때문입니다. 연결을 다시 설정해야 합니다.
다음 단계
- Cloud Build와 통합 튜토리얼에서 DevOps 자동화의 일부로 Connect 게이트웨이를 사용하는 방법의 예시를 참조하세요.