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

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

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

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

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

시작하기 전에

절차 개요

gkectl을 사용하여 사용자 클러스터를 만드는 기본 단계는 다음과 같습니다.

  1. 사용자 클러스터 구성 파일 작성
    사용자 클러스터 구성 파일에서 새 클러스터의 세부정보를 지정합니다.
  2. IP 블록 파일 작성
    IP 블록 파일에서 게이트웨이, 넷마스크, 컨트롤 플레인 노드, 선택적으로 워커 노드의 IP 주소를 지정합니다.
  3. 사용자 클러스터 만들기
    gkectl create cluster를 실행하여 구성 파일에 지정된 대로 클러스터를 만듭니다.
  4. 사용자 클러스터 실행 여부 확인
    kubectl을 사용하여 클러스터 노드를 확인합니다.

이 절차를 마치면 실행 중인 사용자 클러스터가 준비되며 여기에 워크로드를 배포할 수 있습니다.

사용자 클러스터 구성 파일 작성

gkeadm을 사용하여 관리자 워크스테이션을 만든 경우 gkeadm은 사용자 클러스터 구성 파일의 템플릿을 생성했습니다.user-cluster.yaml 또한 gkeadm에는 일부 필드도 채워져 있습니다.

gkeadm을 사용하여 관리자 워크스테이션을 만들지 않은 경우 gkectl을 사용하여 사용자 클러스터 구성 파일의 템플릿을 생성할 수 있습니다.

사용자 클러스터 구성 파일의 템플릿을 생성하려면 다음 안내를 따르세요.

gkectl create-config cluster --config=OUTPUT_FILENAME --gke-on-prem-version=VERSION

다음을 바꿉니다.

OUTPUT_FILENAME: 생성된 템플릿에 대해 선택한 경로. 이 플래그를 생략하면 gkectl은 파일 이름을 user-cluster.yaml로 지정하고 현재 디렉터리에 넣습니다.

VERSION: 원하는 버전 번호. 예를 들면 gkectl create-config cluster --gke-on-prem-version=1.31.0-gke.889입니다.

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

name

name 필드를 사용자 클러스터용으로 선택한 이름으로 설정합니다.

gkeOnPremVersion

이 필드는 이미 채워져 있습니다. Google Distributed Cloud 버전을 지정합니다. 예를 들면 1.31.0-gke.889입니다.

enableAdvancedCluster

enableAdvancedCluster를 true로 설정합니다.

enableControlplaneV2

Controlplane V2는 모든 1.30 이상 사용자 클러스터에 필요합니다. enableControlplaneV2를 true로 설정합니다.

Controlplane V2가 사용 설정되면 사용자 클러스터의 컨트롤 플레인은 사용자 클러스터 자체의 노드에서 실행됩니다.

enableDataplaneV2

enableDataplaneV2를 true로 설정합니다.

vCenter

이 섹션 전체를 삭제합니다. 대신 vSphere 인프라 구성 파일에서 토폴로지 도메인별로 vCenter 정보를 구성합니다.

network

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

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

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

  • 워커 노드가 IP 주소를 가져오는 방법을 결정합니다. 옵션은 다음과 같습니다.

    • 미리 설정한 DHCP 서버에서 network.ipMode.type을 "dhcp"로 설정합니다.

    • IP 블록 파일에 제공한 고정 IP 주소 목록에서 가져옵니다. network.ipMode.type을 "static"로 설정합니다.

    사용자 클러스터의 제어 영역 노드는 사용자가 IP 블록 파일에 제공하는 고정 주소 목록에서 IP를 가져와야 합니다. 이는 워커 노드가 DHCP 서버에서 주소를 가져올 경우에도 마찬가지입니다.

    DHCP 서버를 사용하거나 고정 IP 주소 목록을 지정하는지에 관계없이 사용자 클러스터에 사용할 수 있도록 충분한 IP 주소가 필요합니다. 필요한 IP 주소 수에 대한 설명은 IP 주소 계획을 참조하세요.

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

loadBalancer

advancedNetworking

이그레스 NAT 게이트웨이를 만들려면 advancedNetworking을 true로 설정합니다.

