[Kubernetes] Manifest 파일과 구조 & 작성방법
쿠버네티스의 리소스 오브젝트를 생성하는 방법에는 kubectl CLI 커맨드로 생성하는 방법과 Manifest 파일을 적용해 생성하는 방법 2가지가 존재한다.
이번에는 Manifest 파일과 이를 통해 리소스 오브젝트를 생성하는 방법을 알아보도록 한다.
Manifest 파일
Manifest 파일은 YAML / JSON 포맷으로 작성되는 쿠버네티스 리소스 오브젝트의 구성을 정의하는 파일이다. 생성하고자하는 쿠버네티스 오브젝트를 파일에 정의한 후, kubectl apply를 통해 클러스터에 Manifest 파일을 적용한다.
kubectl apply -f ./deployment.yml
apply 명령어로 마스터 노드에 있는 쿠버네티스 API 서버에 Manifest 파일 내용을 전달하고, 파일의 유효성을 검사한다. 이후 Manifest 파일 내용을 etcd에 업데이트함으로써 클러스터의 상태와 구성을 업데이트한다. (클러스터의 일관성 보장)
파일 작성은 주로 YAML을 사용하며, docker의 Dockerfile이나 docker-compose.yml과는 다르게 특별히 파일이름이 지정되어 있지않다. 생성할 리소스 단위로 작성하며, 여러 리소스를 하나의 Manifest 파일에 작성할 수도 있다.
Manifest 파일 구조
Manifest 파일은 크게 아래와 같은 4가지 필드가 존재한다. 이를 주 항목이라고 부르도록 한다.
apiVersion: <API_VERSION>
kind: <KIND>
metadata:
name: <NAME>
labels:
<KEY>: <VALUE>
spec:
<SPECIFIC_CONFIGURATION>
...
주 항목의 내용은 아래와 같다.
| 주 항목 | 설명 |
| apiVersion | API 그룹 및 버전 |
| kind | 리소스 유형 |
| metadata | 리소스의 메타데이터 |
| spec | 리소스 내용 |
apiVersion
리소스를 생성하기에 앞서 생성하고자 하는 리소스의 API 그룹과 버전을 명시해주어야한다. API 그룹별로 포함되어있는 리소스와 그 내용들이 다르기 때문에 생성하고자하는 리소스의 apiVersion 값을 잘 확인해야한다. 또, 쿠버네티스의 버전별로도 내용이 달라지기 때문에 현재 적용되어있는 쿠버네티스와 컴포넌트들의 버전을 확인해둘 필요가 있다.
kubectl explain으로 해당 리소스를 어떻게 정의하는지에 대한 내용을 확인할 수 있다.
kubectl explain [리소스 타입]
kind
생성할 리소스의 종류를 명시해주는 부분이다.
대표적인 리소스 별 apiVersion 내용과 kind는 아래 표와 같다.
| 리소스 | API 그룹 / 버전 | 리소스 유형(Kind) |
| 파드 | core/v1 (v1으로 축약가능) | Pod |
| 서비스 | core/v1 (v1으로 축약가능) | Service |
| 디플로이먼트 | apps/v1 | Deployment |
| 레플리카셋 | apps/v1 | ReplicaSet |
metadata
생성할 리소스에 대한 메타데이터를 적어주는 부분으로, 주로 레이블(label)이나 이름을 메타데이터에서 선언해준다.
spec
생성할 리소스의 구체적인 스펙을 적어주는 부분이다. 리소스마다 설정해야할 값이 다르다
파드나 Deployment, ReplicaSet을 작성할 때에는 spec 구문에 생성할 컨테이너의 설정값을 작성한다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
spec:
replicas: 3 # Deployment에 포함될 ReplicaSet에 대한 설정을 해준다
selector:
matchLabels:
app: example
template:
metadata:
labels:
app: example
spec:
containers: # ReplicaSet에 포함될 컨테이너 설정을 해준다
- name: nginx
image: nginx:latest
Manifest를 작성할 때에는 쿠버네티스의 공식 Docs를 확인하도록 하자
아래는 쿠버네티스 v1.26 기반의 API Reference Docs이다.
Kubernetes API Reference Docs
kubernetes.io
파드 Manifest
파드를 생성하는 Manifest 파일을 예로 들어보자
apiVersion: v1
kind: Pod # 파드를 생성
metadata:
name: example-pod # 파드의 이름
labels: # 파드의 레이블
app: example-app
spec:
containers: # 파드의 컨테이너 구성
- name: nginx-container
image: nginx:latest
ports:
- containerPort: 80
nginx 컨테이너 하나가 포함된 파드를 생성하는 Manifest 파일이다.
이 파일을 kubectl을 통해 직접 클러스터에 적용해본다.
apply로 적용한 뒤 Creating을 조금 기다리면 파드가 생성됨을 확인할 수 있다.
이렇게 생성한 파드를 삭제하기 위해서는 delete 커맨드를 사용할 수 있다.
# Manifest 파일 기반으로 삭제
kubectl delete -f [생성한 manifest 파일]
# 리소스(파드)를 특정해 삭제
kubectl delete pod [pod 이름]
디플로이먼트 Manifest
다음으로 디플로이먼트를 생성하는 Manifest 파일을 작성해본다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx-container
image: nginx:latest
ports:
- containerPort: 80
1개의 nginx 컨테이너가 포함된 파드를 3개 생성하는 Deployment를 생성하는 Manifest 파일이다.
이번에도 이 파일을 적용하고 파드가 3개 생성되는 것을 확인할 수 있다.
여기서 delete pod로 1개의 파드를 삭제하고 다시 확인해 보았을 때, 파드가 똑같이 3개인 것을 볼 수 있다.
여기서 Deployment의 특성을 확인할 수 있다.
Deployment는 ReplicaSet을 포함하며, ReplicaSet은 명시한 3개의 파드를 유지하고자 한다. 따라서 하나의 파드가 강제로 삭제되어도, 적용한 Manifest 파일에서 명시된 상태를 유지하고자 하는 것이다.
Deployment를 삭제하기 위해 -f 옵션으로 적용 당시의 Manifest 파일을 첨부해준다.
이렇게 Manifest 파일과 그 구조에 대해 알아보았다.