GKE On-Prem API 클라이언트를 사용하여 관리자 클러스터 만들기

이 페이지에서는 Google Cloud 콘솔 또는 Google Cloud CLI(gcloud CLI)를 사용하여 관리자 클러스터를 만드는 방법을 설명합니다. 이러한 표준 Google Cloud 클라이언트 모두 GKE On-Prem API를 사용하여 클러스터를 만듭니다.

GKE On-Prem API란?

GKE On-Prem API는 Terraform 및 표준 Google Cloud 애플리케이션을 사용하여 온프레미스 클러스터의 수명 주기를 관리할 수 있게 해주는 Google Cloud 호스팅 API입니다. GKE On-Prem API는 Google Cloud 인프라에서 실행됩니다. Terraform, 콘솔 및 gcloud CLI는 API의 클라이언트이며 API를 사용하여 데이터 센터에 클러스터를 만듭니다.

클러스터의 수명 주기를 관리하려면 GKE On-Prem API가 클러스터를 만들 때 지정한 Google Cloud 리전을 사용하여 클러스터 상태에 대한 메타데이터를 Google Cloud에 저장해야 합니다. 이 메타데이터를 사용하면 API에서 클러스터 수명 주기를 관리할 수 있으며 워크로드별 데이터는 포함되지 않습니다.

GKE On-Prem API 클라이언트를 사용하여 클러스터를 만든 경우 Google Cloud 프로젝트를 지정합니다. 클러스터가 생성되면 지정된 프로젝트의 Fleet에 자동으로 등록됩니다. 이 프로젝트를 Fleet 호스트 프로젝트라고 합니다. 클러스터를 만든 후에는 Fleet 호스트 프로젝트를 변경할 수 없습니다.

원하는 경우 관리자 클러스터 만들기에 설명된 대로 관리자 클러스터 구성 파일을 만들고 bmctl을 사용하여 관리자 클러스터를 만들 수 있습니다.

콘솔이나 gcloud CLI를 사용하여 bmctl로 만든 클러스터의 수명 주기를 관리하려면 GKE On-Prem API에서 관리할 클러스터 구성을 참조하세요.

IAM 권한

Google Cloud 프로젝트 소유자가 아닌 경우 프로젝트 소유자에게 다음 역할을 부여해 달라고 요청해야 합니다.

콘솔에서 GKE Enterprise 및 GKE 페이지에 액세스하려면 roles/container.viewer도 있어야 합니다.

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

명령줄 액세스 권한

클러스터가 생성된 후 Connect 게이트웨이를 사용하여 관리자 워크스테이션 이외의 컴퓨터에서 kubectl 명령어를 실행하려면 사용할 컴퓨터에 다음 명령줄 도구를 설치합니다.

  • gcloud CLI의 최신 버전

  • Kubernetes 클러스터에 명령어를 실행하기 위한 kubectl. kubectl을 설치해야 하는 경우 이 안내를 따르세요.

클라이언트를 선택하여 관리자 클러스터 만들기

콘솔이나 gcloud CLI를 사용하여 GKE On-Prem API에서 관리하는 관리자 클러스터를 만들 수 있습니다. Google Distributed Cloud를 처음 설치하는 경우 gcloud CLI보다 콘솔 사용이 더 쉬울 수 있습니다.

클러스터를 만들기 위해 제공해야 하는 정보에 익숙해진 다음에는 명령어를 해당 인수와 함께 텍스트 파일에 저장할 수 있기 때문에 gcloud CLI가 더 편리하게 느껴질 수 있습니다. Cloud Build와 같은 CI/CD 도구를 사용할 경우에는 gcloud 명령어를 사용하여 클러스터를 만들고 --impersonate-service-account 플래그를 지정하여 만들기를 자동화할 수 있습니다.

기본 요건

콘솔

  1. 콘솔에서 Distributed Cloud 클러스터 만들기 페이지로 이동합니다.

    Distributed Cloud 클러스터 만들기로 이동

  2. 클러스터를 만들 Google Cloud 프로젝트를 선택합니다. 선택한 프로젝트는 Fleet 호스트 프로젝트로도 사용됩니다.

기본 요건 페이지에 관리자 워크스테이션 및 클러스터 노드 머신의 요구사항이 표시됩니다. 네트워크 요구사항 섹션의 IP 주소 플래너를 사용하면 관리자 클러스터 한 개와 사용자 클러스터 한 개의 최소 설치에 필요한 IP 주소를 계획할 수 있습니다.

