Kubernetes kubectl 명령어와 오브젝트 완벽 가이드

Kubernetes(K8s)는 컨테이너 오케스트레이션의 사실상 표준이 되었습니다. Docker가 "컨테이너를 만드는 도구"라면, Kubernetes는 "수많은 컨테이너를 관리하는 플랫폼"입니다.

Kubernetes (K8s) has become the de facto standard for container orchestration. If Docker is "a tool for creating containers," Kubernetes is "a platform for managing numerous containers."

이 가이드에서는 Kubernetes의 핵심 오브젝트들의 관계를 먼저 이해하고, 이를 관리하는 kubectl 명령어를 체계적으로 학습합니다.

In this guide, we'll first understand the relationships between core objects in Kubernetes, then systematically learn kubectl commands to manage them.

Kubernetes 핵심 오브젝트 이해하기 Understanding Core Kubernetes Objects

Kubernetes에서 모든 것은 "오브젝트"입니다. 오브젝트는 클러스터의 상태를 나타내며, 어떤 애플리케이션이 어디서 몇 개나 실행 중인지를 정의합니다.

In Kubernetes, everything is an "object." Objects represent the state of the cluster, defining what applications are running, where, and how many.

📊 오브젝트 계층 구조 📊 Object Hierarchy

1 Deployment 원하는 상태를 선언하고 관리 Declares and manages desired state

2 ReplicaSet 정해진 수의 Pod 유지 Maintains specified number of Pods

3 Pod 실제 컨테이너가 실행되는 단위 Unit where containers actually run

↑ Deployment를 생성하면 ReplicaSet이 자동 생성되고, ReplicaSet이 Pod를 생성합니다. ↑ Creating a Deployment automatically creates a ReplicaSet, which then creates Pods.

🎁 Pod

Kubernetes에서 가장 작은 배포 단위입니다. 하나 이상의 컨테이너를 포함하며, 같은 Pod 내의 컨테이너들은 네트워크와 스토리지를 공유합니다.

The smallest deployable unit in Kubernetes. Contains one or more containers, and containers in the same Pod share network and storage.

💡 일반적으로 Pod 하나에 컨테이너 하나를 실행합니다. 💡 Typically, one container runs per Pod.

📋 Deployment

Pod의 "원하는 상태"를 선언합니다. 몇 개의 Pod를 실행할지, 어떤 이미지를 사용할지, 업데이트 전략은 무엇인지 등을 정의합니다. 실제로 가장 많이 사용하는 오브젝트입니다.

Declares the "desired state" of Pods. Defines how many Pods to run, which image to use, update strategy, etc. This is the most commonly used object in practice.

🔗 Service

Pod들에 접근하기 위한 안정적인 네트워크 엔드포인트를 제공합니다. Pod는 언제든 재생성될 수 있어 IP가 변하지만, Service는 고정된 IP와 DNS 이름을 제공합니다.

Provides stable network endpoints to access Pods. Pod IPs change as they're recreated, but Services provide fixed IPs and DNS names.

📁 Namespace

클러스터 내에서 리소스를 논리적으로 분리합니다. 팀별, 환경별(dev, staging, prod) 리소스 격리에 사용됩니다.

Logically separates resources within a cluster. Used for isolating resources by team or environment (dev, staging, prod).

kubectl 기본 명령어 패턴 kubectl Basic Command Pattern

kubectl 명령어는 일관된 패턴을 따릅니다. 이 패턴을 이해하면 어떤 리소스든 쉽게 다룰 수 있습니다.

kubectl commands follow a consistent pattern. Understanding this pattern helps you handle any resource easily.

                    # 기본 패턴

                    kubectl [동사] [리소스 타입] [이름] [옵션]

                    # Basic pattern

                    kubectl [verb] [resource type] [name] [options]

동사	설명	예시
`get`	리소스 조회	kubectl get pods
`describe`	상세 정보 확인	kubectl describe pod nginx
`create`	리소스 생성	kubectl create deployment nginx
`apply`	선언적 생성/업데이트	kubectl apply -f deployment.yaml
`delete`	리소스 삭제	kubectl delete pod nginx
`logs`	로그 확인	kubectl logs pod-name
`exec`	컨테이너 내 명령 실행	kubectl exec -it pod -- bash

