유지보수 기간 및 제외 구성

유지보수 기간 및 유지보수 제외를 사용하여 Google Kubernetes Engine(GKE) 클러스터에서 자동 업그레이드와 같은 자동 클러스터 유지보수가 수행되거나 될 수 없는 시기를 제어하는 방법을 보여줍니다. 이러한 유지보수 정책을 구성하기 전에 GKE 유지보수 정책을 준수하는 변경 사항과 그렇지 않은 변경사항을 검토해야 합니다.

시작하기 전에

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

• Google Kubernetes Engine API를 사용 설정합니다.
Google Kubernetes Engine API 사용 설정
• 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.

유지보수 기간 구성

유지보수 기간을 구성하려면 유지보수 기간이 언제 시작하는지, 얼마나 지속되는지, 어떤 빈도로 반복되는지를 구성합니다. 예를 들어 매주 월요일부터 금요일까지 매일 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시간 동안 실행됩니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

유지보수 기간 삭제

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

유지보수 기간 예시

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

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'

유지보수 제외 구성

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

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

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

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

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

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

   Google Kubernetes Engine으로 이동

2. add_box만들기를 클릭합니다.

3. 클러스터를 구성합니다.

4. 탐색창의 클러스터에서 자동화를 클릭합니다.

5. 유지보수 제외에서 add 유지보수 제외 추가를 클릭합니다.

6. 범위, 시작 시간 및 종료 시간을 선택합니다.

7. 만들기를 클릭합니다.

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

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

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

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

유지보수 제외 삭제

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

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

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

유지보수 제외 예시

다음 예시에서는 블랙 프라이데이에서 사이버 먼데이까지 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).

다음 단계

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