유지보수 기간 및 제외 구성

Autopilot Standard

유지보수 기간 및 유지보수 제외를 사용하여 Google Kubernetes Engine(GKE) 클러스터에서 자동 업그레이드와 같은 자동 클러스터 유지보수가 수행되거나 될 수 없는 시기를 제어하는 방법을 보여줍니다. 이러한 유지보수 정책을 구성하기 전에 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과 같은 오류를 방지할 수 있습니다.

유지보수 기간 구성

유지보수 기간을 구성하려면 유지보수 기간이 언제 시작하는지, 얼마나 지속되는지, 어떤 빈도로 반복되는지를 지정합니다. 예를 들어 매주 월요일부터 금요일까지 매일 4시간 동안 반복되는 유지보수 기간을 구성할 수 있습니다.

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 유지보수 기간을 구성할 수 있습니다.

유지보수 기간을 구성할 때의 고려사항

유지보수 기간을 구성할 때는 다음 안내를 따르세요.

GKE 유지보수 기간을 준수하는 유지보수 이벤트 유형과 그렇지 않은 유지보수 이벤트 유형을 이해합니다. 자세한 내용은 GKE 유지보수 정책을 준수하는 자동 유지보수 및 GKE 유지보수 정책을 준수하지 않는 자동 유지보수를 참조하세요.
클러스터에 유지보수 기간을 하나만 구성할 수 있으며 새 기간을 구성하면 이전 기간을 덮어씁니다.
32일의 순환 기간 동안 최소 48시간의 유지보수를 허용해야 합니다. 4시간 이상의 연속적으로 사용 가능한 기간만 고려됩니다.
Google Cloud 콘솔을 사용할 때 시간은 항상 해당 지역 시간대로 표시됩니다.
요일 반복은 항상 UTC를 기준으로 합니다. 따라서 gcloud CLI를 통해 해당 반복이 포함된 유지보수 기간을 완전히 UTC로 설정하는 것이 좋습니다. 플래그를 설정할 때 지역 시간을 사용할 수는 있지만 시간대는 저장되지 않습니다. 예를 들어 시간대가 UTC+6이고 유지보수 기간이 해당 시간대를 기준으로 수요일 02:00에 시작되도록 하려면 화요일 20:00로 UTC 값을 지정합니다. 자세한 내용은 유지보수 기간 시간대를 참조하세요.
클러스터가 예약된 유지보수 기간 내에 노드 업그레이드를 완료할 수 없으면 업그레이드 속도가 느려질 수 있습니다. 해당 환경에 대한 속도와 중단 사이의 최적의 균형을 찾으려면 구성을 실험해야 할 수 있습니다. 업그레이드 속도에 영향을 줄 수 있는 요소는 다음과 같습니다.
- 낮은 유지보수 가용성(예: 짧은 유지보수 기간)
- 대규모 Standard 노드 풀
- 속도보다는 최소한의 중단을 우선으로 노드 업그레이드 전략 구성
- 일부 포드 구성 선택. 자세한 내용은 노드 업그레이드 시간에 대한 고려사항을 참조하세요.

간단한 유지보수 기간이 있는 Standard 클러스터 만들기

gcloud CLI에서 --maintenance-window 플래그를 지정하여 간단한 유지보수 기간을 만들 수 있습니다. 이 플래그를 사용하면 단순화된 형식을 사용하여 매일 4시간의 유지보수 기간을 지정할 수 있습니다. 유지보수 기간이 있는 Autopilot 클러스터를 만들려면 Google Cloud 콘솔을 사용합니다.

간단한 유지보수 기간이 있는 새 Standard 클러스터를 만듭니다.

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window START_TIME

다음을 바꿉니다.

CLUSTER_NAME: 새 클러스터의 이름입니다.
START_TIME: UTC 시간 기준 24시간 타임스탬프입니다(예: 16:00).

유지보수 기간은 매일 지정된 START_TIME에 실행되며 4시간 동안 실행됩니다.

