토폴로지 도메인에 사용할 관리자 클러스터 만들기

이 페이지에서는 Google Distributed Cloud 토폴로지 도메인에서 사용할 관리자 클러스터를 만드는 방법을 보여줍니다. 관리자 클러스터는 워크로드를 실행하는 사용자 클러스터를 관리합니다. 토폴로지 도메인을 사용하려면 Google Distributed Cloud 버전 1.31 이상이 필요합니다.

토폴로지 도메인을 설정하려면 고급 클러스터를 사용 설정해야 합니다. 고급 클러스터 미리보기에는 다음과 같은 제한사항이 있습니다.

  • 새 1.31 클러스터의 경우 클러스터 생성 시점에만 고급 클러스터를 사용 설정할 수 있습니다.
  • 고급 클러스터를 사용 설정한 후에는 클러스터를 1.32로 업그레이드할 수 없습니다. 테스트 환경에서만 고급 클러스터를 사용 설정합니다.

이 페이지는 기술 인프라를 설정, 모니터링, 관리하는 관리자, 설계자, 운영자를 위해 작성되었습니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 작업에 대해 자세히 알아보려면 일반 GKE Enterprise 사용자 역할 및 작업을 참고하세요.

관리자 클러스터에 대한 자세한 내용은 설치 개요를 참조하세요.

절차 개요

관리자 클러스터 만들기에 포함된 기본 단계는 다음과 같습니다.

  1. 관리자 구성 파일 작성
    관리자 클러스터 구성 파일을 완료하여 새 관리자 클러스터의 세부정보를 지정합니다.
  2. vSphere 인프라 구성 파일 작성
    vSphere 인프라 구성 파일에서 토폴로지 도메인에 관한 세부정보를 지정합니다.
  3. IP 블록 파일 작성
    IP 블록 파일에서 게이트웨이, 넷마스크, 컨트롤 플레인 노드의 IP 주소를 지정합니다.
  4. OS 이미지 가져오기
    일반 Google Distributed Cloud 번들을 다운로드합니다. 그런 다음 gkectl prepare를 실행합니다. 이 명령어는 OS 이미지를 vSphere로 가져오고 해당하는 경우 컨테이너 이미지를 비공개 레지스트리로 푸시합니다.
  5. 관리자 클러스터를 만듭니다.
    gkectl을 사용하여 완료된 구성 파일에 지정된 대로 새 관리자 클러스터를 만듭니다. Google Distributed Cloud는 관리자 클러스터를 만들 때 Docker의 Kubernetes(kind) 클러스터를 배포하여 관리자 클러스터를 만드는 데 필요한 Kubernetes 컨트롤러를 일시적으로 호스팅합니다. 이러한 임시 클러스터를 부트스트랩 클러스터라고 합니다. 사용자 클러스터는 부트스트랩 클러스터를 사용하지 않고 관리 중인 관리자 클러스터를 통해 생성되고 업그레이드됩니다.
  6. 클러스터 관리자가 실행 중인지 확인합니다.
    kubectl을 사용하여 클러스터 노드를 확인합니다.

이 절차를 마치면 토폴로지 도메인에서 사용자 클러스터를 만들고 관리하는 데 사용할 수 있는 관리자 클러스터가 실행됩니다.

시작하기 전에

  • 관리자 워크스테이션 만들기에 설명된 대로 관리자 워크스테이션을 설정했고 로그인할 수 있는지 확인합니다. 관리자 워크스테이션에는 관리자 클러스터를 만드는 데 필요한 도구가 포함되어 있습니다. 관리자 워크스테이션에서 이 문서의 모든 단계를 수행합니다.

  • IP 주소 계획 문서를 검토합니다. 3개의 컨트롤 플레인 노드 및 컨트롤 플레인 VIP에 사용할 수 있는 IP 주소가 충분한지 확인합니다.

  • 수동 부하 분산을 위해 부하 분산기를 구성합니다. 관리자 클러스터를 만들기 전에 부하 분산기를 설정해야 합니다.

  • privateRegistry 섹션을 확인하고 Google Distributed Cloud 구성요소에 대해 공개 또는 비공개 레지스트리를 사용할지 결정합니다.

  • osImageType 필드를 확인하고 관리자 클러스터 노드에서 실행하려는 운영체제 유형을 결정합니다.

  • 조직에서 프록시 서버를 통과하도록 아웃바운드 트래픽이 필요한 경우 필요한 API와 아티팩트 레지스트리 주소를 허용 목록에 추가해야 합니다.

  • vCenter Server의 각 인스턴스에 액세스하는 데 필요한 정보를 수집합니다. vSphere 인프라 구성 파일의 Secret 섹션과 VSphereInfraConfig.credentials.vCenters 섹션을 작성하려면 이 정보가 필요합니다. 필요한 정보를 얻는 방법은 다음을 참고하세요.