관리자 워크스테이션 기본 요건

이 섹션을 펼쳐 관리자 워크스테이션의 하드웨어, 운영체제, 연결 요구사항을 표시합니다.

클러스터 노드 머신 기본 요건

이 섹션을 펼쳐 클러스터 노드 머신의 하드웨어, 운영체제, 연결 요구사항을 표시합니다.

네트워크 요구사항

이 섹션은 최소한의 환경에 필요한 IP 주소를 계획하는 데 도움이 됩니다. 필요한 경우 노드 IP 및 가상 IP 주소 섹션에서 시작 노드 IP 주소 및 가상 IP 주소(VIP)를 제공할 수 있으며 콘솔에 필요한 IP 주소의 테이블이 표시됩니다. 이러한 IP 주소는 관리자 클러스터 구성에 적용되지는 않고 설치에 필요한 IP 주소를 계획하는 데 도움이 되는 가이드로 사용됩니다. 테이블을 CSV 파일로 다운로드한 후 스프레드시트 또는 IP 주소 계획 도구로 가져와서 클러스터에 필요한 IP 주소를 추적하는 시작점으로 사용할 수 있습니다.

Google Cloud 리소스 검토:

Fleet 호스트 프로젝트에서 모든 필수 Google API가 사용 설정되었는지 확인합니다. 또한 GKE On-Prem API를 사용 설정해야 합니다.

gcloud services enable --project FLEET_HOST_PROJECT_ID \
  gkeonprem.googleapis.com

FLEET_HOST_PROJECT_ID를 Fleet 호스트 프로젝트의 프로젝트 ID로 바꿉니다.

클러스터를 만들기 전에 부트스트랩 환경 준비에 설명된 대로 관리자 워크스테이션에서 bmctl register bootstrap 명령어를 실행합니다. 이 명령어는 관리자 클러스터를 만드는 데 필요한 최소 IAM 권한으로 필수 서비스 계정을 만들 수 있습니다. 원하는 경우 수동으로 서비스 계정을 구성할 수 있습니다.

시작할 준비가 되면 왼쪽 탐색 메뉴에서 부트스트랩 환경 설치를 클릭합니다.

gcloud CLI

하드웨어, 네트워킹, 운영체제의 기본 요건

GKE On-Prem API 클라이언트를 사용하여 관리자 클러스터를 만들려면 bmctl을 사용하여 클러스터를 만들 때와 동일한 하드웨어, 네트워킹, 운영체제 기본 요건을 충족해야 합니다. 자세한 내용은 설치 기본 요건을 참조하세요.

필수 Google API

Fleet 호스트 프로젝트에서 모든 필수 Google API가 사용 설정되었는지 확인합니다. 또한 GKE On-Prem API를 사용 설정해야 합니다.

gcloud services enable --project FLEET_HOST_PROJECT_ID \
  gkeonprem.googleapis.com

FLEET_HOST_PROJECT_ID를 Fleet 호스트 프로젝트의 프로젝트 ID로 바꿉니다.

필수 서비스 계정 및 권한

클러스터를 만들기 전에 부트스트랩 환경 준비에 설명된 대로 관리자 워크스테이션에서 bmctl register bootstrap 명령어를 실행합니다. 이 명령어는 관리자 클러스터를 만드는 데 필요한 최소 IAM 권한으로 필수 서비스 계정을 만들 수 있습니다. 원하는 경우 수동으로 서비스 계정을 구성할 수 있습니다.

IP 주소 계획

관리자 클러스터를 만들기 전에 클러스터의 IP 주소를 계획해야 합니다. 고가용성(HA) 관리자 클러스터 및 HA 사용자 클러스터 2개에 IP 주소를 할당하는 방법의 예시는 IP 주소 계획을 참조하세요. gcloud CLI를 사용하여 관리자 클러스터를 만드는 경우에도 이 섹션의 콘솔 단계에 따라 IP 주소 플래너를 사용해야 할 수 있습니다.

부트스트랩 환경 준비

