Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Connect 게이트웨이 사용

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

시작하기 전에

다음 명령줄 도구가 설치되었는지 확인합니다.
- Google Cloud와 상호작용하는 명령줄 도구인 Google Cloud CLI 최신 버전
- kubectl
Google Cloud와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 이러한 도구가 자동으로 설치됩니다.
프로젝트에 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.

필요한 역할

Connect 게이트웨이를 사용하여 클러스터에 연결하고 명령어를 실행하는 데 필요한 권한을 얻으려면 관리자에게 클러스터 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

클러스터의 kubeconfig 파일 가져오기: Connect 게이트웨이 리더 (roles/gkehub.gatewayReader)
kubectl CLI 명령어 실행: Connect 게이트웨이 관리자 (roles/gkehub.gatewayAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

Connect 게이트웨이 관리자 (roles/gkehub.gatewayAdmin) 역할은 attach, exec, port-forward, cp와 같은 kubectl CLI 명령어를 실행하는 데 필요한 gkehub.gateway.stream 권한이 포함된 유일한 사전 정의된 역할입니다.

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

계정에 로그인 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 명령어는 스트리밍 명령어이며 추가 요구사항이 있습니다.

attach
cp
exec
port-forward

이러한 명령어를 실행하려면 다음 요구사항을 충족해야 합니다.

클러스터는 attach, cp, exec 명령어의 경우 버전 1.30 이상이어야 하고 port-forward 명령어의 경우 버전 1.31 이상이어야 합니다.
kubectl 클라이언트 버전이 1.31 이상이어야 합니다. 클라이언트 버전을 확인하려면 kubectl version 명령어의 출력을 확인하세요. 최신 버전의 kubectl을(를) 설치하려면 도구 설치를 참고하세요.
사용자와 서비스 계정은 IAM 또는 RBAC를 통해 Kubernetes API에 대한 다음과 같은 추가 액세스 권한이 있어야 합니다.
- IAM: gkehub.gateway.stream 권한이 포함된 역할을 부여합니다. roles/gkehub.gatewayAdmin 사전 정의된 역할에 이 권한이 포함되어 있습니다. 이 권한을 맞춤 역할에 할당할 수도 있습니다.
- RBAC: 다음 예시 Role 및 RoleBinding과 같이 pods/exec, pods/portforward, pods/attach API 하위 리소스에 대한 get 액세스 권한이 포함된 Role 또는 ClusterRole을 부여합니다.
```
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: Group
  name: EMAIL # Specify the group that should have stream access
```
  다음을 바꿉니다.
  - NAMESPACE: Role 및 RoleBinding의 네임스페이스입니다.
  - EMAIL: 클러스터가 그룹으로 RBAC를 지원하는 경우 스트림 액세스 권한이 있어야 하는 그룹의 이메일 주소입니다.
  cluster-admin 기본 ClusterRole에도 이러한 권한이 포함되어 있습니다.

문제 해결

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

서버에 리소스 유형이 없음: 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 ID 서비스 로그 수집을 참조하세요.
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분 후에 이 오류가 발생한다면 이는 예상된 제한사항으로, 보안상의 이유 때문입니다. 연결을 다시 설정해야 합니다.

`kubectl --raw` 문제 해결

단축된 엔드포인트 (예: kubectl get --raw /version)를 사용하면 Error from server (NotFound): the server could not find the requested resource 오류가 발생할 수 있습니다. 전체 서버 주소를 제공해야 합니다.

kubeconfig에서 엔드포인트를 가져옵니다.

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

그런 다음 명령어의 엔드포인트를 사용합니다(예: /version).

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

다음 단계

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