Version 1.16. This version is no longer supported. For information about how to upgrade to version 1.28, see Upgrade clusters in the latest documentation. For more information about supported and unsupported versions, see the Versioning page in the latest documentation.

GKE On-Prem API에서 관리할 클러스터 구성

GKE On-Prem API는 표준 도구(Google Cloud 콘솔, Google Cloud CLI 또는 Terraform)를 사용하여 온프레미스 클러스터의 수명 주기를 관리할 수 있게 해주는 Google Cloud 호스팅 API입니다. 이러한 도구 중 하나를 사용하여 클러스터를 만드는 경우 API는 클러스터를 만들 때 지정한 Google Cloud 리전에 클러스터 상태에 대한 메타데이터를 저장합니다. 이 메타데이터를 사용하면 표준 도구를 사용하여 클러스터의 수명 주기를 관리할 수 있습니다. 이러한 도구를 사용하여 클러스터 세부정보를 보거나 bmctl로 생성된 클러스터의 수명 주기를 관리하려면 GKE On-Prem API에 클러스터를 등록해야 합니다.

용어

클러스터를 등록하면 콘솔, gcloud CLI 또는 Terraform을 사용하여 클러스터 수명 주기를 관리할 수 있습니다.

클러스터 등록은 클러스터를 Fleet에 등록하는 별도의 프로세스입니다. Fleet은 함께 관리할 수 있는 Kubernetes 클러스터의 논리적 그룹입니다. 모든 베어메탈용 GKE 클러스터는 클러스터 생성 시 Fleet에 등록됩니다. bmctl을 사용하여 클러스터를 만들면 클러스터가 클러스터 구성 파일의 gkeConnect.projectID 필드에 지정한 Google Cloud 프로젝트에 등록됩니다. 이 프로젝트를 Fleet 호스트 프로젝트라고 합니다. 사용 사례, 권장사항, 예시 등 Fleet에 대한 자세한 내용은 Fleet 관리 문서를 참조하세요.

등록된 클러스터 보기

모든 Fleet 클러스터는 콘솔의 GKE Enterprise 클러스터 및 GKE 클러스터 페이지에 표시됩니다. 두 가지 모두 전체 Fleet에 대한 개요를 제공하며, 베어메탈용 GKE의 경우 GKE On-Prem API에서 관리되는 클러스터를 확인할 수 있습니다.

Fleet 클러스터를 보려면 다음을 수행하세요.

콘솔에서 GKE Enterprise 클러스터 페이지로 이동합니다.
GKE Enterprise 클러스터 페이지로 이동
Google Cloud 프로젝트를 선택합니다.
- 베어메탈이 유형 열에 표시되면 클러스터가 GKE On-Prem API에서 관리됩니다.
- 유형 열에 외부가 표시되는 경우 클러스터는 GKE On-Prem API에서 관리되지 않습니다.

요구사항

사용자 및 관리자 클러스터만 GKE On-Prem API에 등록할 수 있습니다. 하이브리드 및 독립형 클러스터 등록은 지원되지 않습니다.
버전 1.13 이상이 필요합니다.
프로젝트 소유자가 아닌 경우 프로젝트에 대한 Identity and Access Management(IAM) 역할 roles/gkeonprem.admin을 부여받아야 합니다. 이 역할에 포함된 권한에 대한 자세한 내용은 IAM 문서의 GKE On-Prem 역할을 참조하세요.

시작하기 전에

필요한 경우 gcloud CLI를 설정합니다.
1. gcloud CLI를 설치해야 하는 경우 gcloud CLI 문서를 참조하세요. 필요한 경우 gcloud CLI 구성요소를 업데이트합니다.
```
gcloud components update
```
GKE On-Prem API를 활성화하고 사용하려면 다음 단계를 따르세요.
1. 프로젝트에서 API를 사용 설정합니다.
```
gcloud services enable \
    --project PROJECT_ID \
    gkeonprem.googleapis.com
```
  PROJECT_ID를 Fleet 호스트 프로젝트의 프로젝트 ID로 바꿉니다. 이 프로젝트 ID는 클러스터 구성 파일의 gkeconnect 섹션에서 구성한 프로젝트 ID입니다.
  
  PERMISSION_DENIED 오류가 발생하면 입력한 프로젝트 ID를 다시 확인합니다. 프로젝트 ID가 올바르면 gcloud auth login을 실행하여 프로젝트에 액세스 권한이 있는 계정으로 Google Cloud CLI에 로그인합니다.
2. 프로젝트에서 GKE On-Prem API를 처음 사용 설정한 경우 API를 초기화해야 할 수 있습니다. gcloud CLI 명령어를 호출하여 클러스터를 만드는 데 사용할 수 있는 버전을 표시하면 됩니다.
```
gcloud container bare-metal clusters query-version-config \
    --project=PROJECT_ID \
    --location=REGION
```
  REGION을 us-west1 또는 다른 지원되는 리전으로 바꿉니다.
조직에서 Google API 및 기타 주소의 트래픽이 프록시 서버를 통과하도록 허용하는 허용 목록이 설정된 경우 허용 목록에 다음을 추가합니다.
- gkeonprem.googleapis.com
- gkeonprem.mtls.googleapis.com
이는 GKE On-Prem API에 대한 서비스 이름입니다.