관리자 클러스터를 만들려면 먼저 관리자 워크스테이션에서 bmctl register bootstrap 명령어를 실행해야 합니다. 이 명령어는 관리자 워크스테이션에 Docker의 Kubernetes(종류) 클러스터를 배포합니다. 이 부트스트랩 클러스터는 관리자 클러스터를 만드는 데 필요한 Kubernetes 컨트롤러를 호스팅합니다. 관리자 클러스터를 만들면 부트스트랩 클러스터의 컨트롤러가 노드를 프로비저닝하고, 프리플라이트 검사를 실행하고 Fleet에 관리자 클러스터를 등록합니다. 클러스터가 성공적으로 생성된 후 부트스트랩 클러스터가 자동으로 삭제됩니다.

콘솔

  1. 관리자 클러스터의 이름을 입력합니다. 부트스트랩 클러스터 이름은 관리자 클러스터 이름 앞에 bootstrap-을 추가하여 파생됩니다.

  2. 관리자 클러스터의 Google Distributed Cloud 버전을 선택합니다.

  3. Google Cloud API 위치 필드의 목록에서 Google Cloud 리전을 선택합니다. 이 설정은 다음 API 및 서비스가 실행되는 리전을 지정합니다.

    • GKE On-Prem API(gkeonprem.googleapis.com)
    • Fleet 서비스(gkehub.googleapis.com)
    • 연결 서비스(gkeconnect.googleapis.com)

    이 설정은 다음 항목이 저장되는 리전도 제어합니다.

    • GKE On-Prem API에서 클러스터 수명 주기를 관리하는 데 필요한 클러스터 메타데이터
    • 시스템 구성요소의 Cloud Logging 및 Cloud Monitoring 데이터
    • Cloud 감사 로그에서 만든 관리자 감사 로그

    클러스터 이름, 프로젝트, 위치에 따라 Google Cloud의 클러스터가 고유하게 식별됩니다.

  4. 콘솔에 관리자 워크스테이션에서 실행해야 하는 명령어가 표시됩니다. bmctl 명령줄 도구는 만들고 있는 클러스터 버전과 일치해야 합니다. 관리자 워크스테이션에 bmctl의 해당 버전을 이미 다운로드한 경우 이를 다시 다운로드할 필요가 없습니다.

gcloud CLI

  1. 구성요소를 업데이트합니다.

    gcloud components update
    
  2. 다음 명령어를 실행하여 Google 계정으로 로그인합니다.

    gcloud auth login
    
  3. 설치할 수 있는 사용 가능한 Google Distributed Cloud 버전을 나열합니다. 부트스트랩 환경을 만들기 위해 다운로드하는 bmctl 버전은 관리자 클러스터에 설치할 버전과 일치해야 합니다.

    gcloud container bare-metal admin-clusters query-version-config \
      --location=REGION
    

    REGION을 클러스터를 만들 때 사용할 Google Cloud 리전으로 바꿉니다. GKE On-Prem API와 Fleet 및 Connect 서비스가 실행되는 리전입니다. us-west1 또는 다른 지원되는 리전을 지정합니다.

부트스트랩 클러스터 만들기

관리자 워크스테이션에서 다음 단계를 수행합니다. 이러한 명령어는 콘솔에 표시됩니다.

  1. 사용자 인증 정보를 애플리케이션 기본 사용자 인증 정보(ADC)로 설정합니다.

    gcloud auth application-default login
    

    메시지에 따라 ADC용 Google 계정을 선택합니다.

  2. 필요한 경우 bmctl 명령줄 도구를 현재 작업 디렉터리에 다운로드합니다.

    gcloud storage cp gs://anthos-baremetal-release/bmctl/VERSION/linux-amd64/bmctl .
    chmod a+x ./bmctl
    

    VERSION을 설치하려는 Google Distributed Cloud 버전으로 바꿉니다. 콘솔에서 명령어를 복사한 경우 버전이 이미 명령어에 있습니다.

  3. 부트스트랩 클러스터를 만듭니다. bmctl에서 필요한 서비스 계정(SA)을 만들도록 하거나 직접 서비스 계정을 만들고 키 파일을 만들어 bmctl register bootstrap 명령어에 전달할 수 있습니다.

bmctl이 SA 생성

bmctl이 관리자 클러스터를 만드는 데 필요한 최소 권한으로 필요한 서비스 계정을 만들도록 하려면 다음 명령어를 사용합니다. 이 명령어는 bmctl이 현재 작업 디렉터리에 있다고 가정합니다.

./bmctl register bootstrap \
  --ssh-key=YOUR_PRIVATE_KEY \
  --target-cluster-name=ADMIN_CLUSTER_NAME \
  --project-id=FLEET_HOST_PROJECT_ID

다음을 바꿉니다.