관리자 클러스터 구성 파일 작성

gkeadm을 사용하여 관리자 워크스테이션을 만든 경우 admin-cluster.yaml이라는 구성 파일이 생성됩니다.

gkeadm을 사용하여 관리자 워크스테이션을 만들지 않은 경우 다음 명령어를 관리자 워크스테이션에서 실행하여 admin-cluster.yaml을 생성합니다.

gkectl create-config admin

이 구성 파일은 관리자 클러스터를 만들기 위한 것입니다.

관리자 클러스터 구성 파일 문서를 살펴봐서 구성 파일을 숙지합니다. 다음 단계를 완료할 때 참조되므로 이 문서를 개별 탭 또는 창으로 열어 두는 것이 좋을 수 있습니다.

name

관리자 클러스터 이름을 지정하려면 name 필드를 입력합니다.

bundlePath

번들은 클러스터 구성요소가 포함된 Zip 파일입니다. 관리자 워크스테이션에 포함되어 있습니다. 이 필드는 이미 채워져 있습니다.

enableAdvancedCluster

enableAdvancedCluster를 true로 설정합니다. 이렇게 하면 토폴로지 도메인을 설정하는 데 필요한 고급 클러스터를 사용할 수 있습니다.

infraConfigFilePath

infraConfigFilePath 필드에 vSphere 인프라 구성 파일의 전체 경로를 추가합니다.

vCenter

이 섹션 전체를 삭제합니다. 대신 vSphere 인프라 구성 파일에서 vCenter Server 정보를 구성합니다.

network

  • 구성 파일에서 다음을 삭제합니다.

    • 전체 network.hostConfig 섹션 이 정보는 토폴로지 도메인별로 vSphere 인프라 구성 파일에 구성됩니다.
    • network.vCenter.networkName 필드 이 필드는 토폴로지 도메인별로 vSphere 인프라 구성 파일에 구성됩니다.
    • 전체 network.controlPlaneIPBlock 섹션 게이트웨이, 네트워크 마스크, 컨트롤 플레인 노드의 IP 주소는 IP 블록 파일에 구성됩니다.

  • network.ipMode.ipBlockFilePath를 IP 블록 파일의 경로로 설정합니다.

  • network.ipMode.type를 static로 설정합니다.

  • network.podCIDR 및 network.serviceCIDR 필드에는 미리 입력된 값이 있으며, 네트워크에서 이미 사용 중인 주소와 충돌하지 않는 한 그대로 유지할 수 있습니다. Kubernetes는 이러한 범위를 사용하여 클러스터의 포드 및 서비스에 IP 주소를 할당합니다.

loadBalancer

  • loadBalancer.kind를 "ManualLB"로 설정하고 manualLB 섹션을 삭제합니다.

  • 관리자 클러스터의 Kubernetes API 서버에 대해 VIP를 별도로 설정합니다. VIP를 loadBalancer.vips.controlPlaneVIP의 값으로 제공합니다.

자세한 내용은 관리자 클러스터 서브넷의 VIP를 참조하세요.

antiAffinityGroups

antiAffinityGroups.enabled를 false로 설정합니다. Distributed Resource Scheduler(DRS) 안티어피니티 규칙은 토폴로지 도메인에서 지원되지 않습니다.

adminMaster

  • 관리자 클러스터의 제어 영역 노드에 CPU와 메모리를 지정하려면 adminMaster 섹션에서 cpus 및 memoryMB 필드를 입력합니다.

  • 관리자 클러스터에는 컨트롤 플레인 노드가 3개 있어야 합니다. adminMaster 섹션의 replicas 필드를 3로 설정합니다.

  • 제어 평면 노드가 사용할 특정 토폴로지 도메인을 지정하려면 adminMaster.topologyDomains 필드에 토폴로지 도메인 이름을 추가합니다. 여기서 이름을 지정하지 않으면 vSphere 인프라 구성 파일의 vSphereInfraConfig.defaultTopologyDomain에서 이름을 설정해야 합니다.

proxy

관리자 클러스터 노드를 포함할 네트워크가 프록시 서버 뒤에 있는 경우 proxy 섹션을 입력합니다.

privateRegistry

