이 페이지에서는 노드 자동 복구 작동 방식과 표준 Google Kubernetes Engine(GKE) 클러스터 기능을 사용하는 방법을 설명합니다.
노드 자동 복구는 GKE 클러스터의 노드를 정상 작동 상태로 유지하는 데 도움이 됩니다. 이 기능이 사용 설정되면 GKE는 클러스터의 각 노드 상태를 주기적으로 확인합니다. 노드가 장시간 동안 연속으로 상태 검사에 실패하면 GKE는 해당 노드의 복구 프로세스를 시작합니다.
Autopilot 및 Standard 설정
Autopilot 클러스터는 항상 노드를 자동으로 복구합니다. 이 설정은 중지할 수 없습니다.
Standard 클러스터의 경우에는 새 노드 풀에 대해 노드 자동 복구가 기본적으로 사용 설정됩니다. 기존 노드 풀의 자동 복구를 중지할 수 있지만 기본 구성을 유지하는 것이 좋습니다.
복구 기준
GKE는 노드의 상태를 사용하여 노드를 복구해야 하는지 결정합니다. Ready 상태를 보고하는 노드는 정상으로 간주됩니다.
노드가 일정 시간 기준점 동안 연이어 비정상 상태를 보고하는 경우 GKE가 복구 작업을 트리거합니다.
비정상 상태의 뜻은 다음과 같습니다.
일정 시간 기준(약 10분) 동안 노드가 연이은 검사에서 NotReady 상태를 보고하는 경우
일정 시간 기준(약 10분) 동안 노드가 상태를 전혀 보고하지 않는 경우
장시간(약 30분) 동안 노드의 부팅 디스크에 디스크 공간이 부족한 경우
Autopilot 클러스터의 노드가 지정된 시간 기준(약 10분)보다 오래 차단됩니다.
kubectl get nodes 명령어를 사용하면 언제든 노드의 상태 신호를 수동으로 검사할 수 있습니다.
노드 복구 프로세스
노드 복구가 필요함을 GKE가 감지하면 해당 노드는 드레이닝되고 다시 만들어집니다. 이 프로세스는 노드의 원래 이름을 유지합니다.
GKE는 드레이닝이 완료될 때까지 1시간을 기다립니다. 드레이닝이 완료되지 않으면 노드가 종료되고 새 노드가 생성됩니다.
여러 노드의 복구가 필요한 경우 GKE는 여러 노드를 동시에 복구할 수 있습니다. GKE는 클러스터 크기와 손상된 노드 수에 따라 복구 수를 조정합니다. 큰 클러스터에서는 GKE가 동시에 복구하는 노드 수가 늘어나지만 비정상 노드 수가 증가하면 동시에 복구하는 노드 수가 줄어듭니다.
복구 프로세스 중에 언제든지 노드 자동 복구를 중지하면 진행 중인 복구는 취소되지 않으며 현재 복구 중인 노드가 계속 복구됩니다.
노드 복구 내역
GKE는 자동 복구 이벤트의 로그 항목을 생성합니다. 다음 명령어를 실행하여 로그를 확인할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-01(UTC)"],[],[],null,["# Auto-repair nodes\n\n[Autopilot](/kubernetes-engine/docs/concepts/autopilot-overview) [Standard](/kubernetes-engine/docs/concepts/choose-cluster-mode)\n\n*** ** * ** ***\n\nThis page explains how node auto-repair works and\nhow to use the feature for Standard Google Kubernetes Engine (GKE) clusters.\n\n*Node auto-repair* helps keep the nodes in your GKE cluster in a\nhealthy, running state. When enabled, GKE makes periodic checks\non the health state of each node in your cluster. If a node fails consecutive\nhealth checks over an extended time period, GKE initiates a\nrepair process for that node.\n\nSettings for Autopilot and Standard\n-----------------------------------\n\nAutopilot clusters always automatically repair nodes. You can't disable\nthis setting.\n\nIn Standard clusters, node auto-repair is enabled by default for new\nnode pools. You can [disable auto repair](#disable) for an existing node pool,\nhowever we recommend keeping the default configuration.\n\nRepair criteria\n---------------\n\nGKE uses the node's health status to determine if a node\nneeds to be repaired. A node reporting a `Ready` status is considered healthy.\nGKE triggers a repair action if a node reports consecutive\nunhealthy status reports for a given time threshold.\nAn unhealthy status can mean:\n\n- A node reports a `NotReady` status on consecutive checks over the given time threshold (approximately 10 minutes).\n- A node does not report any status at all over the given time threshold (approximately 10 minutes).\n- A node's boot disk is out of disk space for an extended time period (approximately 30 minutes).\n- A node in an Autopilot cluster is cordoned for longer than the given time threshold (approximately 10 minutes).\n\nYou can manually check your node's health signals at any time by using the\n`kubectl get nodes` command.\n\nNode repair process\n-------------------\n\nIf GKE detects that a node requires repair, the node is drained\nand re-created. This process preserves the original name of the node.\nGKE waits one hour for the drain to complete. If the drain\ndoesn't complete, the node is shut down and a new node is created.\n\nIf multiple nodes require repair, GKE might repair nodes in\nparallel. GKE balances the number of repairs depending on the\nsize of the cluster and the number of broken nodes. GKE will\nrepair more nodes in parallel on a larger cluster, but fewer nodes as the number\nof unhealthy nodes grows.\n\nIf you disable node auto-repair at any time during the repair process, in-\nprogress repairs are *not* canceled and continue for any node under repair.\n| **Note:** Modifications on the boot disk of a node VM don't persist across node re-creations. To preserve modifications across node re-creation, use a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/).\n| **Note:** Node auto-repair uses a set of signals, including signals from the [Node Problem Detector](https://github.com/kubernetes/node-problem-detector). The Node Problem Detector is enabled by default on nodes that use [Container-Optimized OS](/container-optimized-os/docs/how-to/monitoring) and Ubuntu images.\n\n### Node repair history\n\nGKE generates a log entry for automated repair events. You\ncan check the logs by running the following command: \n\n gcloud container operations list\n\n### Node auto repair in TPU slice nodes\n\nIf a TPU slice node in a [multi-host TPU slice node\npool](/kubernetes-engine/docs/concepts/tpus#node_pool) is unhealthy and requires\nauto repair, the *entire* node pool is recreated. To learn more about the TPU\nslice node conditions, see [TPU slice node auto\nrepair](/kubernetes-engine/docs/how-to/tpus#node-auto-repair).\n\nEnable auto-repair for an existing Standard node pool\n-----------------------------------------------------\n\nYou enable node auto-repair on a *per-node pool* basis.\n\nIf auto-repair is disabled on an existing node pool in a Standard\ncluster, use the following instructions to enable it: \n\n### Console\n\n1. Go to the **Google Kubernetes Engine** page in the Google Cloud console.\n\n [Go to Google Kubernetes Engine](https://console.cloud.google.com/kubernetes/list)\n2. In the cluster list, click the name of the cluster you want to modify.\n\n3. Click the **Nodes** tab.\n\n4. Under **Node Pools**, click the name of the node pool you want to modify.\n\n5. On the **Node pool details** page, click *edit* **Edit**.\n\n6. Under **Management** , select the **Enable auto-repair** checkbox.\n\n7. Click **Save**.\n\n### gcloud\n\n gcloud container node-pools update \u003cvar translate=\"no\"\u003ePOOL_NAME\u003c/var\u003e \\\n --cluster \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eCONTROL_PLANE_LOCATION\u003c/var\u003e \\\n --enable-autorepair\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePOOL_NAME\u003c/var\u003e: the name of your node pool.\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of your Standard cluster.\n- \u003cvar translate=\"no\"\u003eCONTROL_PLANE_LOCATION\u003c/var\u003e: the Compute Engine [location](/compute/docs/regions-zones#available) of the control plane of your cluster. Provide a region for regional clusters, or a zone for zonal clusters.\n\nVerify node auto-repair is enabled for a Standard node pool\n-----------------------------------------------------------\n\nNode auto-repair is enabled on a *per-node pool* basis. You can verify that a\nnode pool in your cluster has node auto-repair enabled with the Google Cloud CLI\nor the Google Cloud console. \n\n### Console\n\n1. Go to the **Google Kubernetes Engine** page in the Google Cloud console.\n\n [Go to Google Kubernetes Engine](https://console.cloud.google.com/kubernetes/list)\n2. On the **Google Kubernetes Engine** page, click the name of the cluster of\n the node pool you want to inspect.\n\n3. Click the **Nodes** tab.\n\n4. Under **Node Pools**, click the name of the node pool you want to inspect.\n\n5. Under **Management** , in the **Auto-repair** field, verify that\n auto-repair is enabled.\n\n### gcloud\n\nDescribe the node pool: \n\n gcloud container node-pools describe \u003cvar translate=\"no\"\u003eNODE_POOL_NAME\u003c/var\u003e \\\n --cluster=\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e\n\nIf node auto-repair is enabled, the output of the command includes these\nlines: \n\n management:\n ...\n autoRepair: true\n\nDisable node auto-repair\n------------------------\n\nYou can disable node auto-repair for an existing node pool in a Standard\ncluster by using the gcloud CLI or the Google Cloud console.\n**Note:** You can only disable auto-repair with the gcloud CLI for a node pool in a Standard cluster enrolled in a release channel. \n\n### Console\n\n1. Go to the **Google Kubernetes Engine** page in the Google Cloud console.\n\n [Go to Google Kubernetes Engine](https://console.cloud.google.com/kubernetes/list)\n2. In the cluster list, click the name of the cluster you want to modify.\n\n3. Click the **Nodes** tab.\n\n4. Under **Node Pools**, click the name of the node pool you want to modify.\n\n5. On the **Node pool details** page, click *edit* **Edit**.\n\n6. Under **Management** , clear the **Enable auto-repair** checkbox.\n\n7. Click **Save**.\n\n### gcloud\n\n gcloud container node-pools update \u003cvar translate=\"no\"\u003ePOOL_NAME\u003c/var\u003e \\\n --cluster \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eCONTROL_PLANE_LOCATION\u003c/var\u003e \\\n --no-enable-autorepair\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePOOL_NAME\u003c/var\u003e: the name of your node pool.\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of your Standard cluster.\n- \u003cvar translate=\"no\"\u003eCONTROL_PLANE_LOCATION\u003c/var\u003e: the Compute Engine [location](/compute/docs/regions-zones#available) of the control plane of your cluster. Provide a region for regional clusters, or a zone for zonal clusters.\n\nWhat's next\n-----------\n\n- [Learn more about node pools](/kubernetes-engine/docs/concepts/node-pools)."]]