multipleNetworkInterfaces

multipleNetworkInterfaces를 false로 설정합니다. 토폴로지 도메인에서는 포드용 다중 네트워크 인터페이스가 지원되지 않습니다.

storage

vSphere CSI 구성요소 배포를 사용 중지하려면 storage.vSphereCSIDisabled를 true로 설정하세요.

masterNode

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

  • 고가용성 (HA) 클러스터만 지원됩니다. replicas 필드를 3로 설정하여 클러스터에 제어 영역 노드가 3개 있다고 지정합니다.

  • 제어 영역 노드의 자동 크기 조절을 사용 설정하려면 autoResize.enabled를 true로 설정합니다.

  • 전체 masterNode.vsphere 섹션을 삭제합니다.

  • masterNode.topologyDomains 필드에 컨트롤 플레인 노드가 속할 토폴로지 도메인의 이름을 입력합니다.

nodePools

노드 풀은 구성이 모두 동일한 클러스터의 워커 노드 그룹입니다. 예를 들어 노드 풀마다 별도의 토폴로지 도메인을 설정할 수 있습니다. nodePools 섹션을 입력하여 노드 풀을 하나 이상 지정해야 합니다.

지정하는 각 노드 풀에 대해 다음을 실행합니다.

  • nodePools[i].topologyDomains 필드에 노드 풀을 배치할 토폴로지 도메인의 이름을 입력합니다.

  • nodePools[i].vsphere.tags를 제외하고 nodePools[i].vsphere 섹션의 모든 필드를 삭제합니다. 이 정보는 토폴로지 도메인별로 vSphere 인프라 구성 파일에 지정됩니다.

# advanced-cluster-change #

nodePools[i].osImageType을 ubuntu_cgroupv2 또는 ubuntu_containerd로 설정합니다.

노드 풀에 관한 일반적인 정보는 노드 풀 및 노드 풀 만들기 및 관리를 참고하세요.

antiAffinityGroups

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

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와 리전이 동일하지 않으면 클러스터 생성에 실패합니다.

gkeConnect

사용자 클러스터를 Google Cloud Fleet에 등록해야 합니다.

gkeConnect 섹션을 입력하여 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의 서비스 이름)을 중지합니다. 자세한 내용은 서비스 사용 중지를 참조하세요.

cloudAuditLogging

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

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

# advanced-cluster-change #

cloudAuditLogging.serviceAccountKeyPath를 stackdriver.serviceAccountKeyPath와 동일한 경로로 설정합니다.

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

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

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

preparedSecrets

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

작성된 구성 파일 예시

다음은 IP 블록 파일과 사용자 클러스터 구성 파일의 예시입니다.

user-ipblock.yaml

blocks:
  - netmask: 255.255.255.0
    gateway: 172.16.21.1
    ips:
    - ip: 172.16.21.2
      hostname: worker-vm-1
    - ip: 172.16.21.3
      hostname: worker-vm-2
    - ip: 172.16.21.4
      hostname: worker-vm-3
    - ip: 172.16.21.5
      hostname: worker-vm-4
  - netmask: 255.255.255.0
    gateway: 100.115.223.254
    ips:
    - ip: 100.115.222.205
      hostname: cp-1
      isControlPlane: true
    - ip: 100.115.222.206
      hostname: cp-2
      isControlPlane: true
    - ip: 100.115.222.207
      hostname: cp-3
      isControlPlane: true

user-cluster.yaml

cat user-cluster.yaml
apiVersion: v1
kind: UserCluster
name: "my-user-cluster"
gkeOnPremVersion: 1.31.0-gke.889
enableAdvancedCluster: true
enableControlplaneV2: true
enableDataplaneV2: true
network:
  ipMode:
    type: "static"
    ipBlockFilePath: "user-ipblock.yaml"
  serviceCIDR: 10.96.0.0/20
  podCIDR: 192.168.0.0/16
loadBalancer:
  vips:
    controlPlaneVIP: "100.115.222.200"
    ingressVIP: "172.16.21.30"
  kind: "ManualLB"
  manualLB:
    ingressHTTPNodePort: 32527
    ingressHTTPSNodePort: 30139
    controlPlaneNodePort: 30968