Google Distributed Cloud 구성요소의 컨테이너 이미지를 보관할 위치를 결정합니다. 옵션은 다음과 같습니다.

  • Artifact Registry

  • 자체 비공개 Docker 레지스트리입니다.

    자체 비공개 레지스트리를 사용하려면 privateRegistry 섹션을 입력합니다.

componentAccessServiceAccountKeyPath

Google Distributed Cloud는 구성요소 액세스 서비스 계정을 사용하여 Artifact Registry에서 클러스터 구성요소를 다운로드합니다. 이 필드에는 구성요소 액세스 서비스 계정에 대한 JSON 키 파일의 경로가 포함되어 있습니다.

이 필드는 이미 채워져 있습니다.

gkeConnect

gkeConnect 섹션을 입력하여 Google Cloud Fleet에 관리자 클러스터를 등록합니다. gkeConnect.projectID의 ID는 stackdriver.projectID 및 cloudAuditLogging.projectID에 설정된 ID와 동일해야 합니다. 프로젝트 ID가 동일하지 않으면 클러스터 생성에 실패합니다.

원하는 경우 gkeConnect.location에서 Fleet 및 Connect 서비스가 실행되는 리전을 지정할 수 있습니다. 이 필드를 포함하지 않으면 클러스터는 이러한 서비스의 전역 인스턴스를 사용합니다.

gkeConnect.location을 포함하는 경우 지정하는 리전은 cloudAuditLogging.clusterLocation, stackdriver.clusterLocation, gkeOnPremAPI.location에서 구성된 리전과 동일해야 합니다. 리전이 동일하지 않으면 클러스터 생성에 실패합니다.

gkeOnPremAPI

이 섹션에서는 클러스터를 GKE On-Prem API에 등록하는 방법을 설명합니다.

gkectl 명령줄 도구는 토폴로지 도메인을 사용하는 클러스터에 사용할 수 있는 유일한 클러스터 수명 주기 관리 도구입니다. Google Cloud 콘솔, Google Cloud CLI, Terraform은 토폴로지 도메인을 사용하는 클러스터에 지원되지 않지만, 원하는 경우 클러스터를 만들 때 GKE On-Prem API에 클러스터를 등록할 수 있습니다.

GKE On-Prem API가 Google Cloud 프로젝트에 사용 설정된 경우 프로젝트의 모든 클러스터가 stackdriver.clusterLocation에 구성된 리전의 GKE On-Prem API에 자동으로 등록됩니다. gkeOnPremAPI.location 리전은 cloudAuditLogging.clusterLocation, gkeConnect.location, stackdriver.clusterLocation에 지정된 리전과 동일해야 합니다. 리전이 동일하지 않으면 클러스터 생성에 실패합니다.

  • GKE On-Prem API에서 프로젝트의 모든 클러스터를 등록하려면 프로젝트의 GKE On-Prem API를 활성화하고 사용하기 위해 시작하기 전에의 단계를 수행해야 합니다.

  • GKE On-Prem API에서 클러스터를 등록하지 않으려면 이 섹션을 포함하고 gkeOnPremAPI.enabled를 false로 설정합니다. 프로젝트에 클러스터를 등록하지 않으려면 프로젝트에서 gkeonprem.googleapis.com(GKE On-Prem API의 서비스 이름)을 중지합니다. 자세한 내용은 서비스 사용 중지를 참조하세요.

stackdriver

stackdriver 섹션을 작성하여 클러스터에 Cloud Logging 및 Cloud Monitoring을 사용 설정합니다.

다음 요구사항을 참고하세요.

  • stackdriver.projectID의 ID는 gkeConnect.projectID 및 cloudAuditLogging.projectID의 ID와 동일해야 합니다.

  • stackdriver.clusterLocation에 설정된 Google Cloud 리전은 cloudAuditLogging.clusterLocation 및 gkeConnect.location에 설정된 리전과 동일해야 합니다. 또한 gkeOnPremAPI.enabled가 true인 경우 gkeOnPremAPI.location에 동일한 리전을 설정해야 합니다.

프로젝트 ID와 리전이 동일하지 않으면 클러스터 생성에 실패합니다.

cloudAuditLogging

클러스터 Kubernetes API 서버의 감사 로그를 Cloud 감사 로그와 통합하려면 cloudAuditLogging 섹션을 입력합니다.

