Kubernetes manifest — apiVersion, kind, spec · Markup Quest

모든 Kubernetes 객체가 같은 네 키 가진 YAML 문서

Kubernetes manifest 는 모양이 딱 정해져 있어. apiVersion, kind, metadata, spec. 클러스터 API server 가 manifest 를 읽고, 그 kind 에 해당하는 OpenAPI schema 로 검증한 다음, 실제 상태를 거기 맞춰 조정해. Deployment 든 Service 든 ConfigMap 이든 Ingress 든 Job 이든 CronJob 이든, 전부 이 네 키 봉투를 써.

네 키 봉투

apiVersion — 이 객체가 어느 API 그룹의 몇 번 버전에 속하는지 (Deployment 면 apps/v1, Service 면 v1).
kind — 리소스 종류 (Deployment, Service, ConfigMap, …).
metadata — 이름과 namespace, label, annotation 이 들어가.
spec — 원하는 상태를 적어. 안쪽 모양은 kind 마다 달라.

한 논리적 service 의 multi-document 파일

보통 service 하나는 Deployment 와 Service, ConfigMap, 그리고 필요하면 Ingress 까지 묶어서 나가. 한 파일 안에 --- 로 나뉜 문서 네 개인 셈이지. kubectl apply -f stack.yaml 한 줄이면 넷이 한꺼번에 적용돼.

원칙: manifest 는 원하는 상태지 명령이 아니야. 클러스터가 알아서 그 상태를 향해 맞춰가. 그래서 선언적이고 몇 번을 적용해도 결과가 같은 YAML 이 Kubernetes 에 맞는 포맷인 거야. 순서대로 시키는 shell script 는 애초에 모양이 안 맞아.

Code

한 파일에 완전한 service·yaml

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: pippa-config
data:
  PORT: "8000"
  LOG_LEVEL: info
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pippa
  labels:
    app: pippa
spec:
  replicas: 3
  selector:
    matchLabels:
      app: pippa
  template:
    metadata:
      labels:
        app: pippa
    spec:
      containers:
        - name: api
          image: ghcr.io/cwk/pippa:1.0
          envFrom:
            - configMapRef:
                name: pippa-config
          ports:
            - containerPort: 8000
---
apiVersion: v1
kind: Service
metadata:
  name: pippa
spec:
  selector:
    app: pippa
  ports:
    - port: 80
      targetPort: 8000

적용 전 검증·bash

# 클러스터 실제 API 로 schema-체크
kubectl apply --dry-run=server -f stack.yaml

# 오프라인 schema-체크 (빠름, 오타 잡음)
kubeconform -summary stack.yaml

# kube-linter 로 lint (best practice)
kube-linter lint stack.yaml

'string vs number' 함정·yaml

# 잘못 — port 가 정수 8000 됨, ConfigMap 거부 (string 이어야 함)
data:
  PORT: 8000

# 맞음 — port 가 string "8000"
data:
  PORT: "8000"

Exercise

replica 하나짜리 Deployment 와 Service 를 한 YAML 파일에 정의해봐. 이미지는 아무거나, nginx 면 충분해. kubectl apply -f stack.yaml --dry-run=server 로 돌려보고. 그 다음 필수 필드를 일부러 빼먹고 (selector 나 port) 다시 돌려. 에러 메시지가 빠진 필드를 콕 짚어줄 거야. 새로운 리소스 kind 를 만날 때마다 이 왕복이 제일 빠른 학습법이야.

Kubernetes manifest — apiVersion, kind, spec

모든 Kubernetes 객체가 같은 네 키 가진 YAML 문서

네 키 봉투

한 논리적 service 의 multi-document 파일

Code

External links

Exercise

Progress

댓글 0