kubectl 명령어 정리

출처 https://blog.palark.com/ready-to-use-commands-and-tips-for-kubectl/

오늘은 kubectl 사용에 미숙한 부분을 정리하고 기록하기 위해, kubectl의 개념, 기본 문법, 그리고 주로 사용되는 명령어를 알아보겠습니다.

다양한 옵션 및 자세한 설명은 kubernetes 공식 문서를 참고해주세요.

kubectl 이란?

---

쿠버네티스 API를 사용하여 쿠버네티스 클러스터의 컨트롤 플레인과 통신하기 위한 커맨드라인 툴

-쿠버네티스 문서 설명

위 설명대로 kubectl은 쿠버네티스 API 와 통신하여 쿠버네티스 클러스터를 관리하기 위한 커맨드라인 도구입니다. 사용자는 kubectl 을 통해 클러스터와 상호작용할 수 있으며 다양한 리소스 생성, 조회, 수정, 삭제 등과 같은 작업을 할 수 있습니다.

Syntax

---

kubectl [command] [TYPE] [NAME] [flags] [-o <output_format>]

• command: - 명령어
  • 하나 이상의 리소스에서 수행하려는 동작을 지정합니다.
  • ex) create, get, describe, delete
• TYPE: - 리소스 타입
  • 리소스 타입을 지정합니다
  • ex) pods, configmaps, nodes
  • shortnames로 축약 가능
    • pods -> po
    • configmaps -> cm
    • nodes -> no
• NAME:
  • 리소스 이름을 지정합니다. 이름은 대소문자를 구분하며 이르을 생략하면, 모든 리소스에 대한 세부사항이 표시됩니다.
• flags:
  • 플래그를 지정합니다.
  • ex) -s 또는 --server 플래그를 사용하면 쿠버네티스 API 서버의 주소와 포트를 지정할 수 있습니다.
• -o <output_format> - 출력 옵션
  • 다양한 출력 옵션을 지원하는 명령어로 -o 또는 --output 을 통해 출력 형식을 지정할 수 있습니다.

출력 형식	설명
-o custom-columns=<spec>	쉼표로 구분된 사용자 정의 열 목록을 사용하여 테이블을 출력한다.
-o custom-columns-file=<filename>	<filename> 파일에서 사용자 정의 열 템플릿을 사용하여 테이블을 출력한다.
-o json	JSON 형식의 API 오브젝트를 출력한다.
-o jsonpath=<template>	jsonpath 표현식에 정의된 필드를 출력한다.
-o jsonpath-file=<filename>	<filename> 파일에서 jsonpath 표현식으로 정의된 필드를 출력한다.
-o name	리소스 이름만 출력한다.
-o wide	추가 정보가 포함된 일반 텍스트 형식으로 출력된다. 파드의 경우, 노드 이름이 포함된다.
-o yaml	YAML 형식의 API 오브젝트를 출력한다.

자주 사용되는 kubectl명령어

---

클러스터 정보 및 설정

cluster-info

• 클러스터의 API 서버와 핵심 구성 요소 정보를 출력합니다.

kubectl cluster-info [flags]

top

• 클러스터 리소스(노드, 파드) 사용량을 출력합니다.
• 해당 명령어 사용을 위해서는 metrics-server가 클러스터에 설치되어 있어야 동작합니다.

kubectl top [flags] [options]

• ex) nodes 자원량 확인

kubectl top nodes

• ex) pod 자원량 확인

kubectl top pods

version

• 클라이언트와 서버의 쿠버네티스 버전을 출력합니다.

kubectl version [--client] [flags]

config view

• 현재 설정된 클러스터 컨텍스트와 인증 정보를 출력합니다.
• 기본 네임스페이스를 확인하거나 변경할 때 유용합니다.

kubectl config view

리소스 관련

create

• 매니페스트 파일을 통해 하나 이상의 리소스 생성

kubectl create -f FILENAME [flags]