새 클러스터에 대한 다음 요구사항을 참고하세요.

  • enableAdvancedCluster가 true로 설정되어 있으므로 cloudAuditLogging.serviceAccountKeyPath와 stackdriver.serviceAccountKeyPath에 동일한 경로를 지정해야 합니다.

  • cloudAuditLogging.projectID의 ID는 gkeConnect.projectID 및 stackdriver.projectID의 ID와 동일해야 합니다.

  • cloudAuditLogging.clusterLocation에 설정된 Google Cloud 리전은 stackdriver.clusterLocation 및 gkeConnect.location에 설정된 리전과 동일해야 합니다 (구성 파일에 필드가 포함된 경우). 또한 gkeOnPremAPI.enabled가 true인 경우 gkeOnPremAPI.location에 동일한 리전을 설정해야 합니다.

프로젝트 ID와 리전이 동일하지 않으면 클러스터 생성에 실패합니다.

clusterBackup

이 섹션을 삭제합니다. vSphere 데이터 스토어에 관리자 클러스터를 백업하는 기능은 지원되지 않습니다.

autoRepair

관리자 클러스터에 대해 자동 노드 복구를 사용 설정하려면 autoRepair.enabled를 true로 설정합니다.

secretsEncryption

enableAdvancedCluster가 true로 설정되어 있으므로 이 섹션을 삭제합니다.

osImageType

osImageType를 설정합니다. ubuntu_cgroupv2 또는 ubuntu_containerd입니다.

preparedSecrets

preparedSecrets 필드를 삭제합니다. 토폴로지 도메인이 사용 설정된 경우 준비된 사용자 인증 정보는 지원되지 않습니다.

작성된 구성 파일 예시

다음은 작성된 관리자 클러스터 구성 파일의 예시입니다. 이 구성에 따라 전부는 아니더라도 사용 가능한 기능 중 일부가 사용 설정됩니다.

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.31.0-gke.1-full.tgz"
enableAdvancedCluster: true
infraConfigFilePath: "/my-config-folder/vsphere-infrastructure-config.yaml"
network:
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  ipMode:
    type: "static"
    ipBlockFilePath: "/my-config-folder/admin-cluster-ipblock.yaml"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "ManualLB"
antiAffinityGroups:
  enabled: false
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
  topologyDomains: "admin-cluster-domain"
componentAccessServiceAccountKeyPath: "sa-key.json"
gkeConnect:
  projectID: "my-project-123"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
  disableVsphereResourceMetrics: false
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

vSphere 인프라 구성 파일 작성

vSphere 인프라 구성 파일의 템플릿을 관리자 클러스터 구성 파일의 infraConfigFilePath 필드에 지정한 디렉터리의 파일에 복사합니다. 관리자 클러스터와 모든 관리형 사용자 클러스터의 vSphere 인프라 구성 파일은 하나만 있습니다.

Secret

vSphere 인프라 구성 파일의 Secret 섹션을 입력합니다. 이 섹션에서는 각 vCenter Server의 사용자 인증 정보를 저장하는 vSphere 사용자 인증 정보 보안 비밀을 설명합니다.

VSphereInfraConfig.name

VSphereInfraConfig,name 필드를 입력합니다.

VSphereInfraConfig.credentials.vCenters

각 Secret에 해당하는 VSphereInfraConfig.credentials.vCenters 섹션을 추가합니다.

VSphereInfraConfig,topologyDomains

VSphereInfraConfig.topologyDomains 섹션을 작성하여 Topology Domains(토폴로지 도메인)을 정의합니다.

IP 블록 파일 작성

IP 블록 파일의 템플릿을 관리자 클러스터 구성 파일의 network.ipMode.ipBlockFilePath 필드에 지정한 디렉터리의 파일에 복사합니다. 게이트웨이, 네트마스크, 컨트롤 플레인 노드 3개의 IP 주소를 추가합니다. 각 제어 영역 노드 IP 주소에 토폴로지 도메인 예와 같이 isControlPlane: true를 추가합니다.

OS 이미지 가져오기

  1. 관리자 워크스테이션에 일반 Google Distributed Cloud 번들을 다운로드합니다.

    gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz /var/lib/gke/bundles/gke-onprem-vsphere-VERSION.tgz

    VERSION을 설치하려는 Google Distributed Cloud 버전으로 바꿉니다.

    이 명령어는 일반 번들을 다운로드합니다. 전체 번들은 고급 클러스터에서 지원되지 않으므로 다운로드하지 마세요.

  2. gkectl prepare를 실행하여 vSphere 환경을 초기화합니다.

    gkectl prepare --config ADMIN_CLUSTER_CONFIG

    ADMIN_CLUSTER_CONFIG를 관리자 클러스터 구성의 경로로 바꿉니다.

    gkectl prepare 명령어는 다음 준비 태스크를 수행합니다.

    • OS 이미지를 vSphere로 가져오고 VM 템플릿으로 표시합니다.

    • 비공개 Docker 레지스트리를 사용하는 경우 컨테이너 이미지를 레지스트리에 푸시합니다.

    • 선택적으로 컨테이너 이미지의 빌드 증명을 검사하여 이미지가 빌드되었고, Google에서 서명되었으며, 배포에 사용할 준비가 되었는지 확인합니다.

