클러스터 및 노드 풀 라벨 만들기 및 관리

이 페이지에서는 Google Kubernetes Engine(GKE)의 클러스터 라벨과 노드 풀 라벨을 간략하게 설명합니다.

GKE 클러스터 및 노드 풀 라벨과 Kubernetes 라벨

GKE 클러스터 및 노드 풀 라벨은 Kubernetes의 라벨과 다릅니다. 두 라벨 지정 시스템은 독립적으로 작동하며 라벨을 상속하거나 공유하지 않습니다.

GKE 클러스터 및 노드 풀 라벨은 사용량 및 결제 정보를 추적하는 데 사용할 수 있는 리소스에 연결된 임의 메타데이터입니다.

이와는 별도로 Kubernetes에서 시스템은 클러스터 구성요소 및 리소스(예: 포드 및 노드)를 서로 연결하고 리소스 수명 주기를 관리하기 위해 내부적으로 라벨을 사용합니다. Kubernetes API를 사용하여 Kubernetes 라벨을 수정할 수 있습니다. GKE API를 사용하여 클러스터 만들기 또는 클러스터 업데이트를 통해 노드에서 Kubernetes 라벨을 수정할 수도 있습니다.

클러스터 라벨이란 무엇인가요?

클러스터 라벨은 Google Cloud 클러스터에 할당할 수 있는 키-값 쌍입니다. 이러한 리소스를 구성하고 필요한 세부사항으로 규모에 맞게 비용을 관리하는 데 도움이 됩니다. 각 리소스에 라벨을 연결한 후 이 라벨을 기준으로 리소스를 필터링할 수 있습니다. 라벨에 대한 정보는 청구 요금을 라벨별로 분류할 수 있는 결제 시스템으로 전달됩니다. 기본 제공되는 결제 보고서를 통해 리소스 라벨별로 비용을 필터링하고 그룹화할 수 있습니다. 라벨을 사용하여 결제 데이터 내보내기를 쿼리할 수도 있습니다.

클러스터 라벨 요구사항

리소스에 적용된 클러스터 라벨은 다음 요구사항을 충족해야 합니다.

각 리소스는 최대 64개의 클러스터 라벨을 가질 수 있습니다.
각 클러스터 라벨은 키-값 쌍이어야 합니다.
키는 비워 둘 수 없으며 최소 길이는 1자이고 최대 길이는 63자입니다. 값은 비워 둘 수 있으며 최대 길이는 63자(영문 기준)입니다.
키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다. 키는 소문자나 국제 문자로 시작해야 합니다.
클러스터 라벨의 키 부분은 단일 리소스에서 고유해야 합니다. 그러나 여러 리소스에 같은 키를 사용할 수 있습니다.

이러한 한도는 각 클러스터 라벨의 키와 값 및 클러스터 라벨이 있는 개별 Google Cloud 리소스에 적용됩니다. 한 프로젝트의 모든 리소스에 적용할 수 있는 클러스터 라벨 수에는 제한이 없습니다.

클러스터 라벨의 일반적인 사용 사례

다음은 클러스터 라벨의 몇 가지 일반적인 사용 사례입니다.

팀 또는 비용 센터 클러스터 라벨: 팀 또는 비용 센터 기준의 라벨을 추가하여 team:research 및 team:analytics와 같은 여러 팀에서 소유한 클러스터를 구별할 수 있습니다. 비용 계산이나 예산 책정에 이 유형의 라벨을 사용할 수 있습니다.
구성요소 클러스터 라벨: 예를 들어 component:redis, component:frontend, component:ingest, component:dashboard입니다.
환경 또는 단계 클러스터 라벨: 예를 들어 environment:production 및 environment:test입니다.
상태 클러스터 라벨: 예를 들어 state:active, state:readytodelete, state:archive입니다.
소유권 클러스터 라벨: 작업을 담당하는 팀을 식별하는 데 사용됩니다(예: team:shopping-cart).

결제 분류: 노드 풀 라벨을 사용하여 청구 금액을 노드 풀별로 분류합니다. 자세한 내용은 클러스터 비용의 상세 분석 보기를 참조하세요.

모든 API 호출의 타임스탬프 또는 개별 값과 같은 다수의 고유 라벨을 만들지 않는 것이 좋습니다. 이 접근 방식의 문제는 값이 자주 변경되거나 카탈로그를 복잡하게 하는 키로 인해 리소스를 효과적으로 필터링하고 보고하기 어렵다는 것입니다.