커스텀 유지보수 기간 만들기

이 섹션에 설명된 추가 매개변수를 사용하여 주 또는 월의 특정 시간에 발생하는 유지보수 기간을 만들 수 있습니다.

예를 들어 다음 명령어는 2026년 8월 19일 수요일 오전 2시(UTC)에 유지보수 기간이 사용 설정된 my-cluster라는 클러스터를 만듭니다. 이 유지보수 기간은 월요일과 금요일에 시작되고 30시간 후에 종료됩니다. 유지보수 기간은 8월 21일 금요일 오전 2시에 시작되고 8월 22일 토요일 오전 8시에 종료됩니다. 날짜 및 시간 형식 지정에 대해 자세히 알아보세요.

gcloud container clusters create my-cluster \
    --maintenance-window-start 2026-08-19T02:00:00Z \
    --maintenance-window-end 2026-08-20T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY:BYDAY=MO,FR'

더 많은 시나리오는 유지보수 기간 예시를 참조하세요.

유지보수 기간이 있는 클러스터 만들기

gcloud CLI 또는 Google Cloud 콘솔을 사용하여 에서 유지보수 기간이 있는 새 Standard 클러스터를 만들 수 있습니다. 유지보수 기간이 있는 새 Autopilot 클러스터를 만들려면 Google Cloud 콘솔을 사용합니다.

gcloud

유지보수 기간이 있는 새 Standard 클러스터를 만듭니다.

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

다음을 바꿉니다.

CLUSTER_NAME: 새 클러스터의 이름
START_TIME: 반복 유지보수 기간이 사용 설정된 날짜 및 시간이며, RFC-5545 DTSTART 값으로 표시됩니다. 이 시간 이후에는 RRULE에 따라 유지보수 기간이 반복됩니다. START_TIME은 유지보수 기간이 시작되는 시간도 제공합니다.
END_TIME: 유지보수 기간 계산을 위한 종료 시간으로, START_TIME 이후의 시간을 동일한 형식으로 표시합니다. END_TIME 값은 START_TIME 이후 시간이어야 합니다.
RRULE: RFC-5545 RRULE로 표시된 유지보수 기간의 반복입니다. 이는 여러 방식으로 반복 규칙을 지정하여 유지보수 기간 시작일을 결정하는 유연한 방법입니다. 예를 들어 주 또는 월에서 특정 시간의 반복을 지정할 수 있습니다. END_TIME 날짜가 START_TIME 날짜보다 크면 유지보수 기간이 여러 날에 걸쳐 진행됩니다. 예를 들어 일요일에 시작하는 유지보수 기간이 월요일까지 계속될 수 있습니다.

콘솔

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

Google Kubernetes Engine으로 이동
만들기를 클릭합니다.
클러스터를 구성합니다.
탐색창의 클러스터에서 자동화를 클릭합니다.
유지보수 기간 사용 설정 체크박스를 선택합니다.
시작 시간과 기간을 선택한 다음 유지보수 기간이 시작되는 요일을 선택합니다. 반복 규칙 사양(RRule)을 직접 수정하려면 커스텀 편집기를 선택합니다.
만들기를 클릭합니다.

기존 클러스터의 유지보수 기간 구성

gcloud

기존 클러스터의 유지보수 기간을 만들거나 업데이트합니다.

gcloud container clusters update CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

다음을 바꿉니다.

CLUSTER_NAME: 새 클러스터의 이름
START_TIME: 반복 유지보수 기간이 사용 설정된 날짜 및 시간이며, RFC-5545 DTSTART 값으로 표시됩니다. 이 시간 이후에는 RRULE에 따라 유지보수 기간이 반복됩니다. START_TIME은 유지보수 기간이 시작되는 시간도 제공합니다.
END_TIME: 유지보수 기간 계산을 위한 종료 시간으로, START_TIME 이후의 시간을 동일한 형식으로 표시합니다. END_TIME 값은 START_TIME 이후 시간이어야 합니다.
RRULE: RFC-5545 RRULE로 표시된 유지보수 기간의 반복입니다. 이는 여러 방식으로 반복 규칙을 지정하여 유지보수 기간 시작일을 결정하는 유연한 방법입니다. 예를 들어 주 또는 월에서 특정 시간의 반복을 지정할 수 있습니다. END_TIME 날짜가 START_TIME 날짜보다 크면 유지보수 기간이 여러 날에 걸쳐 진행됩니다. 예를 들어 일요일에 시작하는 유지보수 기간이 월요일까지 계속될 수 있습니다.

