kubectl apply은 Kubernetes에서 리소스의 선언적(descriptive/declarative) 구성을 클러스터에 적용하는 커맨드이다.
개요
kubectl apply 명령은 YAML 또는 JSON 형식의 매니페스트 파일을 통해 “원하는 상태(desired state)”를 정의하면, 해당 리소스가 클러스터에 존재하지 않을 경우 새로 생성하고, 이미 존재하는 경우에는 매니페스트에 맞춰 업데이트를 수행한다. 이 방식은 “무엇이 있어야 하는가(what)”만 정의하고, “어떻게 변경할 것인가(how)”는 클러스터가 알아서 처리하도록 하는 선언형(Declarative) 관리 방식이다.
동작 방식
kubectl apply는 내부적으로 다음 세 가지 구성을 비교하여 변경이 필요한 부분만 적용한다.
- 사용자가 제공한 로컬 구성 파일(Local configuration)
- 클러스터에 현재 저장된 실제 객체 상태(Live object configuration)
- 마지막으로 apply된 구성(Last applied configuration)
이 3가지 구성 간의 차이를 계산하여, 변경된 필드만 patch 형태로 업데이트하고, 불필요한 필드 삭제 또는 추가가 있을 경우 반영한다.
사용 예시
다음은 간단한 Deployment 매니페스트를 적용하는 예시이다:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.23
kubectl apply -f my-nginx.yaml
위 명령은 my-nginx라는 Deployment가 존재하지 않으면 생성하며, 존재한다면 정의된 spec에 맞추어 업데이트를 수행한다.
kubectl apply 와 다른 명령의 비교
| 명령어 | 동작 방식 | 특징 |
|---|---|---|
| kubectl apply | 선언적(declarative) | 리소스 생성 또는 업데이트, 멱등적(idempotent) |
| kubectl create | 명령형(imperative) | 리소스가 없을 때만 생성, 이미 존재하면 오류 발생 |
| kubectl replace | 명령형 | 기존 리소스를 완전히 대체 |
| kubectl delete + create | 명령형 | 리소스를 삭제 후 재생성 — 상태 초기화 우려 있음 |
장점
- 선언형 구성 관리로 YAML 파일만 버전 관리하면 됨
- 멱등성 보장 — 같은 명령 여러 번 실행해도 결과 동일
- 수정 사항이 있는 경우에만 실제 변경됨
- 복잡한 리소스 정의도 명확하게 표현 가능
유의사항
- kubectl edit, scale, patch 같은 명령형 방식과 혼용 시 충돌 가능성 있음
- 일부 필드는 불변(immutable)이므로 apply로 변경할 수 없으며, 리소스를 재생성해야 할 수 있음
- last-applied-configuration 어노테이션 삭제 또는 꼬임 발생 시 예상치 못한 동작 가능