라벨 및 태그

라벨은 리소스에 대해 쿼리 가능한 주석으로 사용될 수 있지만 정책에 조건을 설정하는 데는 사용할 수 없습니다. 태그를 사용하면 정책을 세밀하게 제어하여 리소스에 특정 태그가 있는지 여부에 따라 정책을 조건부로 허용하거나 거부할 수 있습니다. 자세한 내용은 태그 개요를 참조하세요.

라벨 자동 적용

GKE는 자동으로 클러스터 리소스에 라벨을 여러 개 적용합니다.

예를 들어 GKE는 Compute Engine 인스턴스, 영구 디스크, 가속기(TPU)에 라벨을 적용합니다.

다음 표에서는 GKE가 리소스에 자동으로 적용하는 라벨을 보여줍니다.

라벨	적용된 리소스
`goog-gke-node`	GKE 노드의 기본이 되는 Compute Engine VM 인스턴스입니다.
`goog-gke-volume`	GKE 노드의 기본이 되는 VM 인스턴스에 연결된 Compute Engine 영구 디스크입니다.
`goog-gke-tpu`	GKE의 Cloud TPU입니다.
`goog-k8s-cluster-name`	GKE 노드의 기반이 되는 VM 인스턴스에 연결된 Compute Engine VM 인스턴스 및 영구 디스크입니다.
`goog-k8s-cluster-location`	GKE 노드의 기반이 되는 VM 인스턴스에 연결된 Compute Engine VM 인스턴스 및 영구 디스크입니다.
`goog-k8s-node-pool-name`	GKE 노드의 기반이 되는 Compute Engine VM 인스턴스와 부팅 디스크입니다.
`goog-fleet-project`	Fleet에 클러스터가 등록된 경우 Compute Engine VM 인스턴스 및 GKE 노드를 기반으로 하는 VM 인스턴스에 연결된 영구 디스크입니다.

예약된 라벨은 수정하거나 삭제하지 마세요. 예약된 라벨에 대한 변경사항은 자동으로 조정됩니다.

라벨 전파

GKE에서는 클러스터 및 Standard 모드 노드 풀에 라벨을 적용할 수 있습니다. 클러스터에 라벨을 지정하면 라벨이 노드, 인스턴스, 영구 디스크와 같은 클러스터의 모든 개별 리소스에 전파됩니다. 노드 풀에 라벨을 지정하면 라벨이 인스턴스 및 영구 디스크와 같은 노드 풀의 모든 개별 리소스에 전파됩니다. Standard 클러스터에서 라벨 키는 동일하지만 값이 다른 경우와 같이 클러스터 라벨이 노드 풀 라벨과 충돌하는 경우 노드 풀 라벨이 클러스터 라벨을 재정의합니다.

클러스터 또는 노드 풀에 적용하는 모든 라벨은 시간별로 실행되는 백그라운드 프로세스를 통해 전파됩니다. 특정 클러스터와 연결된 모든 리소스에 라벨이 표시되는 데 최대 1시간이 걸릴 수 있습니다. 또한 라벨은 Compute Engine 인스턴스에 연결된 Persistent Disk와 Compute Engine 인스턴스에만 전파됩니다. 워크로드, 전달 규칙, IP 주소, 연결되지 않은 Persistent Disk와 같은 다른 리소스에는 라벨이 지정되지 않습니다.

Standard 클러스터의 경우 클러스터 및 노드 풀 라벨이 Compute Engine 리소스에 적용되면 GKE에서 변경사항을 조정하지 않고 리소스 라벨을 수동으로 변경할 수 있습니다. Autopilot 클러스터에서는 GKE에서 노드를 관리하므로 Compute Engine 리소스의 라벨을 수동으로 수정할 수 없습니다. 하지만 GKE를 통해 이러한 라벨을 관리하는 것이 좋습니다. 해당 Compute Engine 리소스의 기존 라벨은 자동으로 적용되는 라벨과 충돌하지 않는 한 GKE에서 삭제되지 않습니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

Google Kubernetes Engine API를 사용 설정합니다.

Google Kubernetes Engine API 사용 설정

이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

API 요청의 라벨 디지털 지문 가져오기

Google Cloud 콘솔 또는 gcloud CLI를 사용하는 경우 이 단계를 건너뛸 수 있습니다.

