--- title: 명령줄 도구 (kubectl) content_type: reference weight: 60 no_list: true card: name: reference weight: 20 --- {{< glossary_definition prepend="쿠버네티스는 다음을 제공한다: " term_id="kubectl" length="short" >}} 이 툴의 이름은 `kubectl`이다. 구성을 위해, `kubectl` 은 config 파일을 $HOME/.kube 에서 찾는다. KUBECONFIG 환경 변수를 설정하거나 [`--kubeconfig`](/ko/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 플래그를 설정하여 다른 [kubeconfig](/ko/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 파일을 지정할 수 있다. 이 개요는 `kubectl` 구문을 다루고, 커맨드 동작을 설명하며, 일반적인 예제를 제공한다. 지원되는 모든 플래그 및 하위 명령을 포함한 각 명령에 대한 자세한 내용은 [kubectl](/docs/reference/generated/kubectl/kubectl-commands/) 참조 문서를 참고한다. 설치 방법에 대해서는 [kubectl 설치](/ko/docs/tasks/tools/)를 참고하고, 빠른 가이드는 [치트 시트](/ko/docs/reference/kubectl/cheatsheet/)를 참고한다. `docker` 명령줄 도구에 익숙하다면, [도커 사용자를 위한 `kubectl`](/ko/docs/reference/kubectl/docker-cli-to-kubectl/)에서 대응되는 쿠버네티스 명령어를 볼 수 있다. ## 구문 터미널 창에서 `kubectl` 명령을 실행하려면 다음의 구문을 사용한다. ```shell kubectl [command] [TYPE] [NAME] [flags] ``` 다음은 `command`, `TYPE`, `NAME` 과 `flags` 에 대한 설명이다. * `command`: 하나 이상의 리소스에서 수행하려는 동작을 지정한다. 예: `create`, `get`, `describe`, `delete` * `TYPE`: [리소스 타입](#리소스-타입)을 지정한다. 리소스 타입은 대소문자를 구분하지 않으며 단수형, 복수형 또는 약어 형식을 지정할 수 있다. 예를 들어, 다음의 명령은 동일한 출력 결과를 생성한다. ```shell kubectl get pod pod1 kubectl get pods pod1 kubectl get po pod1 ``` * `NAME`: 리소스 이름을 지정한다. 이름은 대소문자를 구분한다. 이름을 생략하면, 모든 리소스에 대한 세부 사항이 표시된다. 예: `kubectl get pods` 여러 리소스에 대한 작업을 수행할 때, 타입 및 이름별로 각 리소스를 지정하거나 하나 이상의 파일을 지정할 수 있다. * 타입 및 이름으로 리소스를 지정하려면 다음을 참고한다. * 리소스가 모두 동일한 타입인 경우 리소스를 그룹화하려면 다음을 사용한다. `TYPE1 name1 name2 name<#>`
예: `kubectl get pod example-pod1 example-pod2` * 여러 리소스 타입을 개별적으로 지정하려면 다음을 사용한다. `TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>`
예: `kubectl get pod/example-pod1 replicationcontroller/example-rc1` * 하나 이상의 파일로 리소스를 지정하려면 다음을 사용한다. `-f file1 -f file2 -f file<#>` * YAML이 특히 구성 파일에 대해 더 사용자 친화적이므로, [JSON 대신 YAML을 사용한다](/ko/docs/concepts/configuration/overview/#일반적인-구성-팁).
예: `kubectl get -f ./pod.yaml` * `flags`: 선택적 플래그를 지정한다. 예를 들어, `-s` 또는 `--server` 플래그를 사용하여 쿠버네티스 API 서버의 주소와 포트를 지정할 수 있다.
{{< caution >}} 커맨드 라인에서 지정하는 플래그는 기본값과 해당 환경 변수를 무시한다. {{< /caution >}} 도움이 필요하다면, 터미널 창에서 `kubectl help` 를 실행한다. ## 클러스터 내 인증과 네임스페이스 오버라이드 기본적으로 `kubectl`은 먼저 자신이 파드 안에서 실행되고 있는지, 즉 클러스터 안에 있는지를 판별한다. 이를 위해 `KUBERNETES_SERVICE_HOST`와 `KUBERNETES_SERVICE_PORT` 환경 변수, 그리고 서비스 어카운트 토큰 파일이 `/var/run/secrets/kubernetes.io/serviceaccount/token` 경로에 있는지를 확인한다. 세 가지가 모두 감지되면, 클러스터 내 인증이 적용된다. 하위 호환성을 위해, 클러스터 내 인증 시에 `POD_NAMESPACE` 환경 변수가 설정되어 있으면, 서비스 어카운트 토큰의 기본 네임스페이스 설정을 오버라이드한다. 기본 네임스페이스 설정에 의존하는 모든 매니페스트와 도구가 영향을 받을 것이다. **`POD_NAMESPACE` 환경 변수** `POD_NAMESPACE` 환경 변수가 설정되어 있으면, 네임스페이스에 속하는 자원에 대한 CLI 작업은 환경 변수에 설정된 네임스페이스를 기본값으로 사용한다. 예를 들어, 환경 변수가 `seattle`로 설정되어 있으면, `kubectl get pods` 명령은 `seattle` 네임스페이스에 있는 파드 목록을 반환한다. 이는 파드가 네임스페이스에 속하는 자원이며, 명령어에 네임스페이스를 특정하지 않았기 때문이다. `kubectl api-resources` 명령을 실행하고 결과를 확인하여 특정 자원이 네임스페이스에 속하는 자원인지 판별한다. 명시적으로 `--namespace ` 인자를 사용하면 위와 같은 동작을 오버라이드한다. **kubectl이 서비스어카운트 토큰을 관리하는 방법** 만약 * 쿠버네티스 서비스 어카운트 토큰 파일이 `/var/run/secrets/kubernetes.io/serviceaccount/token` 경로에 마운트되어 있고, * `KUBERNETES_SERVICE_HOST` 환경 변수가 설정되어 있고, * `KUBERNETES_SERVICE_PORT` 환경 변수가 설정되어 있고, * kubectl 명령에 네임스페이스를 명시하지 않으면 kubectl은 자신이 클러스터 내부에서 실행되고 있다고 가정한다. kubectl은 해당 서비스어카운트의 네임스페이스(파드의 네임스페이스와 동일하다)를 인식하고 해당 네임스페이스에 대해 동작한다. 이는 클러스터 외부에서 실행되었을 때와는 다른데, kubectl이 클러스터 외부에서 실행되었으며 네임스페이스가 명시되지 않은 경우 kubectl은 `default` 네임스페이스에 대해 동작한다. ## 명령어 다음 표에는 모든 `kubectl` 작업에 대한 간단한 설명과 일반적인 구문이 포함되어 있다. 명령어 | 구문 | 설명 -------------------- | -------------------- | -------------------- `alpha` | `kubectl alpha SUBCOMMAND [flags]` | 쿠버네티스 클러스터에서 기본적으로 활성화되어 있지 않은 알파 기능의 사용할 수 있는 명령을 나열한다. `annotate` | kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | 하나 이상의 리소스 어노테이션을 추가하거나 업데이트한다. `api-resources` | `kubectl api-resources [flags]` | 사용 가능한 API 리소스를 나열한다. `api-versions` | `kubectl api-versions [flags]` | 사용 가능한 API 버전을 나열한다. `apply` | `kubectl apply -f FILENAME [flags]`| 파일이나 표준입력(stdin)으로부터 리소스에 구성 변경 사항을 적용한다. `attach` | `kubectl attach POD -c CONTAINER [-i] [-t] [flags]` | 실행 중인 컨테이너에 연결하여 출력 스트림을 보거나 표준입력을 통해 컨테이너와 상호 작용한다. `auth` | `kubectl auth [flags] [options]` | 승인을 검사한다. `autoscale` | kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags] | 레플리케이션 컨트롤러에서 관리하는 파드 집합을 자동으로 조정한다. `certificate` | `kubectl certificate SUBCOMMAND [options]` | 인증서 리소스를 수정한다. `cluster-info` | `kubectl cluster-info [flags]` | 클러스터의 마스터와 서비스에 대한 엔드포인트 정보를 표시한다. `completion` | `kubectl completion SHELL [options]` | 지정된 셸(bash 또는 zsh)에 대한 셸 완성 코드를 출력한다. `config` | `kubectl config SUBCOMMAND [flags]` | kubeconfig 파일을 수정한다. 세부 사항은 개별 하위 명령을 참고한다. `convert` | `kubectl convert -f FILENAME [options]` | 다른 API 버전 간에 구성 파일을 변환한다. YAML 및 JSON 형식이 모두 허용된다. 참고 - `kubectl-convert` 플러그인을 설치해야 한다. `cordon` | `kubectl cordon NODE [options]` | 노드를 스케줄 불가능(unschedulable)으로 표시한다. `cp` | `kubectl cp [options]` | 컨테이너에서 그리고 컨테이너로 파일 및 디렉터리를 복사한다. `create` | `kubectl create -f FILENAME [flags]` | 파일이나 표준입력에서 하나 이상의 리소스를 생성한다. `delete` | kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] | 파일, 표준입력 또는 레이블 셀렉터, 이름, 리소스 셀렉터 또는 리소스를 지정하여 리소스를 삭제한다. `describe` | kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] | 하나 이상의 리소스의 자세한 상태를 표시한다. `diff` | `kubectl diff -f FILENAME [flags]`| 라이브 구성에 대해 파일이나 표준입력의 차이점을 출력한다. `drain` | `kubectl drain NODE [options]` | 유지 보수를 준비 중인 노드를 드레인한다. `edit` | kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] | 기본 편집기를 사용하여 서버에서 하나 이상의 리소스 정의를 편집하고 업데이트한다. `exec` | `kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]` | 파드의 컨테이너에 대해 명령을 실행한다. `explain` | `kubectl explain [--recursive=false] [flags]` | 파드, 노드, 서비스 등의 다양한 리소스에 대한 문서를 출력한다. `expose` | kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags] | 레플리케이션 컨트롤러, 서비스 또는 파드를 새로운 쿠버네티스 서비스로 노출한다. `get` | kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] | 하나 이상의 리소스를 나열한다. `kustomize` | `kubectl kustomize [flags] [options]` | kustomization.yaml 파일의 지시 사항에서 생성된 API 리소스 집합을 나열한다. 인수는 파일을 포함하는 디렉터리의 경로이거나, 리포지터리 루트와 관련하여 경로 접미사가 동일한 git 리포지터리 URL이어야 한다. `label` | kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | 하나 이상의 리소스 레이블을 추가하거나 업데이트한다. `logs` | `kubectl logs POD [-c CONTAINER] [--follow] [flags]` | 파드의 컨테이너에 대한 로그를 출력한다. `options` | `kubectl options` | 모든 명령에 적용되는 전역 커맨드 라인 옵션을 나열한다. `patch` | kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags] | 전략적 병합 패치 프로세스를 사용하여 리소스의 하나 이상의 필드를 업데이트한다. `plugin` | `kubectl plugin [flags] [options]` | 플러그인과 상호 작용하기 위한 유틸리티를 제공한다. `port-forward` | `kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]` | 하나 이상의 로컬 포트를 파드로 전달한다. `proxy` | `kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]` | 쿠버네티스 API 서버에 프록시를 실행한다. `replace` | `kubectl replace -f FILENAME` | 파일 또는 표준입력에서 리소스를 교체한다. `rollout` | `kubectl rollout SUBCOMMAND [options]` | 리소스의 롤아웃을 관리한다. 유효한 리소스 타입에는 디플로이먼트(deployment), 데몬셋(daemonset)과 스테이트풀셋(statefulset)이 포함된다. `run` | kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags] | 클러스터에서 지정된 이미지를 실행한다. `scale` | kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] | 지정된 레플리케이션 컨트롤러의 크기를 업데이트한다. `set` | `kubectl set SUBCOMMAND [options]` | 애플리케이션 리소스를 구성한다. `taint` | `kubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options]` | 하나 이상의 노드에서 테인트(taint)를 업데이트한다. `top` | `kubectl top [flags] [options]` | 리소스(CPU/메모리/스토리지) 사용량을 표시한다. `uncordon` | `kubectl uncordon NODE [options]` | 노드를 스케줄 가능(schedulable)으로 표시한다. `version` | `kubectl version [--client] [flags]` | 클라이언트와 서버에서 실행 중인 쿠버네티스 버전을 표시한다. `wait` | kubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options] | 실험(experimental) 기능: 하나 이상의 리소스에서 특정 조건을 기다린다. 명령 동작에 대한 자세한 내용을 배우려면 [kubectl](/ko/docs/reference/kubectl/kubectl/) 참조 문서를 참고한다. ## 리소스 타입 다음 표에는 지원되는 모든 리소스 타입과 해당 약어가 나열되어 있다. (이 출력은 `kubectl api-resources` 에서 확인할 수 있으며, 쿠버네티스 1.19.1 에서의 출력을 기준으로 한다.) | NAME | SHORTNAMES | APIGROUP | NAMESPACED | KIND | |---|---|---|---|---| | `bindings` | | | true | Binding | | `componentstatuses` | `cs` | | false | ComponentStatus | | `configmaps` | `cm` | | true | ConfigMap | | `endpoints` | `ep` | | true | Endpoints | | `events` | `ev` | | true | Event | | `limitranges` | `limits` | | true | LimitRange | | `namespaces` | `ns` | | false | Namespace | | `nodes` | `no` | | false | Node | | `persistentvolumeclaims` | `pvc` | | true | PersistentVolumeClaim | | `persistentvolumes` | `pv` | | false | PersistentVolume | | `pods` | `po` | | true | Pod | | `podtemplates` | | | true | PodTemplate | | `replicationcontrollers` | `rc` | | true | ReplicationController | | `resourcequotas` | `quota` | | true | ResourceQuota | | `secrets` | | | true | Secret | | `serviceaccounts` | `sa` | | true | ServiceAccount | | `services` | `svc` | | true | Service | | `mutatingwebhookconfigurations` | | admissionregistration.k8s.io | false | MutatingWebhookConfiguration | | `validatingwebhookconfigurations` | | admissionregistration.k8s.io | false | ValidatingWebhookConfiguration | | `customresourcedefinitions` | `crd,crds` | apiextensions.k8s.io | false | CustomResourceDefinition | | `apiservices` | | apiregistration.k8s.io | false | APIService | | `controllerrevisions` | | apps | true | ControllerRevision | | `daemonsets` | `ds` | apps | true | DaemonSet | | `deployments` | `deploy` | apps | true | Deployment | | `replicasets` | `rs` | apps | true | ReplicaSet | | `statefulsets` | `sts` | apps | true | StatefulSet | | `tokenreviews` | | authentication.k8s.io | false | TokenReview | | `localsubjectaccessreviews` | | authorization.k8s.io | true | LocalSubjectAccessReview | | `selfsubjectaccessreviews` | | authorization.k8s.io | false | SelfSubjectAccessReview | | `selfsubjectrulesreviews` | | authorization.k8s.io | false | SelfSubjectRulesReview | | `subjectaccessreviews` | | authorization.k8s.io | false | SubjectAccessReview | | `horizontalpodautoscalers` | `hpa` | autoscaling | true | HorizontalPodAutoscaler | | `cronjobs` | `cj` | batch | true | CronJob | | `jobs` | | batch | true | Job | | `certificatesigningrequests` | `csr` | certificates.k8s.io | false | CertificateSigningRequest | | `leases` | | coordination.k8s.io | true | Lease | | `endpointslices` | | discovery.k8s.io | true | EndpointSlice | | `events` | `ev` | events.k8s.io | true | Event | | `ingresses` | `ing` | extensions | true | Ingress | | `flowschemas` | | flowcontrol.apiserver.k8s.io | false | FlowSchema | | `prioritylevelconfigurations` | | flowcontrol.apiserver.k8s.io | false | PriorityLevelConfiguration | | `ingressclasses` | | networking.k8s.io | false | IngressClass | | `ingresses` | `ing` | networking.k8s.io | true | Ingress | | `networkpolicies` | `netpol` | networking.k8s.io | true | NetworkPolicy | | `runtimeclasses` | | node.k8s.io | false | RuntimeClass | | `poddisruptionbudgets` | `pdb` | policy | true | PodDisruptionBudget | | `podsecuritypolicies` | `psp` | policy | false | PodSecurityPolicy | | `clusterrolebindings` | | rbac.authorization.k8s.io | false | ClusterRoleBinding | | `clusterroles` | | rbac.authorization.k8s.io | false | ClusterRole | | `rolebindings` | | rbac.authorization.k8s.io | true | RoleBinding | | `roles` | | rbac.authorization.k8s.io | true | Role | | `priorityclasses` | `pc` | scheduling.k8s.io | false | PriorityClass | | `csidrivers` | | storage.k8s.io | false | CSIDriver | | `csinodes` | | storage.k8s.io | false | CSINode | | `storageclasses` | `sc` | storage.k8s.io | false | StorageClass | | `volumeattachments` | | storage.k8s.io | false | VolumeAttachment | ## 출력 옵션 특정 명령의 출력을 서식화하거나 정렬하는 방법에 대한 정보는 다음 섹션을 참고한다. 다양한 출력 옵션을 지원하는 명령에 대한 자세한 내용은 [kubectl](/ko/docs/reference/kubectl/kubectl/) 참조 문서를 참고한다. ### 출력 서식화 모든 `kubectl` 명령의 기본 출력 형식은 사람이 읽을 수 있는 일반 텍스트 형식이다. 특정 형식으로 터미널 창에 세부 정보를 출력하려면, 지원되는 `kubectl` 명령에 `-o` 또는 `--output` 플래그를 추가할 수 있다. #### 구문 ```shell kubectl [command] [TYPE] [NAME] -o ``` `kubectl` 명령에 따라, 다음과 같은 출력 형식이 지원된다. 출력 형식 | 설명 --------------| ----------- `-o custom-columns=` | 쉼표로 구분된 [사용자 정의 열](#custom-columns) 목록을 사용하여 테이블을 출력한다. `-o custom-columns-file=` | `` 파일에서 [사용자 정의 열](#custom-columns) 템플릿을 사용하여 테이블을 출력한다. `-o json` | JSON 형식의 API 오브젝트를 출력한다. `-o jsonpath=