콘솔

기존 클러스터의 유지관리 기간을 만들거나 수정하려면 다음 단계를 따르세요.

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

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
자동화에서 유지보수 기간 필드 옆의 유지보수 정책 수정을 클릭합니다.
유지보수 기간 사용 설정 체크박스를 선택합니다.
시작 시간과 기간을 선택한 다음 유지보수 기간이 시작되는 요일을 선택합니다. RRule을 직접 수정하려면 커스텀 편집기를 선택합니다.
변경사항 저장을 클릭합니다.

완료되지 않은 유지보수를 수동으로 완료

업그레이드 또는 기타 자동 유지보수가 완료되는 데 유지보수 기간보다 긴 시간이 소요되면 GKE는 진행 중인 유지보수 태스크를 중지했다가 다음 유지보수 기간 중에 다시 시작합니다. 자동 업그레이드가 취소되고 노드 자동 업그레이드가 사용 설정된 경우에는 노드 버전이 혼합된 상태일 수 있지만 클러스터는 정상적으로 작동합니다.

클러스터를 수동으로 업그레이드하거나, 부분 업그레이드를 취소하거나 롤백하려면 수동으로 클러스터 업그레이드를 확인하세요.

유지보수 기간 삭제

gcloud

클러스터에서 유지보수 기간을 삭제합니다.

gcloud container clusters update CLUSTER_NAME --clear-maintenance-window

CLUSTER_NAME을 기존 클러스터의 이름으로 바꿉니다.

콘솔

유지관리 기간을 삭제하려면 다음 단계를 따르세요.

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

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
자동화에서 유지보수 기간 필드 옆의 유지보수 정책 수정을 클릭합니다.
유지보수 기간 사용 설정 체크박스를 선택 취소합니다.
변경사항 저장을 클릭합니다.

유지보수 기간 예시

다음 예시는 유지보수 기간을 구성하는 여러 가지 방법을 보여줍니다. 플래그는 새 클러스터를 만들거나 기존 클러스터를 업데이트할 때 동일한 구문을 사용하므로 관련 플래그만 표시됩니다.

2026년 8월 22일 시작하는 주말

이 예시에서 시작 및 종료 타임스탬프의 차이는 만 이틀입니다. 따라서 유지보수 기간은 토요일과 일요일을 모두 포함한 전체 주말 동안 실행됩니다. 기간을 정확히 48시간이 아닌 다른 시간으로 설정하려면 -start를 수정하여 기간 시작 시간을 변경하거나 -end를 수정하여 기간의 총 길이를 변경합니다.

--maintenance-window-start 2026-08-22T00:00:00Z \
--maintenance-window-end 2026-08-24T00:00:00Z \
--maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'

평일에 매일 오전 9시~오후 5시(UTC-4)

이 예시는 일일 유지보수 기간을 설정하되 주말은 생략하는 방법을 보여줍니다. 이 예시에서는 UTC가 아닌 시간대를 지정합니다.

--maintenance-window-start 2026-09-02T09:00:00-04:00 \
--maintenance-window-end 2026-09-02T17:00:00-04:00 \
--maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

주 1회 오후 4시(UTC-7)에 8시간 동안

--maintenance-window-start의 시간대를 지정하지 않으면 Google Cloud 계정에 구성된 현지 시간이 사용됩니다. Google Cloud 콘솔은 항상 현지 시간을 사용합니다.