masterNode:
  cpus: 4
  memoryMB: 8192
  replicas: 3
nodePools:
- name: "worker-node-pool1"
  cpus: 4
  memoryMB: 8192
  replicas: 3
  topologyDomains:
  - "domain1"
antiAffinityGroups:
  enabled: false
gkeConnect:
  projectID: "my-project-123"
  location: "us-central1"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
autoRepair:
  enabled: true

앞의 예시에서 이해가 필요한 중요 부분은 다음과 같습니다.

  • nodePools.replicas 필드는 3으로 설정됩니다. 즉, "worker-node-pool"에는 워커 노드가 3개 있습니다. network.ipMode.type가 "static"로 설정되어 있으므로 모든 워커 노드는 고정 IP 주소를 사용합니다.

  • 컨트롤 플레인 노드와 워커 노드의 IP 주소는 IP 블록 파일에 지정됩니다. 워커 노드가 3개뿐인데도 IP 블록 파일은 워커 노드의 주소가 4개입니다. 추가 작업자 노드 IP 주소는 클러스터 업그레이드, 업데이트, 자동 복구 중에 필요합니다. 컨트롤 플레인 노드의 IP 주소에는isControlPlane: true 플래그가 있습니다.

  • 고급 클러스터, Controlplane V2, Dataplane V2가 사용 설정됩니다.

  • masterNode.replicas 필드가 3으로 설정되므로 클러스터는 고가용성 컨트롤 플레인을 갖게 됩니다.

  • 제어 영역 VIP는 제어 영역 노드와 동일한 VLAN에 있고 인그레스 VIP는 워커 노드와 동일한 VLAN에 있습니다.

IP 블록 파일 작성

IP 블록 파일의 템플릿을 사용자 클러스터 구성 파일의 network.ipMode.ipBlockFilePath 필드에 지정한 디렉터리의 파일에 복사합니다. 관리자 클러스터와 각 사용자 클러스터에 대해 별도의 IP 블록 파일을 만듭니다.

게이트웨이, 네트워크 마스크, 컨트롤 플레인 노드의 IP 주소를 IP 블록 파일에 추가합니다. 각 컨트롤 플레인 노드 IP 주소에 대해 이전 예와 같이 isControlPlane: true를 추가합니다. 고가용성 (HA) 사용자 클러스터가 필요한 경우 3개의 IP 주소를 지정합니다. 그렇지 않으면 IP 주소를 1개 지정합니다. 컨트롤 플레인 노드에 지정하는 IP 주소 수는 사용자 클러스터 구성 파일의 masterNode.replicas 필드에 있는 수와 일치해야 합니다.

network.ipMode.type이 "static"로 설정된 경우 워커 노드의 IP 주소를 IP 블록 파일에 추가합니다. 클러스터 업그레이드, 업데이트, 자동 복구 중에 사용할 IP 주소를 하나 더 지정해야 합니다.

IP 블록 파일의 각 게이트웨이 주소는 vSphere 인프라 구성 파일의 topologyDomains[i].network.gateway 필드에 지정된 주소와 일치해야 합니다. 자세한 내용은 토폴로지 도메인 예시를 참고하세요.

사용자 클러스터 만들기

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

gkectl create cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG

사용자 클러스터 kubeconfig 파일 찾기

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

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

kubectl config get-clusters --kubeconfig USER_CLUSTER_KUBECONFIG

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

NAME
my-user-cluster

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

사용자 클러스터 실행 여부 확인

사용자 클러스터 실행 여부 확인:

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG

USER_CLUSTER_KUBECONFIG를 사용자 클러스터 kubeconfig 파일 경로로 바꿉니다.

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

cp-vm-1       Ready    control-plane,master   18m
cp-vm-2       Ready    control-plane,master   18m
cp-vm-3       Ready    control-plane,master   18m
worker-vm-1   Ready                           6m7s
worker-vm-2   Ready                           6m6s
worker-vm-3   Ready                           6m14s

PodTemplate 구성

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

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

문제 해결

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

다음 단계