콘솔에 표시된 명령어를 복사했다면 다음 필드가 이미 채워져 있을 겁니다.

  • ADMIN_CLUSTER_NAME: 관리자 클러스터 이름.

  • FLEET_HOST_PROJECT_ID: 관리자 클러스터가 생성된 후 자동으로 등록되는 프로젝트.

bmctl register bootstrap 명령어는 다음 서비스 계정을 만듭니다. 서비스 계정 키는 bmctl-workspace/.sa-keys 디렉터리에 저장됩니다.

서비스 계정 목적 IAM 역할
anthos-baremetal-gcr Google Distributed Cloud는 이 서비스 계정을 사용하여 Google Container Registry에서 컨테이너 이미지를 다운로드합니다. 없음
anthos-baremetal-connect Connect Agent는 이 서비스 계정을 사용하여 클러스터와 Google Cloud 간의 연결을 유지합니다. roles/gkehub.connect
anthos-baremetal-register Connect Agent는 이 서비스 계정을 사용하여 Google Cloud Fleet에 클러스터를 등록합니다. roles/gkehub.admin
anthos-baremetal-cloud-ops Stackdriver Agent는 이 서비스 계정을 사용하여 클러스터의 로그와 측정항목을 Cloud Logging 및 Cloud Monitoring으로 내보냅니다. roles/logging.logWriter
roles/monitoring.metricWriter
roles/stackdriver.resourceMetadata.writer
roles/opsconfigmonitoring.resourceMetadata.writer
roles/monitoring.dashboardEditor

SA 키 파일 지정

원하는 경우 만든 서비스 계정 키 파일을 bmctl에 전달할 수 있습니다. 다음 명령어는 수동으로 서비스 계정 구성의 키 파일 이름을 사용하고 bmctl 및 키 파일이 현재 작업 디렉터리에 있다고 가정합니다.

./bmctl register bootstrap \
  --ssh-key=YOUR_PRIVATE_KEY \
  --target-cluster-name=ADMIN_CLUSTER_NAME \
  --project-id=FLEET_HOST_PROJECT_ID \
  --gcr-service-account-key=anthos-baremetal-gcr.json \
  --gke-agent-service-account-key=connect-agent.json \
  --gke-register-service-account-key=connect-register.json \
  --cloud-operation-service-account-key=anthos-baremetal-cloud-ops.json

다음을 바꿉니다.

  • YOUR_PRIVATE_KEY: 비공개 SSH 키 경로입니다. 노드에 대한 루트 SSH 액세스를 설정할 때 SSH 키를 만들었습니다.

  • ADMIN_CLUSTER_NAME: 관리자 클러스터 이름.

  • FLEET_HOST_PROJECT_ID: 관리자 클러스터가 생성된 후 자동으로 등록되는 프로젝트.

다음 플래그는 키 파일의 경로를 지정합니다.

  • -gcr-service-account-key: 컨테이너 이미지를 가져오는 서비스 계정의 키 파일 경로입니다(anthos-baremetal-gcr).

  • --gke-agent-service-account-key: Connect Agent 서비스 계정의 키 파일 경로입니다(anthos-baremetal-connect).

  • --gke-register-service-account-key: 클러스터를 Fleet에 등록하는 Connect Agent 서비스 계정의 키 파일 경로입니다(anthos-baremetal-register).

  • --cloud-operation-service-account-key: 로그를 감사하고 프로젝트를 모니터링하기 위한 서비스 계정의 키 파일 경로입니다(anthos-baremetal-cloud-ops).

bmctl이 부트스트랩 클러스터를 성공적으로 만들면 다음과 비슷한 출력이 표시됩니다.

[2023-03-22 17:35:24+0000] Waiting for the temporary cluster to be registered... OK
[2023-03-22 17:35:37+0000] Please go to https://console.cloud.google.com/home/dashboard?project=example-project-12345 to create the cluster
[2023-03-22 17:35:37+0000] Waiting for preflight checks and cluster to run..

관리자 클러스터 만들기