GKE API를 사용하여 클러스터 라벨을 업데이트하거나 추가할 때는 다른 요청과 충돌하지 않도록 요청과 함께 최신 클러스터 라벨 디지털 지문을 제공해야 합니다.

최신 클러스터 라벨 디지털 지문을 가져오려면 적합한 클러스터에 대해 GET 요청을 실행합니다. 예를 들면 다음과 같습니다.

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

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

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

이 출력에서 labelFingerprint 속성은 클러스터 라벨 지문입니다.

라벨이 있는 클러스터 만들기

gcloud CLI, Google Cloud 콘솔, GKE API 또는 Terraform을 사용하여 라벨이 있는 Autopilot 및 표준 클러스터를 만들 수 있습니다.

gcloud

다음 명령어를 실행하여 라벨이 있는 Autopilot 클러스터를 만듭니다.

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

또는 다음 명령어를 실행하여 라벨이 있는 표준 클러스터를 만듭니다.

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
KEY: 라벨의 키-값 쌍에 대한 키입니다.
VALUE: 라벨의 키-값 쌍에 대한 값입니다.

콘솔

클러스터를 만들 때 라벨을 추가하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
만들기를 클릭합니다.
Autopilot 또는 Standard에서 구성을 클릭합니다.
클러스터를 구성합니다.
탐색창의 클러스터에서 메타데이터를 클릭합니다.
라벨 추가를 클릭합니다.
라벨을 추가합니다.
만들기를 클릭합니다.

API

클러스터를 만들 때 라벨을 포함하려면 projects.zones.clusters.create에 제공하는 cluster 객체 내에 resourceLabels 객체를 지정합니다.

Terraform

Terraform을 사용하여 라벨이 있는 Autopilot 클러스터를 만들려면 다음 예시를 참조하세요.

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Terraform을 사용하여 라벨이 있는 Standard 클러스터를 만들려면 다음 예시를 참조하세요.

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-west1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Terraform 사용에 대한 자세한 내용은 GKE에 대한 Terraform 지원을 참조하세요.

기존 클러스터에 대해 라벨 추가 또는 업데이트

gcloud CLI, Google Cloud 콘솔 또는 GKE API를 사용하여 기존 Autopilot 및 Standard 클러스터의 라벨을 추가하거나 업데이트할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
COMPUTE_REGION: 새 클러스터의 Compute Engine 리전입니다. 영역 표준 클러스터의 경우 --zone=COMPUTE_ZONE을 사용합니다.
KEY: 라벨의 키-값 쌍에 대한 키입니다.
VALUE: 라벨의 키-값 쌍에 대한 값입니다.

라벨을 업데이트하면 클러스터의 기존 라벨을 덮어씁니다. 클러스터에 보존하려는 기존 라벨이 있으면 추가하려는 새 라벨과 함께 이러한 라벨을 포함해야 합니다.

콘솔

라벨을 추가하거나 업데이트하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 세부정보 페이지에서 수정할 클러스터의 체크박스를 하나 이상 선택합니다.
라벨을 클릭합니다.
라벨을 추가하거나 업데이트합니다.
저장을 클릭합니다.

API

적용할 최신 지문과 전체 라벨 목록을 사용하여 클러스터의 resourceLabels 메서드에 POST 요청을 수행합니다.

메타데이터 및 태그와 마찬가지로 클러스터에 보존하려는 기존 라벨이 있으면 추가하려는 새 라벨과 함께 요청에 이러한 라벨을 포함해야 합니다.

예를 들어 다음 스니펫은 resourceLabels 메서드에 대해 요청을 실행합니다.

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

클러스터 라벨 삭제

gcloud CLI, Google Cloud 콘솔, GKE API를 사용하여 Autopilot 및 Standard 클러스터에서 라벨을 삭제할 수 있습니다.

gcloud

--remove-labels 플래그와 함께 update 명령어를 실행합니다.

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
KEYS: 삭제하려는 라벨의 쉼표로 구분된 키 목록입니다.

콘솔

라벨을 삭제하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정할 클러스터의 체크박스를 하나 이상 선택합니다.
라벨을 클릭합니다.
삭제할 라벨의 값 필드 옆에 있는 항목 삭제를 클릭합니다.
저장을 클릭합니다.

API

적절한 클러스터에 대해 resourceLabels 메서드에 POST 요청을 수행합니다. 최신 labelsFingerprint 및 비어 있는 라벨 목록을 제공하여 모든 라벨을 삭제하거나 유지하려는 라벨 목록을 제공하고, 삭제하려는 라벨은 생략합니다. 예를 들면 다음과 같습니다.

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