--maintenance-window-start 2026-08-13T16:00:00-7:00 \
--maintenance-window-end 2026-08-14T00:00:00-7:00 \
--maintenance-window-recurrence 'FREQ=WEEKLY'

평일 야간

이 예시에서는 UTC-7 시간대로 주중 자정 전후에 실행되는 일일 유지보수 기간을 보여줍니다. 이 예시에서 기간은 저녁 20:00부터 다음 날 오전 4:00까지입니다.

 --maintenance-window-start 2026-08-15T20:00:00-7:00 \
 --maintenance-window-end 2026-08-16T04:00:00-7:00 \
 --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH'

유지보수 제외 구성

클러스터에 유지보수 제외를 설정하려면 다음을 지정해야 합니다.

이름: 제외의 이름입니다(선택사항).
시작 시간: 제외 기간이 시작되는 날짜와 시간입니다.
종료 시간: 제외 기간이 종료되는 날짜 및 시간입니다. 사용 가능한 각 범위의 제외 기간 길이에 대한 제한사항은 다음 표를 참조하세요.
범위: 제한할 자동 업그레이드의 범위입니다. 사용 가능한 제외 범위가 나열된 다음 표를 참조하세요.

범위	설명	최대 제외 기간
업그레이드 없음(기본값)	모든 패치 및 마이너 업그레이드를 제외합니다. 업그레이드 시 클러스터 제어 영역 및 노드의 VM 중단을 방지합니다.	30일을 초과할 수 없습니다.
마이너 업그레이드 없음	모든 부 업그레이드는 제외됩니다. 패치 업그레이드로 인해 클러스터의 제어 영역과 노드에 VM 중단이 발생할 수 있습니다.	제외 생성 날짜 이후 180일을 초과하거나 부 버전의 지원 종료 날짜를 지날 수 없습니다.
부 버전 또는 노드 업그레이드 없음	모든 부 업그레이드와 노드 업그레이드를 제외합니다. 업그레이드 시 클러스터 노드의 VM 중단을 방지합니다. 하지만 제어 영역에 중단이 발생할 수 있습니다.	제외 생성 날짜 이후 180일을 초과하거나 부 버전의 지원 종료 날짜를 지날 수 없습니다.

부 버전과 패치 버전의 정의는 버전 관리 스키마를 참조하세요.

유지보수 제외가 있는 클러스터 만들기

Google Cloud 콘솔을 사용하여 새 클러스터를 만들 때 유지보수 제외를 구성할 수 있습니다. 이 태스크는 gcloud CLI에서 수행될 수 없습니다.

유지보수 제외가 있는 새 클러스터를 만들려면 다음 안내를 따르세요.

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

Google Kubernetes Engine으로 이동
만들기를 클릭합니다.
클러스터를 구성합니다.
탐색창의 클러스터에서 자동화를 클릭합니다.
유지보수 제외에서 유지보수 제외 추가를 클릭합니다.
범위, 시작 시간 및 종료 시간을 선택합니다.
만들기를 클릭합니다.

블랙 프라이데이의 유지보수 제외 예시를 확인할 수 있습니다.

기존 클러스터의 유지보수 제외 구성

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 기존 클러스터에서 유지보수 제외를 구성할 수 있습니다.

gcloud

기존 클러스터의 유지보수 제외 구성

gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    --add-maintenance-exclusion-start START_DATE_TIME \
    --add-maintenance-exclusion-end END_DATE_TIME \
    --add-maintenance-exclusion-scope SCOPE

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
EXCLUSION_NAME: 유지보수 제외의 이름입니다.
START_DATE_TIME: 제외 시작 날짜와 시간입니다.
END_DATE_TIME: 제외 종료 날짜와 시간입니다.
SCOPE: 제외할 업그레이드 범위입니다. no_upgrades, no_minor_upgrades, no_minor_or_node_upgrades 값 중 하나일 수 있습니다.

지원되는 날짜 및 시간 형식을 보려면 gcloud topic datetimes를 실행합니다.

