이 문서에서는 맞춤 단계로 출시 시퀀싱을 사용하는 Google Kubernetes Engine (GKE) 클러스터 업그레이드를 관리하는 방법을 보여줍니다. Fleet으로 구성된 클러스터 그룹과 선택적으로 이러한 Fleet의 클러스터 하위 집합을 사용하여 출시 시퀀스를 만듭니다. 한 그룹에서 클러스터 업그레이드가 완료된 후 원하는 소크 테스트 시간 (최대 30일)을 선택할 수 있습니다. Autopilot 및 Standard 클러스터 모두를 포함할 수 있습니다. 이 기능의 작동 방식에 대한 자세한 내용은 맞춤 단계가 있는 출시 시퀀스 정보를 참고하세요.
여러 Fleet에 걸쳐 출시를 관리하는 경우 전용 프로젝트를 사용하여 RolloutSequence 객체를 호스팅하는 것이 좋습니다. 이 프로젝트는 시퀀스 전반에서 출시의 상위 요소이자 코디네이터 역할을 합니다. 이 프로젝트는 일반적으로 시퀀스에 포함되지 않습니다. 즉, 이 프로젝트에는 시퀀스에 포함된 함대나 클러스터가 포함되지 않습니다.
시작하기 전에
-
Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다.
gcloud init외부 ID 프로바이더(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
- 기존 Autopilot 또는 Standard 클러스터가 있는지 확인합니다. 새 클러스터를 만들려면 Autopilot 클러스터 만들기를 참조하세요.
(선택사항)
RolloutSequence구성을 호스팅할 전용 Google Cloud 프로젝트가 아직 없는 경우 Google Cloud 콘솔이나 다른 방법을 사용하여 만듭니다.차량 관리 시스템에 필요한 API를 사용 설정했는지 확인합니다. 모든 유형의 출시 시퀀스를 만들려면 Fleet 호스트 프로젝트에서 이러한 API를 사용 설정해야 합니다. 출시 시퀀스 호스트 프로젝트에서
gkehub.googleapis.comAPI를 사용 설정합니다.
필요한 역할
프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
출시 시퀀스를 만들거나 수정하려면 출시 시퀀스의 각 Fleet 호스트 프로젝트와 출시 시퀀스 호스트 프로젝트에 Fleet 편집자 IAM 역할 (roles/gkehub.editor)이 있어야 합니다. 이 역할은 다음 권한을 제공합니다.
gkehub.rolloutsequences.creategkehub.rolloutsequences.getgkehub.rolloutsequences.listgkehub.rolloutsequences.updategkehub.rolloutsequences.deletegkehub.fleet.get
이러한 권한을 사용하면 RolloutSequence 객체를 만들고, 액세스하고, 수정할 수 있으며, 출시 시퀀스에서 플릿을 사용할 수 있습니다.
클러스터를 Fleet에 등록하거나 등록 취소하려면 다음 권한이 모두 필요합니다.
- Fleet 호스트 프로젝트의 클러스터 등록 권한
- 등록할 모든 GKE 클러스터에 대한 클러스터 관리자 권한
- 다른 프로젝트의 Fleet에 등록될 모든 GKE 클러스터에 대한 프로젝트 간 클러스터 등록 권한
다양한 작업에 필요한 최소 권한 IAM 역할에 대한 자세한 내용은 Gemini 지원을 통해 사전 정의된 역할 추천 받기를 참고하세요.
출시 시퀀스 구성
출시 시퀀스를 만들려면 클러스터를 Fleet 그룹으로 구성해야 합니다. Kubernetes 라벨을 사용하여 Fleet 내의 특정 클러스터 하위 집합을 타겟팅할 수 있는 세부적인 단계를 만들 수도 있습니다. 클러스터 구성 방법에 대한 안내는 지역 은행 예시를 참고하세요. 클러스터를 그룹으로 정리하고 원하는 경우 라벨을 지정한 후 단계의 순서가 지정된 목록과 각 그룹의 적응 시간을 정의하여 출시 시퀀스를 만듭니다.
클러스터를 Fleet으로 구성
출시 시퀀스에서는 모든 클러스터를 동일한 출시 채널에 등록하는 것이 좋습니다. 클러스터가 동일한 채널에 등록되지 않은 경우 GKE는 시퀀스에서 가장 보수적인 채널의 버전을 선택합니다. 예를 들어 클러스터가 안정화 버전 채널과 일반 채널 모두에 등록된 경우 GKE는 안정화 버전 채널의 버전을 선택합니다. 또한 모든 클러스터가 동일한 자동 업그레이드 대상 버전을 사용할 수 있도록 동일한 부 버전을 실행하는 것이 좋습니다.
클러스터를 이미 Fleet으로 구성했다면 다음 단계를 건너뛰고 클러스터 하위 집합 만들기 섹션으로 진행하면 됩니다.
- 클러스터를 Fleet으로 그룹화합니다. 테스트, 스테이징, 프로덕션과 같은 배포 환경별로 클러스터를 구성할 수 있습니다 (권장).
- 선택한 그룹화에 따라 Fleet에 각 클러스터를 등록합니다.
클러스터 하위 집합 만들기 (선택사항)
출시 시퀀스의 단계를 특정 클러스터를 타겟팅하도록 하려면 해당 클러스터에 라벨을 지정해야 합니다.
예를 들어 전체 출시 전에 소수의 클러스터에서 새 버전을 테스트하려면 해당 클러스터에 canary 라벨을 적용하면 됩니다. Google Cloud CLI를 사용하여 값 true이 있는 canary 라벨을 클러스터에 추가하려면 다음 명령어를 실행합니다.
gcloud container clusters update CLUSTER_NAME \
--location=CLUSTER_LOCATION\
--update-labels=canary=true
다음을 바꿉니다.
CLUSTER_NAME: 기존 클러스터의 이름입니다.CLUSTER_LOCATION: 클러스터의 Compute Engine 리전 또는 영역
--update-labels=canary=true 플래그는 GKE에 클러스터에 canary 라벨을 적용하도록 지시합니다 .
클러스터에 라벨을 추가하는 방법에 대한 자세한 내용은 기존 클러스터의 라벨 추가 또는 업데이트를 참고하세요.
맞춤 단계로 출시 시퀀스 만들기
출시 시퀀스는 단계를 사용하여 업그레이드 순서를 정의합니다. 롤아웃 시퀀스를 만들려면 먼저 단계를 정의하는 YAML 파일을 만든 다음 RolloutSequence을 만들어야 합니다.
시퀀스에서 모든 클러스터를 캡처하려면 각 Fleet에 포괄적인 단계 (라벨 선택기가 없는 단계)가 포함되어야 합니다. 이 포괄적 단계에서는 GKE가 이전 단계에서 선택하지 않은 나머지 클러스터를 모두 포착합니다. 하나의 RolloutSequence 내에서 여러 단계에 단일 클러스터를 할당하는 경우 충돌을 해결하기 위해 GKE는 가장 이른 단계에만 클러스터를 암시적으로 할당합니다.
다음 예시 구성은 3개의 단계를 만듭니다.
- 첫 번째 단계는
devFleet의 모든 클러스터를 타겟팅합니다. 업그레이드가 완료되면 7일 (604800초)의 적응 시간이 있습니다. - 두 번째 단계에서는
canary=true라벨이 있는prodFleet의 클러스터를 타겟팅합니다. 업그레이드가 완료된 후 7일의 소크 시간이 있습니다. - 세 번째 단계는
prodFleet의 나머지 클러스터를 타겟팅합니다. 업그레이드가 완료된 후 7일의 소크 시간이 있습니다.
다음 매니페스트를
rollout-sequence.yaml로 저장합니다.- stage: fleet-projects: - projects/dev soak-duration: 604800s - stage: fleet-projects: - projects/prod soak-duration: 604800s label-selector: resource.labels.canary=='true' - stage: fleet-projects: - projects/prod soak-duration: 604800s다음에 유의하세요.
stage: Fleet 또는 Fleet 내 클러스터의 하위 집합을 포함합니다. 이전 단계의 클러스터는 시퀀스가 다음 단계로 진행되기 전에 완전히 업그레이드되고 소킹되어야 합니다. 하지만 업그레이드 프로세스가 시작된 후 30일이 지나도 클러스터 업그레이드가 완료되지 않으면 GKE에서 적응 기간을 시작합니다.fleet-projects: 이 단계에서 클러스터를 선택할 Fleet 목록입니다. 단계별로 최대 하나의 플릿을 참조할 수 있습니다. Fleet은 Fleet이 호스팅되는 프로젝트로 식별됩니다. Fleet에 프로젝트 간 멤버십이 포함된 경우 이 프로젝트는 클러스터가 있는 프로젝트와 다른 프로젝트일 수 있습니다. Fleet 프로젝트를 지정하는 형식은projects/PROJECT_ID입니다.label-selector(선택사항): 지정된 플릿에서 클러스터의 하위 집합을 선택합니다. 이 필드는 Common Expression Language (CEL) 문법을 사용하며resource.labels로 시작해야 합니다.soak-duration: 이전 단계에서 모든 클러스터를 업그레이드한 후 다음 단계로 진행하기 전에 대기할 시간입니다. 초 단위로 표현됩니다.
rollout-sequence.yaml매니페스트에 정의된 출시 시퀀스를 만들려면 다음 명령어를 실행합니다.gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \ --display-name=DISPLAY_NAME \ --stage-config=rollout-sequence.yaml다음을 바꿉니다.
ROLLOUT_SEQUENCE_NAME: RFC-1034 사양을 준수하는 변경 불가능한 식별자입니다(예:test-rollout-sequence).DISPLAY_NAME: 출시 시퀀스를 나타내는 사람이 읽을 수 있는 문자열입니다.
출시 상태 확인
출시 시퀀스를 구성하면 시스템에서 업그레이드를 관리하는 Rollout 객체를 자동으로 만듭니다. Google Cloud CLI 명령어를 사용하여 이러한 객체의 진행 상황을 관찰하고 추적할 수 있습니다.
출시 나열
출시 시퀀스 호스트 프로젝트에서 모든 활성 및 이전 출시를 나열하려면 다음 명령어를 실행합니다.
gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID
HOST_PROJECT_ID를 출시 시퀀스 호스트 프로젝트의 ID로 바꿉니다.
출시 시퀀스가 호스팅된 프로젝트에 이미 있는 경우 --project=HOST_PROJECT_ID 플래그를 생략할 수 있습니다.
출력은 다음과 비슷합니다.
NAME STATE CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd COMPLETED 2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst COMPLETED 2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu COMPLETED 2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct RUNNING 2025-10-23T16:41:33
위 출력에서 kcp가 포함된 출시 이름은 컨트롤 플레인 업그레이드를 나타내고 node가 포함된 이름은 노드 업그레이드를 나타냅니다. kcp 또는 node 뒤에 오는 출시 이름의 세그먼트는 GKE 버전에서 파생됩니다.
출시 설명
타겟 버전, 상태, 업그레이드된 클러스터 등 특정 출시에 관한 자세한 정보를 가져오려면 이전 명령어에서 가져온 출시 ID와 함께 describe 명령어를 사용하세요.
gcloud beta container fleet rollouts describe ROLLOUT_ID \
--project=HOST_PROJECT_ID
다음을 바꿉니다.
ROLLOUT_ID: 출시를 나열할 때 획득한 출시 ID입니다.HOST_PROJECT_ID: 출시 시퀀스가 호스팅되는 프로젝트 ID입니다.
예를 들면 다음과 같습니다.
gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
--project=my-hostfleet
출력은 다음과 비슷합니다.
createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
projects/dev-project-id/locations/us-central1/memberships/c-1:
lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
targets:
- cluster: projects/dev-project-id/locations/us-central1/clusters/c-1
operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
state: SUCCEEDED
stageAssignment: 1
projects/dev-project-id/locations/us-central1/memberships/c-2:
lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
targets:
- cluster: projects/dev-project-id/locations/us-central1/clusters/c-2
operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
state: SUCCEEDED
stageAssignment: 1
projects/prod-project-id/locations/us-central1/memberships/c-1:
lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
targets:
- cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
state: SUCCEEDED
stageAssignment: 2
projects/prod-project-id/locations/us-central1/memberships/c-2:
lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
targets:
- cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
state: SUCCEEDED
stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
desiredVersion: 1.32.4-gke.1106006
type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
endTime: '2025-05-26T12:22:28.828506491Z'
stageNumber: 1
startTime: '2025-05-26T11:48:28.772658427Z'
soakDuration: 600s
- state: COMPLETED
endTime: '2025-05-26T13:06:20.026390832Z'
stageNumber: 2
startTime: '2025-05-26T12:32:38.419372153Z'
soakDuration: 600s
출시의 상태 정보
출시를 설명하면 출력의 stages 및 membershipStates 필드에 각 단계와 해당 단계 내 클러스터의 진행 상태가 각각 표시됩니다.
다음 표에는 단계의 잠재적 상태가 나열되어 있습니다.
| 상태 | 설명 |
|---|---|
PENDING |
이 단계의 업그레이드는 아직 시작되지 않았습니다. |
RUNNING |
이 단계의 업그레이드가 진행 중입니다. 단계의 클러스터에 유지보수 기간을 구성한 경우 GKE는 기간이 열릴 때까지 기다린 후 클러스터를 업그레이드합니다. |
SOAKING |
이 단계의 모든 클러스터는 업그레이드를 완료했으며 단계가 구성된 소킹 기간에 있습니다. |
FORCED_SOAKING |
업그레이드에 최대 업그레이드 시간 (30일)이 초과되어 GKE가 강제로 적응 단계를 시작했습니다. 업그레이드는 나머지 클러스터에서 계속됩니다. |
COMPLETED |
단계의 소킹이 완료되고 출시가 다음 단계로 진행됩니다. |
다음 표에는 시퀀스 내 클러스터의 가능한 상태가 나열되어 있습니다.
| 상태 | 설명 |
|---|---|
PENDING |
이 클러스터에서 업그레이드가 대기 중입니다. |
INELIGIBLE |
이 클러스터는 버전 불일치로 인해 업그레이드할 수 없습니다. 부적격 이유는 출력에 제공됩니다. |
RUNNING |
이 클러스터에서 업그레이드가 진행 중입니다. |
SUCCEEDED |
이 클러스터에서 업그레이드가 완료되었습니다. |
FAILED |
이 클러스터에서 업그레이드에 실패했습니다. 실패한 타겟은 단계가 활성 상태 (RUNNING 또는 FORCED_SOAKING 상태)인 동안 무기한으로 재시도됩니다. |
출시 시퀀스 관리
다음 섹션에서 설명하는 여러 가지 방법의 출시 시퀀싱을 사용하여 자동 클러스터 업그레이드를 제어할 수 있습니다.
출시 시퀀스 나열
호스트 프로젝트의 모든 출시 시퀀스를 나열하려면 다음 명령어를 실행합니다.
gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID
HOST_PROJECT_ID를 출시 시퀀스 호스트 프로젝트의 ID로 바꿉니다.
출시 시퀀스 설명
특정 출시 시퀀스의 세부정보를 보려면 다음 명령어를 실행합니다.
gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
--project=HOST_PROJECT_ID
다음을 바꿉니다.
ROLLOUT_SEQUENCE_NAME: 출시 시퀀스의 이름입니다.HOST_PROJECT_ID: 출시 시퀀스 호스트 프로젝트의 ID입니다.
출력은 다음과 비슷합니다.
createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
labelSelector: resource.labels.canary=='true'
fleetProjects:
- projects/FLEET_PROJECT_ID
soakDuration: 600s
- fleetProjects:
- projects/FLEET_PROJECT_ID
soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'
출시 시퀀스 수정
시퀀스를 정의한 YAML 구성 파일을 수정하여 기존 출시 시퀀스를 수정할 수 있습니다. 예를 들어 단계의 흡수 시간을 업데이트하거나 단계를 업데이트하여 업그레이드 순서를 변경할 수 있습니다. 파일을 수정한 후 변경사항을 적용합니다.
예를 들어 rollout-sequence.yaml이라는 파일에 원래 출시 시퀀스를 정의한 경우 필요에 따라 파일을 수정합니다. 그런 다음 다음 명령어를 실행합니다.
gcloud beta container fleet rolloutsequences update test-rollout-sequence \
--display-name="My Updated Rollout Sequence" \
--stage-config=rollout-sequence.yaml
출시 시퀀스 삭제
출시 시퀀스를 삭제하려면 다음 명령어를 실행합니다.
gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
--project=HOST_PROJECT_ID
다음을 바꿉니다.
ROLLOUT_SEQUENCE_NAME을 출시 시퀀스 이름으로 바꿉니다.HOST_PROJECT_ID를 출시 시퀀스 호스트 프로젝트의 ID로 바꿉니다.
출시 시퀀스를 삭제하면 해당 시퀀스의 진행 중인 출시가 취소됩니다. 시퀀스에 포함된 클러스터는 등록된 출시 채널의 기본 자동 업그레이드 동작으로 되돌아갑니다.
기존 출시 시퀀스를 마이그레이션하여 맞춤 단계를 사용
일반적으로 사용 가능한 출시 시퀀싱의 버전을 사용하는 경우 기존 플릿을 참조하는 새 RolloutSequence를 만들어 커스텀 단계를 사용하는 시퀀스로 이전할 수 있습니다.
시퀀스를 이전하기 전에 현재 출시 시퀀스 구성의 사본을 만드는 것이 좋습니다.
출시 시퀀스를 이전하려면 다음 단계를 완료하세요.
- 출시 시퀀스를 호스팅할 전용 Google Cloud 프로젝트를 만듭니다. 이 프로젝트는 일반적으로 시퀀스에 포함되지 않습니다. 즉, 시퀀스에 포함된 함대나 클러스터가 프로젝트에 포함되지 않습니다.
- 롤아웃 시퀀스에 Fleet 내의 특정 클러스터를 포함하려면 해당 클러스터에 라벨을 추가하세요. 이 단계는 선택사항입니다.
맞춤 단계로 출시 시퀀스 만들기의 안내를 따릅니다.
예를 들어
rollout-sequence-migrate.yaml이라는 이름의 다음 매니페스트는 이전 출시 시퀀스의 기존 플릿을 참조합니다. 이 매니페스트는prod차량의canary단계를 포함한 세 단계를 설명합니다.- stage: fleet-projects: - projects/dev soak-duration: 604800s - stage: fleet-projects: - projects/prod soak-duration: 604800s label-selector: canary=true - stage: fleet-projects: - projects/prod soak-duration: 604800s
Fleet의 새 RolloutSequence를 정의하면 GKE는 새 순서에 따라 Fleet 업그레이드를 시작하고 이전 구성을 삭제합니다.
맞춤 단계가 있는 출시 시퀀스를 이전 출시 시퀀스로 이전
이 섹션에서는 맞춤 단계가 있는 출시 순서 지정에서 일반 출시 버전의 플릿 기반 순서 지정 모델로 되돌리는 방법을 설명합니다. 이 프로세스에는 새 RolloutSequence를 삭제하고 원래 함대 기반 구성을 복원하는 작업이 포함됩니다.
이전 중에 순서가 잘못된 업그레이드 방지
시퀀스를 재구성하는 동안 의도치 않은 업그레이드나 순서가 잘못된 업그레이드를 방지하려면 프로덕션 클러스터에 유지보수 제외를 적용하세요. 이 단계에서는 해당 클러스터의 모든 자동 업그레이드가 일시적으로 중지됩니다. 예를 들어 프로덕션 클러스터에서 no upgrades 유형의 유지보수 제외를 구성할 수 있습니다.
출시 시퀀스 삭제
클러스터를 관리하는 RolloutSequence 객체를 삭제합니다. 이렇게 삭제하면 맞춤 단계 기능이 사용 중지됩니다.
RolloutSequence를 삭제하려면 다음 명령어를 실행합니다.
gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME
ROLLOUT_SEQUENCE_NAME을 출시 시퀀스의 이름으로 바꿉니다.
이전 출시 순서 구성 복원 (맞춤 단계 제외)
RolloutSequence를 삭제한 후 원래의 Fleet 기반 구성을 복원할 수 있습니다. 이 프로세스에는 시퀀스의 각 차량에 대한 upstreamFleet 링크와 소킹 시간을 비롯한 원래 매개변수로 clusterupgrade 기능을 다시 만드는 작업이 포함됩니다. 자세한 내용은 출시 시퀀스 만들기를 참고하세요.
유지보수 제외 삭제
원래 함대 기반 출시 순서 구성으로 복원한 후 이 섹션의 첫 번째 단계에서 적용한 유지관리 제외를 삭제합니다. GKE는 복원된 플릿 기반 시퀀스에 따라 자동 업그레이드를 재개합니다.
다음 단계
- 출시 시퀀싱을 사용한 클러스터 업그레이드에 대해 자세히 알아보세요.