라벨이 있는 Standard 노드 풀 만들기

gcloud CLI, Google Cloud 콘솔 또는 GKE API를 사용하여 Standard 클러스터에 라벨이 있는 노드 풀을 만들 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

다음을 바꿉니다.

NODE_POOL_NAME: 노드 풀의 이름입니다.
CLUSTER_NAME: 클러스터의 이름입니다.
COMPUTE_REGION: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우 --zone=COMPUTE_ZONE을 사용합니다.
KEY: 라벨의 키-값 쌍에 대한 키입니다.
VALUE: 라벨의 키-값 쌍에 대한 값입니다.

API

노드 풀을 만들 때 라벨을 포함하려면 projects.zones.clusters.nodePools.create에 제공하는 노드 풀 객체 내에서 resourceLabels 객체를 지정합니다.

콘솔

새 노드 풀에 라벨을 추가하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 세부정보 페이지에서 수정하려는 클러스터 이름을 클릭합니다.
노드 풀 추가를 클릭합니다.
새 노드 풀을 구성합니다.
탐색창에서 메타데이터를 클릭합니다.
라벨 추가를 클릭합니다.
라벨을 추가합니다.
만들기를 클릭합니다.

기존 노드 풀의 라벨 추가 또는 업데이트

gcloud CLI, Google Cloud 콘솔, GKE API를 사용하여 기존 노드 풀에 대해 라벨을 추가하거나 업데이트할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

다음을 바꿉니다.

NODE_POOL_NAME: 노드 풀 이름
CLUSTER_NAME: 클러스터의 이름입니다.
COMPUTE_REGION: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우 --zone=COMPUTE_ZONE을 사용합니다.
KEY: 라벨의 키-값 쌍에 대한 키입니다.
VALUE: 라벨의 키-값 쌍에 대한 값입니다.

업데이트한 라벨이 노드 풀의 기존 라벨을 덮어씁니다. 노드 풀에 보존하려는 기존 라벨이 있으면 추가하려는 새 라벨과 함께 이러한 라벨을 포함해야 합니다.

API

노드 풀을 수정할 때 라벨을 포함하려면 projects.zones.clusters.nodePools.update에 제공하는 노드 풀 객체 내에서 resourceLabels 객체를 지정합니다.

콘솔

라벨을 추가하거나 업데이트하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 노드 풀이 포함된 클러스터의 이름을 클릭합니다.
노드 풀 섹션에서 수정하려는 노드 풀의 이름을 클릭합니다.
수정을 클릭합니다.
라벨 섹션에서 라벨을 추가하거나 업데이트합니다.
저장을 클릭합니다.

노드 풀 라벨 삭제

gcloud CLI, Google Cloud 콘솔, GKE API를 사용하여 노드 풀에서 라벨을 삭제할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

다음을 바꿉니다.

NODE_POOL_NAME: 노드 풀의 이름입니다.
CLUSTER_NAME: 클러스터의 이름입니다.
COMPUTE_REGION: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우 --zone=COMPUTE_ZONE을 사용합니다.
KEY: 라벨의 키-값 쌍에 대한 키입니다.
VALUE: 라벨의 키-값 쌍에 대한 값입니다.

업데이트한 라벨이 노드 풀의 기존 라벨을 덮어씁니다. 노드 풀에 보존하려는 기존 라벨이 있으면 삭제할 라벨을 제외해야 합니다. 모든 라벨을 삭제하려면 키-값 쌍 없이 --labels=을 사용합니다.

API

노드 풀을 수정할 때 라벨을 포함하려면 projects.zones.clusters.nodePools.update에 제공하는 노드 풀 객체 내에서 resourceLabels 객체를 지정합니다. 빈 라벨 목록을 제공하여 모든 라벨을 삭제하거나 유지할 라벨의 목록을 제공합니다. 삭제할 라벨을 생략합니다.

콘솔

노드 풀에서 라벨을 삭제하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 노드 풀이 포함된 클러스터의 이름을 클릭합니다.
노드 풀 섹션에서 수정하려는 노드 풀의 이름을 클릭합니다.
삭제할 라벨의 값 필드 옆에 있는 항목 삭제를 클릭합니다.
저장을 클릭합니다.

다음 단계

GKE 개요 읽기