사용자 클러스터 등록

gcloud CLI

필요에 따라 화면을 스크롤해서 --admin-cluster-membership 플래그의 ADMIN_CLUSTER_NAME 자리표시자를 채워야 합니다.

gcloud container bare-metal clusters enroll USER_CLUSTER_NAME  \
    --project=PROJECT_ID \
    --admin-cluster-membership=projects/PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
    --location=REGION

다음을 바꿉니다.

USER_CLUSTER_NAME: 등록하려는 사용자 클러스터의 이름입니다.
PROJECT_ID: Fleet 호스트 프로젝트의 프로젝트 ID입니다.
ADMIN_CLUSTER_NAME: 사용자 클러스터를 관리하는 관리자 클러스터입니다. 관리자 클러스터 이름은 Google Cloud에서 클러스터를 고유하게 식별하는 완전히 지정된 클러스터 이름의 마지막 세그먼트입니다.
REGION: GKE On-Prem API가 클러스터 메타데이터를 실행하고 저장하는 Google Cloud 리전입니다. us-west1 또는 다른 지원되는 리전을 지정합니다. 클러스터를 등록한 후에는 리전을 변경할 수 없습니다.

`bmctl`

관리자 워크스테이션에서 다음 단계를 수행합니다.

사용자 클러스터 구성 파일에 다음 섹션을 추가합니다.
```
gkeOnPremAPI:
  enabled: true
  location: REGION
```
REGION을 GKE On-Prem API가 실행되고 클러스터 메타데이터를 저장하는 Google Cloud 리전으로 바꿉니다. us-west1 또는 다른 지원되는 리전을 지정합니다. 클러스터를 등록한 후에는 리전을 변경할 수 없습니다.
클러스터를 업데이트합니다.
```
bmctl update cluster -c USER_CLUSTER_NAME \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
다음을 바꿉니다.
- USER_CLUSTER_NAME: 업데이트할 사용자 클러스터의 이름입니다.
- ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.

관리자 클러스터 등록

gcloud CLI

필요에 따라 화면을 스크롤해서 --admin-cluster-membership 플래그의 ADMIN_CLUSTER_NAME 자리표시자를 채워야 합니다.

gcloud container bare-metal admin-clusters enroll ADMIN_CLUSTER_NAME \
    --project=PROJECT_ID \
    --admin-cluster-membership=projects/PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
    --location=REGION

다음을 바꿉니다.

ADMIN_CLUSTER_NAME: 등록하려는 관리자 클러스터의 이름입니다.
PROJECT_ID: Fleet 호스트 프로젝트의 프로젝트 ID입니다.

ADMIN_CLUSTER_NAME 및 PROJECT_ID는 --admin-cluster-membership 플래그에 대해 완전히 지정된 클러스터 이름을 형성하는 데 사용됩니다.
REGION: GKE On-Prem API가 클러스터 메타데이터를 실행하고 저장하는 Google Cloud 리전입니다. us-west1 또는 다른 지원되는 리전을 지정합니다. 클러스터를 등록한 후에는 리전을 변경할 수 없습니다.

`bmctl`

관리자 워크스테이션에서 다음 단계를 수행합니다.

관리자 클러스터 구성 파일에 다음 섹션을 추가합니다.
```
gkeOnPremAPI:
  enabled: true
  location: REGION
```
REGION을 GKE On-Prem API가 실행되고 클러스터 메타데이터를 저장하는 Google Cloud 리전으로 바꿉니다. us-west1 또는 다른 지원되는 리전을 지정합니다. 클러스터를 등록한 후에는 리전을 변경할 수 없습니다.
클러스터를 업데이트합니다.
```
bmctl update cluster -c ADMIN_CLUSTER_NAME \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
다음을 바꿉니다.
- ADMIN_CLUSTER_NAME: 업데이트할 관리자 클러스터의 이름입니다.
- ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.

클러스터 정보 가져오기

클러스터가 등록되면 다음 명령어를 사용하여 클러스터에 대한 정보를 가져올 수 있습니다.

사용자 클러스터

사용자 클러스터를 설명하려면 다음 안내를 따르세요.

gcloud container bare-metal clusters describe USER_CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=REGION

사용자 클러스터를 나열하려면 다음 안내를 따르세요.

gcloud container bare-metal clusters list \
    --project=PROJECT_ID \
    --location=-

--location=-을 설정하면 모든 리전의 모든 클러스터가 나열됩니다. 목록의 범위를 좁혀야 하는 경우 클러스터를 등록할 때 지정한 리전으로 --location을 설정합니다.

관리자 클러스터

관리자 클러스터를 설명하려면 다음 안내를 따르세요.

gcloud container bare-metal admin-clusters describe ADMIN_CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=REGION

관리자 클러스터를 나열하려면 다음 안내를 따르세요.

gcloud container bare-metal admin-clusters list \
    --project=PROJECT_ID \
    --location=-

클러스터에 연결

클러스터를 GKE On-Prem API에 등록한 후에는 Google Cloud 콘솔에서 클러스터를 관리할 수 있도록 인증 방법을 선택하고 구성해야 합니다. 선택한 인증 방법은 명령줄에서 클러스터에 대한 액세스도 제어합니다. 자세한 내용은 다음을 참조하세요.