관리자 클러스터 만들기

관리자 클러스터를 만듭니다.

gkectl create admin --config ADMIN_CLUSTER_CONFIG

실패 후 관리자 클러스터 만들기 재개

관리자 클러스터 만들기가 실패하거나 취소된 경우 create 명령어를 다시 실행할 수 있습니다.

gkectl create admin --config ADMIN_CLUSTER_CONFIG

관리자 클러스터 kubeconfig 파일 찾기

gkectl create admin 명령어는 현재 디렉터리에 kubeconfig라는 kubeconfig 파일을 만듭니다. 나중에 관리자 클러스터와 상호작용하려면 이 kubeconfig 파일이 필요합니다.

kubeconfig 파일에는 관리자 클러스터의 이름이 포함되어 있습니다. 클러스터 이름을 보려면 다음을 실행합니다.

kubectl config get-clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

출력에 클러스터의 이름이 표시됩니다. 예를 들면 다음과 같습니다.

NAME
gke-admin-tqk8x

원하는 경우 kubeconfig 파일의 이름과 위치를 변경할 수 있습니다.

관리자 클러스터 실행 여부 확인

클러스터가 실행 중인지 확인합니다.

kubectl get nodes --kubeconfig ADMIN_CLUSTER_KUBECONFIG

ADMIN_CLUSTER_KUBECONFIG를 관리자 클러스터 kubeconfig 파일의 경로로 바꿉니다.

출력에 관리자 클러스터 노드가 표시됩니다. 예를 들면 다음과 같습니다.

admin-cp-vm-1   Ready    control-plane,master   ...
admin-cp-vm-2   Ready    control-plane,master   ...
admin-cp-vm-3   Ready    control-plane,master   ...

PodTemplate 구성

토폴로지 라벨은 토폴로지 도메인의 노드 라벨에 채워집니다. 토폴로지 도메인 설정에서 기본 제약 조건인 "topology.kubernetes.io/zone"를 토폴로지 키로 사용하지 않는 한, 해당하는 경우 배포, StatefulSet 또는 ReplicaSet의 pod 템플릿에서 토폴로지 키를 구성해야 합니다.

예를 들어 토폴로지 라벨에서 키를 "topology.examplepetstore.com/zone"로 정의했다고 가정해 보겠습니다. PodTemplate에서 키를 topologySpreadConstraints.topologyKey 필드의 값으로 지정합니다. 이를 통해 Kubernetes 스케줄러는 토폴로지 도메인에 포드를 배포하여 고가용성을 보장하고 장애 발생 시 단일 영역에 과도하게 집중되는 것을 방지할 수 있습니다.

topologySpreadConstraints 구성에 관한 자세한 내용은 Kubernetes 문서의 Pod 토폴로지 확산 제약 조건을 참고하세요.

파일 백업

관리자 클러스터 kubeconfig 파일을 백업하는 것이 좋습니다. 즉, kubeconfig 파일을 관리자 워크스테이션에서 다른 위치로 복사합니다. 그러면 관리자 워크스테이션에 대한 액세스 권한을 상실하거나 관리자 워크스테이션의 kubeconfig 파일이 실수로 삭제된 경우에도 관리자 클러스터에 액세스할 수 있습니다.

또한 관리자 클러스터의 비공개 SSH 키를 백업하는 것이 좋습니다. 그러면 관리자 클러스터에 대한 액세스 권한을 상실한 경우에도 SSH를 사용하여 관리자 클러스터 노드에 연결할 수 있습니다. 이렇게 하면 관리자 클러스터 연결과 관련된 문제를 해결하고 조사할 수 있습니다.

관리자 클러스터에서 admin-cluster-ssh-key라는 파일로 SSH 키를 추출합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n kube-system sshkeys \
    -o jsonpath='{.data.vsphere_tmp}' | base64 -d > admin-cluster-ssh-key

이제 admin-cluster-ssh-key를 원하는 다른 위치에 백업할 수 있습니다.

문제 해결

클러스터 생성 및 업그레이드 문제 해결을 참조하세요.

다음 단계

토폴로지 도메인에 사용할 사용자 클러스터 만들기