콘솔

  1. 부트스트랩 환경 설치 페이지에서 연결 확인을 클릭합니다.

    성공하면 콘솔에 연결 설정됨이 표시됩니다.

    계속하기 전에 부트스트랩 클러스터에 대한 연결을 설정해야 합니다. 연결이 설정되지 않았으면 bmctl register bootstrap 명령어에 지정한 인수를 확인합니다.

    • --target-cluster-name의 값이 부트스트랩 환경 기본사항 섹션에 표시된 관리자 클러스터 이름과 일치하는지 확인합니다.

    • --project-id 값이 콘솔에서 선택한 프로젝트의 ID와 일치하는지 확인합니다.

    부트스트랩 클러스터 이름 또는 프로젝트 ID를 변경해야 하는 경우 Ctrl-C를 입력하여 bmctl register bootstrap을 종료하고 명령어를 다시 실행합니다.

  2. Next를 클릭하여 관리자 클러스터 구성을 시작합니다. 콘솔에 있는 대부분의 설정은 클러스터 구성 파일의 필드에 해당합니다.

  3. 노드 구성에서 노드당 최대 포드 수에 64~250 사이의 값을 입력하거나 기본값인 110을 수락합니다. 클러스터가 생성된 후에는 이 값을 업데이트할 수 없습니다.

    또한 노드당 최대 포드 수(포드 밀도)는 클러스터의 사용 가능한 IP 리소스에 의해 제한됩니다. 자세한 내용은 포드 네트워킹을 참조하세요.

  4. 다음을 클릭합니다.

  5. 네트워킹 페이지에서 클러스터의 노드 및 구성요소가 서로 통신하고 Kubernetes 제어 영역과 통신하는 방법을 정의합니다.

    자세한 내용을 보려면 각 필드 옆에 있는 위에 마우스 포인터를 올려놓으세요.

  6. 확인 및 만들기를 클릭합니다.

    콘솔은 설정을 확인하고 데이터 센터에 클러스터를 만들 때 상태 메시지를 표시합니다.

    구성에 문제가 있으면 콘솔에 구성 문제를 해결하고 클러스터를 다시 만들 수 있도록 명확한 오류 메시지가 표시됩니다.

gcloud CLI

관리자 클러스터를 만들기 전에 부트스트랩 클러스터가 Fleet의 구성원으로 등록되었는지 확인합니다.

gcloud container fleet memberships list \
  --project=FLEET_HOST_PROJECT_ID

부트스트랩 클러스터가 나열되지 않았으면 bmctl register bootstrap에 지정한 부트스트랩 클러스터 이름과 프로젝트 ID를 확인합니다. 부트스트랩 클러스터 이름 또는 프로젝트 ID를 변경해야 하는 경우 Ctrl-C를 입력하여 bmctl register bootstrap을 종료하고 명령어를 다시 실행합니다.

다음 명령어를 사용하여 관리자 클러스터를 만듭니다.

gcloud container bare-metal admin-clusters create

명령어에 지정하는 대부분의 플래그는 사용자 클러스터 구성 파일의 필드에 해당합니다.

번들 부하 분산기를 사용하는 관리자 클러스터를 만들려면 다음 안내를 따르세요.

gcloud container bare-metal admin-clusters create ADMIN_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --version=VERSION \
  --max-pods-per-node=MAX_PODS_PER_NODE \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LOAD_BALANCER_PORT \
  --control-plane-node-configs 'CONTROL_PLANE_NODE_CONFIG' \
  --island-mode-service-address-cidr-blocks=SERVICE_ADDR_CIDR \
  --island-mode-pod-address-cidr-blocks=POD_ADDR_CIDR \
  --lvp-share-path=/mnt/localpv-share \
  --lvp-share-storage-class=local-shared \
  --lvp-node-mounts-config-path=/mnt/localpv-disk \
  --lvp-node-mounts-config-storage-class=local-disks

수동 부하 분산을 사용하려면 명령어에 --enable-manual-lb를 추가합니다.