Verb	Description	Example
`get`	Query resources	kubectl get pods
`describe`	View detailed info	kubectl describe pod nginx
`create`	Create resources	kubectl create deployment nginx
`apply`	Declarative create/update	kubectl apply -f deployment.yaml
`delete`	Delete resources	kubectl delete pod nginx
`logs`	View logs	kubectl logs pod-name
`exec`	Execute command in container	kubectl exec -it pod -- bash

Pod 관리 명령어 Pod Management Commands

                    # 모든 Pod 조회

                    $ kubectl get pods

                    # 특정 네임스페이스의 Pod 조회

                    $ kubectl get pods -n production

                    # 모든 네임스페이스의 Pod 조회

                    $ kubectl get pods -A

                    # Pod 상세 정보 (이벤트, 상태 등)

                    $ kubectl describe pod nginx-abc123

                    # Pod 로그 확인

                    $ kubectl logs nginx-abc123

                    # Pod 로그 실시간 스트리밍

                    $ kubectl logs -f
                    nginx-abc123

                    # Pod 내부 쉘 접속

                    $ kubectl exec -it nginx-abc123 -- /bin/bash

                    # Pod 삭제

                    $ kubectl delete pod nginx-abc123

                    # List all Pods

                    $ kubectl get pods

                    # List Pods in specific namespace

                    $ kubectl get pods -n production

                    # List Pods in all namespaces

                    $ kubectl get pods -A

                    # Pod detailed info (events, status, etc.)

                    $ kubectl describe pod nginx-abc123

                    # View Pod logs

                    $ kubectl logs nginx-abc123

                    # Stream Pod logs in real-time

                    $ kubectl logs -f
                    nginx-abc123

                    # Access Pod shell

                    $ kubectl exec -it nginx-abc123 -- /bin/bash

                    # Delete Pod

                    $ kubectl delete pod nginx-abc123

💡 실무 팁: 출력 형식 변경 💡 Pro Tip: Changing Output Format

-o wide: 더 많은 정보(IP, 노드 등) 표시

-o yaml: YAML 형식으로 출력 (디버깅에 유용)

-o json: JSON 형식으로 출력 (스크립트 처리에 유용)

-o wide: Show more info (IP, node, etc.)

-o yaml: Output in YAML format (useful for debugging)

-o json: Output in JSON format (useful for scripts)

Deployment 관리 명령어 Deployment Management Commands

Deployment는 실무에서 가장 많이 다루는 오브젝트입니다. Pod를 직접 생성하지 않고 Deployment를 통해 관리하면 스케일링, 롤링 업데이트 등을 자동으로 처리할 수 있습니다.

Deployment is the most commonly used object in practice. Managing through Deployments instead of creating Pods directly enables automatic scaling and rolling updates.

                    # Deployment 생성 (명령형)

                    $ kubectl create deployment nginx --image=nginx:latest

                    # Deployment 조회

                    $ kubectl get deployments

                    # Deployment 상세 정보

                    $ kubectl describe deployment nginx

                    # 스케일 조정 (Pod 개수 변경)

                    $ kubectl scale deployment nginx --replicas=5

                    # 이미지 업데이트 (롤링 업데이트 자동 수행)

                    $ kubectl set image deployment/nginx nginx=nginx:1.25

                    # 롤아웃 상태 확인

                    $ kubectl rollout status deployment/nginx

                    # 롤백 (이전 버전으로)

                    $ kubectl rollout undo deployment/nginx

                    # Create Deployment (imperative)

                    $ kubectl create deployment nginx --image=nginx:latest

                    # List Deployments

                    $ kubectl get deployments

                    # Deployment details

                    $ kubectl describe deployment nginx

                    # Scale (change Pod count)

                    $ kubectl scale deployment nginx --replicas=5

                    # Update image (performs rolling update)

                    $ kubectl set image deployment/nginx nginx=nginx:1.25

                    # Check rollout status

                    $ kubectl rollout status deployment/nginx

                    # Rollback (to previous version)

                    $ kubectl rollout undo deployment/nginx