apply

• 매니페스트 파일을 통해 리소스를 생성하거나 업데이트

[!TIP]

create 명령은 리소스를 “생성”할 때 사용되며, 이미 존재하는 리소스를 수정하려면 apply 명령을 사용해야 합니다.

kubectl apply -f FILENAME [flags]

delete

• 리소스를 삭제합니다.
• 매니페스트 파일 또는 리소스 이름으로 삭제할 수 있습니다.

kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]

• ex) pod 삭제

kubectl delete pod my-pod

run

• 간단한 파드를 생성합니다.
• 테스트 환경에서 주로 사용하며, 배포(deployment)나 YAML 매니페스트를 사용하지 않을 때 유용합니다.

kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags]

• ex) nginx 파드 생성

kubectl run nginx --image=nginx

exec

• 실행 중인 컨테이너 안에서 명령어를 실행합니다.
• 디버깅 및 문제 해결에 유용합니다.

kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]

• ex) bash 셸로 접속

kubectl exec -it my-pod -- /bin/bash

get

• 리소스를 조회합니다.

kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]

• ex) pod 목록 확인

kubectl get pods

logs

• 특정 파드의 컨테이너 로그를 확인합니다.

kubectl logs POD [-c CONTAINER] [--follow] [flags]

• ex) pods 로그 확인

kubectl logs my-pod

describe

• 리소스의 상세 정보를 출력합니다.

kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]

• ex) 파드 상세 정보 확인

kubectl describe pod my-pod

explain

• 특정 리소스의 필드와 매니페스트 구조를 설명합니다.
• 매니페스트 작성 시 유용합니다.

kubectl explain [--recursive=false] [flags]

• ex) pod 리소스 구조 확인

kubectl explain pod

기타 명령어

port-forward

• 로컬 머신에서 파드로 포트를 전달하여 테스트 환경을 구성할 때 사용됩니다.

kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]

• ex) 8080 포트를 로컬에서 pod로 전달

kubectl port-forward my-pod 8080:80

scale

• deployment 나 statefulset 등의 리소스를 스케일링합니다.

kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags]

• ex) deployment를 5개의 파드로 스케일링

kubectl scale deployment nginx-deployment --replicas=5

명령어 요약

---

명령어	설명	예시
cluster-info	클러스터의 API 서버와 핵심 구성 요소 정보를 출력	kubectl cluster-info
top	클러스터 리소스(노드, 파드) 사용량 출력	kubectl top nodes, kubectl top pods
version	클라이언트와 서버의 Kubernetes 버전 출력	kubectl version --client
config view	현재 설정된 클러스터 컨텍스트와 인증 정보 출력	kubectl config view
create	매니페스트 파일로 리소스를 생성	kubectl create -f deploy.yaml
apply	매니페스트 파일로 리소스 생성 또는 업데이트	kubectl apply -f deploy.yaml
delete	리소스를 삭제	kubectl delete pod my-pod
run	간단한 파드를 생성 (테스트 환경에서 주로 사용)	kubectl run nginx --image=nginx
exec	실행 중인 컨테이너에서 명령어 실행 또는 셸 접속	kubectl exec -it my-pod -- /bin/bash
get	리소스 조회	kubectl get pods, kubectl get svc -o wide
logs	특정 파드의 컨테이너 로그 확인	kubectl logs my-pod, kubectl logs -f my-pod
describe	리소스 상세 정보 출력	kubectl describe pod my-pod
explain	특정 리소스의 매니페스트 구조 설명	kubectl explain pod, kubectl explain pod.spec
port-forward	로컬 머신에서 파드로 포트를 전달하여 테스트 환경 구성	kubectl port-forward my-pod 8080:80
scale	Deployment, StatefulSet 등의 리소스를 스케일링	kubectl scale deployment nginx --replicas=5

Reference

---

• https://kubernetes.io/ko/docs/reference/kubectl/