다음을 바꿉니다.

  • ADMIN_CLUSTER_NAME: 관리자 클러스터 이름. 클러스터를 만든 후에는 이름을 변경할 수 없습니다.

  • FLEET_HOST_PROJECT_ID: 관리자 클러스터가 생성된 후 자동으로 등록되는 프로젝트. 클러스터를 만든 후에는 Fleet 호스트 프로젝트를 변경할 수 없습니다.

  • REGION: GKE On-Prem API가 실행되는 Google Cloud 리전. us-west1 또는 다른 지원되는 리전을 지정합니다. 클러스터를 만든 후에는 리전을 변경할 수 없습니다. 이 설정은 다음이 저장되는 리전을 지정합니다.

    • GKE On-Prem API에서 클러스터 수명 주기를 관리하는 데 필요한 클러스터 메타데이터
    • 시스템 구성요소의 Cloud Logging 및 Cloud Monitoring 데이터
    • Cloud 감사 로그에서 만든 관리자 감사 로그

    클러스터 이름, 프로젝트, 위치에 따라 Google Cloud의 클러스터가 고유하게 식별됩니다.

  • VERSION: Google Distributed Cloud 버전. 이 버전은 bmctl register bootstrap을 실행하는 데 사용한 bmctl 버전과 일치해야 합니다. 관리자 워크스테이션에서 bmctl version을 실행하여 bmctl 버전을 확인할 수 있습니다.

  • MAX_PODS_PER_NODE : 관리자 클러스터의 경우 허용되는 값은 비 HA 클러스터의 경우 32~250, 64~250입니다. 명령어에 --max-pods-per-node가 포함되지 않은 경우 기본값은 110입니다. 클러스터가 생성된 후에는 이 값을 업데이트할 수 없습니다.

    또한 노드당 최대 포드 수(포드 밀도)는 클러스터의 사용 가능한 IP 리소스에 의해 제한됩니다. 자세한 내용은 포드 네트워킹을 참조하세요.

  • CONTROL_PLANE_VIP: 클러스터의 Kubernetes API 서버의 부하 분산기에 있는 가상IP(VIP). 부하 분산기 노드와 동일한 서브넷에 제어 영역 VIP를 포함합니다. 부하 분산기 주소 풀에 제어 영역 VIP를 포함하지 않습니다.

  • CONTROL_PLANE_LOAD_BALANCER_PORT: 부하 분산기가 제어 영역에 제공하는 포트. 다른 값을 구성할 수 있지만 포트 443이 HTTPS 연결에 사용되는 표준 포트입니다.

  • CONTROL_PLANE_NODE_CONFIG: 제어 영역 노드의 IPv4 주소. 제어 영역 노드는 시스템 워크로드를 실행합니다. 각 제어 영역 노드에 이 플래그를 지정합니다. 일반적으로 최소 배포를 사용하는 경우에는 단일 머신이 있고 고가용성(HA) 배포를 사용하는 경우에는 머신이 3개 있습니다. 고가용성을 위해 대다수의 쿼럼을 가지도록 노드를 홀수로 지정하세요. 이러한 주소는 클러스터를 업데이트하거나 업그레이드할 때마다 변경할 수 있습니다.

    플래그 값의 형식은 다음과 같습니다.

    'node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \
    

    값에 node-iplabels 키워드로 시작하는 세그먼트가 있습니다. 각 세그먼트를 쉼표로 구분합니다.

    • node-ip: 제어 영역 노드의 IP 주소. 플래그당 node-ip 하나만 지정할 수 있습니다. 노드를 두 개 이상 지정해야 하는 경우 각 노드에 플래그를 다시 포함합니다.

    • labels: 노드에 연결된 하나 이상의 키-값 쌍

    다음 문법 규칙에 유의하세요.

    • 전체 값은 작은따옴표로 묶어야 합니다.
    • 공백은 허용되지 않습니다.
    • labels 세그먼트의 각 키-값 쌍을 세미콜론으로 구분합니다.

    예를 들면 다음과 같습니다.

    --control-plane-node-configs 'node-ip=192.0.2.1' \
    --control-plane-node-configs 'node-ip=192.0.2.2,labels=key2.1=value2.1' \
    --control-plane-node-configs 'node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
    
  • SERVICE_ADDR_CIDR: 클러스터의 서비스에 대한 CIDR 형식의 IPv4 주소 범위. CIDR 범위는 /24에서 /12 사이여야 합니다. 여기서 /12는 대부분의 IP 주소를 제공합니다. RFC 1918에 정의된 비공개 인터넷에 대한 IP 주소 공간 범위를 사용하는 것이 좋습니다(예: 10.96.0.0/20).

  • POD_ADDR_CIDR: 사용자 클러스터의 포드에 사용할 CIDR 형식의 IPv4 주소 범위. CIDR 범위는 /18에서 /8 사이여야 합니다. 여기서 /8은 대부분의 IP 주소를 제공합니다. RFC 1918에 정의된 대로 비공개 인터넷에 대한 IP 주소 공간 범위를 사용하는 것이 좋습니다(예: 192.168.0.0/16).