콘솔

기존 클러스터의 유지보수 제외를 구성하려면 다음 안내를 따르세요.

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

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
자동화에서 유지보수 제외 필드 옆의 유지보수 제외 수정을 클릭합니다.
유지보수 제외에서 유지보수 제외 추가를 클릭합니다.
범위, 시작 시간 및 종료 시간을 선택합니다.
변경사항 저장을 클릭합니다.

유지보수 제외 삭제

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 유지보수 제외를 삭제할 수 있습니다.

gcloud

기존 유지보수 제외를 삭제합니다.

gcloud container clusters update CLUSTER_NAME \
    --remove-maintenance-exclusion EXCLUSION_NAME

다음을 바꿉니다.

CLUSTER_NAME: 기존 클러스터의 이름입니다.
EXCLUSION_NAME: 삭제할 유지보수 제외의 이름입니다.

콘솔

기존 클러스터에서 유지보수 제외를 삭제하려면 다음 안내를 따르세요.

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

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
자동화에서 유지보수 제외 필드 옆의 유지보수 제외 수정을 클릭합니다.
유지보수 제외에서 삭제하려는 제외의 종료 시간 필드 옆에 있는 항목 삭제를 클릭합니다.
변경사항 저장을 클릭합니다.

클러스터의 모든 유지보수 제외를 보려면 클러스터의 유지보수 정책을 참조하세요.

유지보수 제외 예시

다음 예시에서는 블랙 프라이데이에서 사이버 먼데이까지 4일간, 많은 소매업체에서 연중 판매량이 가장 많은 기간에 유지보수를 방지합니다. 이 예시는 2021년 블랙 프라이데이(2021년 11월 26일)부터 2021년 사이버 먼데이(2021년 11월 29일)까지, 미동부 시간(UTC-5) 기준 자정부터 태평양 시간(UTC-8) 기준 23:59:59까지 유지보수 기간이 발생하지 않도록 하는 방법을 보여줍니다.

gcloud container clusters update sample-cluster \
    --add-maintenance-exclusion-name black-friday \
    --add-maintenance-exclusion-start 2021-11-26T00:00:00-05:00 \
    --add-maintenance-exclusion-end 2021-11-29T23:59:59-08:00 \
    --add-maintenance-exclusion-scope no_upgrades

클러스터의 유지보수 정책 보기

유지보수 기간 및 모든 유지보수 제외를 포함하여 클러스터의 유지보수 정책을 보려면 다음 명령어를 사용합니다.

gcloud container clusters describe CLUSTER_NAME

문제 해결

유지보수 제외 범위 제한은 출시 채널에만 적용 가능

유지보수 제외에서 자동 업그레이드 범위를 제한하는 경우 클러스터를 출시 채널에 등록해야 합니다. 그렇지 않으면 다음 오류가 발생할 수 있습니다.

ERROR: (gcloud.container.clusters.update) INVALID_ARGUMENT: Cannot update to
STATIC channel since following maintenancePolicy.maintenanceExclusions can only
apply to release channels. Please remove those maintenance exclusions.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=MaintenancePolicy.maintenanceExclusions["no"] could not apply to cluster
in STATIC channel, only no_upgrades exclusions are allowed in STATIC channel.

유지보수 제외가 한도를 초과함

모든 업그레이드(즉, '업그레이드 없음' 범위)를 제외하는 유지보수 제외를 최대 3개까지만 지정할 수 있습니다. 그렇지 않으면 다음 오류가 발생합니다.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of active maintenance exclusions exceeds limit (3).

유지보수 제외를 최대 20개까지 지정할 수 있습니다. 그렇지 않으면 다음 오류가 발생합니다.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of total maintenance exclusions exceeds limit (20).

다음 단계

클러스터 및 노드 업그레이드에 대해 자세히 알아보기
노드 자동 업그레이드 사용 설정 방법 알아보기
클러스터 알림 수신 방법 알아보기