Service 관리 명령어 Service Management Commands

                    # Service 조회

                    $ kubectl get services

                    # 줄여서 svc로도 가능

                    $ kubectl get svc

                    # Deployment를 Service로 노출

                    $ kubectl expose deployment nginx --port=80
                        --type=LoadBalancer

                    # Service 상세 정보 (Endpoints 확인)

                    $ kubectl describe svc nginx

                    # List Services

                    $ kubectl get services

                    # Can abbreviate to svc

                    $ kubectl get svc

                    # Expose Deployment as Service

                    $ kubectl expose deployment nginx --port=80
                        --type=LoadBalancer

                    # Service details (check Endpoints)

                    $ kubectl describe svc nginx

YAML 파일을 통한 선언적 관리 Declarative Management with YAML Files

실무에서는 명령형(kubectl create)보다 선언적(kubectl apply -f) 방식을 선호합니다. YAML 파일로 원하는 상태를 정의하고, Git으로 버전 관리하는 GitOps 방식이 표준입니다.

In practice, declarative (kubectl apply -f) is preferred over imperative (kubectl create). Defining desired state in YAML files and version controlling with Git (GitOps) is the standard approach.

                    # YAML 파일로 리소스 생성/업데이트

                    $ kubectl apply -f deployment.yaml

                    # 디렉토리 내 모든 YAML 적용

                    $ kubectl apply -f ./manifests/

                    # 현재 상태를 YAML로 출력

                    $ kubectl get deployment nginx -o yaml

                    # YAML 파일로 삭제

                    $ kubectl delete -f deployment.yaml

                    # Create/update resources from YAML

                    $ kubectl apply -f deployment.yaml

                    # Apply all YAML in directory

                    $ kubectl apply -f ./manifests/

                    # Output current state as YAML

                    $ kubectl get deployment nginx -o yaml

                    # Delete using YAML file

                    $ kubectl delete -f deployment.yaml

디버깅 필수 명령어 Essential Debugging Commands

                    # Pod가 시작되지 않을 때: 이벤트 확인

                    $ kubectl describe pod problem-pod

                    # 이전 컨테이너 로그 (재시작된 경우)

                    $ kubectl logs --previous problem-pod

                    # 클러스터 전체 이벤트

                    $ kubectl get events --sort-by='.lastTimestamp'

                    # 노드 상태 확인

                    $ kubectl get nodes

                    # 리소스 사용량 확인

                    $ kubectl top pods

                    $ kubectl top nodes

                    # When Pod won't start: check events

                    $ kubectl describe pod problem-pod

                    # Previous container logs (if restarted)

                    $ kubectl logs --previous problem-pod

                    # Cluster-wide events

                    $ kubectl get events --sort-by='.lastTimestamp'

                    # Check node status

                    $ kubectl get nodes

                    # Check resource usage

                    $ kubectl top pods

                    $ kubectl top nodes

자주 사용하는 명령어 요약 Frequently Used Commands Summary

상황	명령어
Pod 목록 확인	`kubectl get pods`
모든 리소스 확인	`kubectl get all`
Pod 로그 실시간	`kubectl logs -f pod-name`
Pod 내부 접속	`kubectl exec -it pod -- bash`
YAML 적용	`kubectl apply -f file.yaml`
스케일 조정	`kubectl scale deploy name --replicas=N`
롤백	`kubectl rollout undo deployment/name`

Situation	Command
List Pods	`kubectl get pods`
List all resources	`kubectl get all`
Real-time Pod logs	`kubectl logs -f pod-name`
Access Pod shell	`kubectl exec -it pod -- bash`
Apply YAML	`kubectl apply -f file.yaml`
Scale	`kubectl scale deploy name --replicas=N`
Rollback	`kubectl rollout undo deployment/name`

Kubernetes는 방대한 시스템이지만, Pod-Deployment-Service의 관계와 kubectl의 기본 패턴을 이해하면 대부분의 상황에 대응할 수 있습니다. 처음에는 간단한 명령어부터 익히고, 점차 YAML 매니페스트 작성으로 확장해 나가세요.

Kubernetes is a vast system, but understanding Pod-Deployment-Service relationships and kubectl's basic patterns helps you handle most situations. Start with simple commands, then gradually expand to writing YAML manifests.