다음 스토리지 플래그를 지정해야 합니다. 이 예시 명령어에는 일반적인 값이 포함됩니다. 자세한 내용은 로컬 스토리지 구성을 참조하세요.

  • --lvp-share-path: 하위 디렉터리를 만들 수 있는 호스트 머신 경로. 각 하위 디렉터리에 대해 로컬 PersistentVolume(PV)이 생성됩니다.

  • --lvp-share-storage-class: 영구 볼륨을 만드는 데 사용할 StorageClass. StorageClass는 클러스터 생성 중에 생성됩니다.

  • --lvp-node-mounts-config-path: 마운트된 디스크를 검색할 수 있는 호스트 머신 경로. 각 마운트마다 로컬 PersistentVolume(PV)이 생성됩니다.

  • --lvp-node-mounts-config-storage: 클러스터 생성 중에 PV가 만든 스토리지 클래스.

플래그 및 해당 설명의 전체 목록은 gcloud CLI 참조를 확인하세요.

명령어 출력은 다음과 비슷합니다.

Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.

예시 출력에서 operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 문자열은 장기 실행 작업의 OPERATION_ID입니다. 다음 명령어를 사용하여 작업 상태를 확인할 수 있습니다.

gcloud container bare-metal operations describe OPERATION_ID \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

자세한 내용은 gcloud 컨테이너 베어메탈 작업을 참조하세요.

프리플라이트 오류 해결하기

bmctl은 클러스터를 만들기 전에 일련의 실행 전 검사를 실행하여 구성을 확인합니다. 구성에 문제가 있는 경우 gcloud ... create 명령어가 다음과 유사한 오류와 함께 종료됩니다.

ERROR: (gcloud.container.bare-metal.admin-clusters.create) Invalid resource state for "projects/694677185633/locations/us-west1/bareMetalAdminClusters/abm-cluster-1": cluster preflight checks failed

예를 들어 제어 영역 노드에 연결할 수 없어서 실행 전 검사가 실패했다고 가정해 보겠습니다. 관리자 워크스테이션에 다음과 비슷한 내용이 표시됩니다.

[2023-03-27 20:34:38+0000] Waiting for preflight check job to finish... OK
[2023-03-27 20:35:58+0000] - Validation Category: machines and network
[2023-03-27 20:35:58+0000]    - [PASSED] pod-cidr
[2023-03-27 20:35:58+0000]    - [FAILED] node-network (log: bmctl-workspace/log/register-bootstrap-20230327-201548/node-network)
[2023-03-27 20:35:58+0000]        - Failed to connect to the host via ssh: ssh: connect to host 10.100.0.5 port 22: Connection timed out
[2023-03-27 20:35:58+0000] Flushing logs... OK
[2023-03-27 20:35:58+0000] Error polling the preflight check abm-cluster-mar-27 in the cluster-abm-cluster-mar-27: preflight check failed
  1. 관리자 워크스테이션에서 bmctl register bootstrap 프로세스가 계속 실행 중인지 확인합니다. 그렇지 않으면 동일한 인수로 명령어를 다시 실행하고 --reuse-bootstrap-cluster=true 플래그를 추가합니다.

  2. gcloud ... update를 실행하여 잘못된 IP 주소를 수정합니다.

    gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
      --project=FLEET_HOST_PROJECT_ID \
      --location=REGION \
      --control-plane-node-configs 'node-ip=NEW_NODE_ID_ADDRESS'
    

    자세한 내용은 gcloud 컨테이너 베어메탈 관리자 클러스터 업데이트를 참조하세요.

클러스터 만들기 프로세스에 대한 세부정보가 관리자 워크스테이션에 출력됩니다. 프리플라이트 검사가 통과하면 다음과 비슷하게 표시됩니다.

[2023-03-22 23:12:47+0000] Waiting for cluster kubeconfig to become ready OK
[2023-03-22 23:15:47+0000] Writing kubeconfig file
[2023-03-22 23:15:47+0000] kubeconfig of cluster being created is present at bmctl-workspace/abm-cluster-1/abm-cluster-1-kubeconfig
[2023-03-22 23:15:47+0000] Please restrict access to this file as it contains authentication credentials of your cluster.
[2023-03-22 23:15:47+0000] Waiting for cluster to become ready OK
[2023-03-22 23:20:17+0000] Please run
[2023-03-22 23:20:17+0000] kubectl --kubeconfig bmctl-workspace/abm-cluster-1/abm-cluster-1-kubeconfig get nodes
[2023-03-22 23:20:17+0000] to get cluster nodes status.
[2023-03-22 23:20:17+0000] Waiting for node pools to become ready OK
[2023-03-22 23:20:37+0000] Waiting for metrics to become ready in GCP OK
[2023-03-22 23:25:38+0000] Waiting for cluster API provider to install in the created admin cluster OK
[2023-03-22 23:25:48+0000] Moving admin cluster resources to the created admin cluster
[2023-03-22 23:25:51+0000] Waiting for node update jobs to finish OK
[2023-03-22 23:27:41+0000] Flushing logs... OK
[2023-03-22 23:27:41+0000] Deleting membership... OK
[2023-03-22 23:27:42+0000] Deleting bootstrap cluster.

관리자 클러스터에 연결

bmctl register bootstrap 명령어는 관리자 워크스테이션에서 관리자 클러스터용 kubeconfig 파일을 만듭니다. kubeconfig가 있는 디렉터리와 파일 이름은 다음과 같이 관리자 클러스터 이름을 기반으로 합니다.

bmctl-workspace/ADMIN_CLUSTER_NAME/ADMIN_CLUSTER_NAME-kubeconfig

클러스터의 사용자 인증 정보가 포함되어 있으므로 이 kubeconfig에 대한 액세스를 제한해야 합니다.

Google ID를 사용하여 클러스터에 로그인하려면 다음과 같이 Connect 게이트웨이를 설정하면 됩니다.

  1. 관리자 워크스테이션에서 KUBECONFIG 환경 변수를 설정합니다.

    export KUBECONFIG=$HOME/bmctl-workspace/ADMIN_CLUSTER_NAME/ADMIN_CLUSTER_NAME-kubeconfig
    
  2. 환경 변수에 현재 컨텍스트를 설정합니다.

    export CONTEXT="$(kubectl config current-context)"
    
  3. 다음 gcloud 명령어를 실행합니다. 이 명령어는 다음을 수행합니다.

    • 사용자 계정에 클러스터에 대한 Kubernetes clusterrole/view 역할을 부여합니다.
    • 관리자 워크스테이션에 SSH로 연결할 필요 없이 로컬 컴퓨터에서 읽기 전용 kubectl 명령어를 실행할 수 있도록 클러스터를 구성합니다.

    GOOGLE_ACCOUNT_EMAIL을 Google Cloud 계정과 연결된 이메일 주소로 바꿉니다. 예를 들면 --users=alex@example.com입니다.

    gcloud container fleet memberships generate-gateway-rbac  \
        --membership=ADMIN_CLUSTER_NAME \
        --role=clusterrole/view \
        --users=GOOGLE_ACCOUNT_EMAIL \
        --project=FLEET_HOST_PROJECT_ID \
        --kubeconfig=$KUBECONFIG \
        --context=$CONTEXT\
        --apply
    

    이 명령어의 출력은 가독성을 위해 잘려서 표시된 다음과 비슷합니다.

    Validating input arguments.
    Specified Cluster Role is: clusterrole/view
    Generated RBAC policy is:
    --------------------------------------------
    ...
    
    Writing RBAC policy for user: GOOGLE_ACCOUNT_EMAIL to cluster.
    Successfully applied the RBAC policy to cluster.
    

이러한 RBAC 정책이 있으면 Google ID를 사용하여 콘솔에서 클러스터에 로그인할 수 있습니다. 또한 Connect 게이트웨이를 통해 요청을 라우팅하는 특수 kubeconfig를 사용하여 관리자 워크스테이션 이외의 컴퓨터에서 읽기 전용 kubectl 명령어를 실행할 수 있습니다.

  1. 관리자 워크스테이션 이외의 컴퓨터에서 다음 명령어를 실행하여 Connect 게이트웨이를 통해 클러스터에 액세스할 수 있는 kubeconfig 항목을 가져옵니다.

    gcloud container fleet memberships get-credentials ADMIN_CLUSTER_NAME \
        --project=FLEET_HOST_PROJECT_ID
    

    출력은 다음과 비슷합니다.

    Starting to build Gateway kubeconfig...
    Current project_id: FLEET_HOST_PROJECT_ID
    A new kubeconfig entry "connectgateway_FLEET_HOST_PROJECT_ID_global_ADMIN_CLUSTER_NAME" has been generated and set as the current context.
    
  2. 이제 Connect 게이트웨이를 통해 kubectl 명령어를 실행할 수 있습니다.

    kubectl get pods -A
    

다음 단계