[IT-방법] 파드 YAML 설정 파일 작성법 총정리 – 필수 필드부터 실무 예제까지

파드 YAML 설정 파일, 왜 한 번의 오타로 무너질까요

CI/CD 파이프라인을 돌리다가 갑자기 붉은색 에러 메시지가 뜨면서 배포가 중단된 경험이 있나요? 분명히 로컬에서는 잘 작동하던 설정 파일이 쿠버네티스 클러스터에만 올라가면 BadRequest 에러를 내뱉으며 거부당하곤 해요. 들여쓰기 한 칸을 잘못했거나, 필드 이름의 대소문자를 틀리는 아주 사소한 실수 때문이죠.

쿠버네티스 환경에서 파드 YAML 설정 파일은 단순한 텍스트 파일이 아니에요. 운영 환경의 컨테이너가 어떻게 실행되고, 어떤 자원을 얼마나 쓸지 결정하는 설계도와 같아서 작은 오차가 시스템 전체의 장애로 이어질 수 있어요. 특히 데브옵스 엔지니어라면 배포 자동화 과정에서 발생하는 이런 문법 오류를 줄이는 것이 업무 효율의 핵심이에요.

이 글을 끝까지 읽으시면 더 이상 YAML 문법 때문에 배포를 반복하며 시간을 허비하지 않게 될 거예요. 기초적인 구조부터 실무에서 즉시 복사해서 쓸 수 있는 고급 옵션까지 모두 다뤄요.

이 글에서 배워갈 핵심 내용이에요

• 파드 매니페스트를 구성하는 4가지 필수 필드 구조
• 실무에 바로 적용 가능한 최소 단위 및 확장 예제
• 리소스 제한과 상태 체크(Probe)를 포함한 고급 설정법
• 설정 파일 검증을 위한 kubectl 명령어 활용법

작성 전 반드시 점검해야 할 기본 준비 사항

파드 매니페스트를 작성하기 전에 먼저 준비되어야 할 도구와 개념이 있어요. 무턱대고 메모장에 코드를 적기 시작하면 나중에 수정하기가 매우 까다로워져요. 먼저 kubectl 명령어가 클러스터에 정상적으로 연결되어 있는지 확인하는 것이 우선이에요.

또한, 작성하려는 파드가 단독으로 존재할 것인지, 아니면 Deployment 같은 컨트롤러에 의해 관리될 것인지 결정해야 해요. 실무에서는 파드를 직접 생성하기보다는 컨트롤러를 통해 관리하는 경우가 훨씬 많지만, 파드의 동작 원리를 이해하려면 단일 파드 설정법을 먼저 마스터하는 것이 순서예요.

파드 구성 방식 비교

위 표에서 볼 수 있듯이, 학습 단계에서는 단독 파드 설정을 통해 쿠버네티스 yaml 문법을 익히는 것이 좋고, 실제 서비스를 배포할 때는 디플로이먼트를 사용하는 것이 기본 원칙이에요.

파드 설정 파일 작성 실전 가이드

이제 본격적으로 파드 설정 파일 작성을 시작해 볼게요. 파드 매니페스트는 계층적인 구조를 가지고 있어서, 각 필드가 어떤 역할을 하는지 정확히 파악하는 것이 중요해요.

STEP 1. 필수 필드 4가지 이해하기

모든 파드 YAML에는 반드시 들어가야 하는 네 가지 핵심 섹션이 있어요. 이 부분이 빠지면 쿠버네티스는 요청을 이해하지 못해요.

• apiVersion: 사용할 쿠버네티스 API의 버전을 명시해요. 파드는 보통 v1을 사용해요.
• kind: 생성할 객체의 종류를 알려줘요. 여기서는 Pod라고 적어요.
• metadata: 파드의 이름, 네임스페이스, 라벨(Label) 등 식별 정보를 담아요.
• spec: 파드가 실제로 어떻게 동작할지 정의하는 가장 중요한 부분이에요. 어떤 이미지를 쓸지, 포트는 무엇인지 등을 적어요.

STEP 2. 최소 단위 파드 yaml 예제

가장 기본적인 형태의 예제를 먼저 살펴볼게요. Nginx 웹 서버를 실행하는 아주 단순한 구조예요.

apiVersion: v1
kind: Pod
metadata:
  name: my-nginx-pod
  labels:
    app: web
spec:
  containers:
  - name: nginx-container
    image: nginx:1.21
    ports:
    - containerPort: 80

이 코드는 my-nginx-pod라는 이름의 파드를 만들고, nginx:1.21 이미지를 사용하여 80번 포트를 여는 아주 기초적인 구성이에요. 이 단계에서는 복잡한 옵션을 빼고 구조를 익히는 데 집중하세요.

STEP 3. 실무형 확장 예제: 리소스 제한과 상태 체크

실제 운영 환경에서는 위와 같이 단순하게 쓰면 위험해요. 컨테이너가 갑자기 메모리를 무한정 잡아먹으면 노드 전체가 다운될 수 있기 때문이죠. 그래서 리소스 제한(Resources)과 상태 체크(Probes) 설정이 반드시 들어가야 해요.

apiVersion: v1
kind: Pod
metadata:
  name: production-pod
spec:
  containers:
  - name: app-container
    image: my-app:v1.2
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 3
      periodSeconds: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5

위의 파드 yaml 예제를 자세히 분석해 볼게요.

• resources: requests는 파드가 실행되기 위해 보장받아야 할 최소 자원량이고, limits는 넘어서는 안 될 최대 상한선이에요. CPU는 m(milli-cores) 단위를 쓰고, 메모리는 Mi 또는 Gi 단위를 사용해요.
• livenessProbe: 컨테이너가 살아있는지 확인해요. 만약 설정한 경로(/healthz)에서 응답이 없으면 쿠버네티스가 컨테이너를 강제로 재시작해요.
• readinessProbe: 컨테이너가 트래픽을 받을 준비가 되었는지 확인해요. 준비가 안 되었다면 서비스(Service)를 통해 들어오는 요청을 이 파드로 보내지 않도록 차단해요.

STEP 4. 환경 변수와 설정값 주입하기

애플리케이션에 따라 데이터베이스 접속 정보나 API 키 같은 설정값이 필요할 때가 있어요. 이때 YAML의 env 필드를 사용해요. 보안이 중요한 값은 ConfigMap이나 Secret을 통해 가져오는 것이 정석이에요.

spec:
  containers:
  - name: app-container
    image: my-app:v1.2
    env:
    - name: DB_HOST
      value: "db.example.com"
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: db-secret
          key: password

이렇게 작성하면 코드 내에 비밀번호를 직접 적지 않아도 되어 보안성이 크게 향상돼요. 환경 변수를 통해 설정을 관리하면 동일한 이미지를 유지하면서 환경(Dev/Prod)에 따라 다른 값을 주입할 수 있어 매우 유연해요.

STEP 5. 데이터 영속성을 위한 볼륨 설정

컨테이너는 삭제되면 내부 데이터도 함께 사라지는 휘발성 특징이 있어요. 로그 파일이나 데이터베이스 파일을 저장해야 한다면 Volume을 설정해야 해요. 가장 간단한 방법은 emptyDir를 사용하는 것이지만, 이는 파드가 삭제되면 데이터도 같이 사라지므로 주의해야 해요.

자주 하는 실수와 해결법

파드 설정을 하다 보면 누구나 한 번쯤은 벽에 부딪혀요. 제가 현장에서 직접 목격한 가장 빈번한 실수 5가지를 정리했어요.

• ❌ 들여쓰기(Indentation) 오류 → YAML은 공백 하나에 구조가 완전히 바뀌어요. → ✅ VS Code의 YAML 확장 프로그램을 사용하여 구조를 시각적으로 확인하세요.
• ❌ 필드 이름 오타 (예: contianers) → 쿠버네티스가 필드를 인식하지 못해 배포가 거부돼요. → ✅ 자동 완성 기능이 지원되는 에디터를 사용하고, 오타가 의심될 때는 공식 문서를 대조하세요.
• ❌ 리소스 요청량 과다 설정 → 노드의 전체 자원보다 큰 requests를 잡으면 파드가 Pending 상태에서 멈춰요. → ✅ 노드의 가용 자원을 kubectl describe node 명령어로 확인한 뒤 조절하세요.
• ❌ 이미지 태그 미지정 → latest 태그는 버전 관리가 안 되어 배포 시 예기치 못한 버그를 일으켜요. → ✅ 반드시 v1.2.3처럼 명확한 버전을 명시하세요.
• ❌ Port 번호 불일치 → 컨테이너 내부 포트와 YAML의 containerPort가 다르면 통신이 안 돼요. → ✅ 애플리케이션이 실제로 리스닝(Listening) 중인 포트 번호를 꼭 확인하세요.

자주 묻는 질문

Q. 파드가 Pending 상태에서 계속 머물러 있어요. 어떻게 확인하나요?

가장 먼저 kubectl describe pod [파드이름] 명령어를 입력해 보세요. 맨 아래 Events 섹션을 보면 왜 스케줄링이 안 되는지 이유가 나와요. 보통 자원 부족이나 노드 셀렉터 설정 오류가 원인인 경우가 많아요.

Q. kubectl apply와 kubectl create의 차이가 무엇인가요?

create는 새로운 리소스를 생성할 때 사용하며, 이미 같은 이름의 리소스가 있으면 에러를 발생시켜요. 반면 apply는 선언적(Declarative) 방식이에요. 기존 설정과 새로운 YAML을 비교해서 변경된 부분만 업데이트하므로 실무에서는 대부분 apply를 사용해요.

Q. YAML 파일의 문법이 맞는지 미리 검사할 방법이 있나요?

명령어를 실행하기 전에 kubectl apply --dry-run=client -f [파일명] 옵션을 사용해 보세요. 실제로 클러스터에 적용하지 않고 문법적 오류나 구조적 결함이 있는지 미리 시뮬레이션할 수 있어 매우 안전해요.

Q. ConfigMap에 저장된 값을 파드에서 어떻게 쓰나요?

파드 YAML의 env 섹션에서 valueFrom 필드를 사용하여 configMapKeyRef를 지정하면 돼요. 그러면 ConfigMap의 특정 키 값이 환경 변수로 자동 주입돼요.

성공적인 쿠버네티스 운영을 위한 마지막 체크리스트

파드 YAML 작성은 단순히 텍스트를 적는 행위가 아니라, 서비스의 안정성을 설계하는 과정이에요. 오늘 배운 내용을 바탕으로 실무에서 실수 없이 적용할 수 있도록 핵심을 요약해 드릴게요.

이제 이론은 충분히 익히셨어요. 다음 단계로 나아가기 위해 오늘 당장 실습 환경에서 직접 작은 파드 하나를 띄워 보는 건 어떨까요? 작은 성공 경험이 모여 숙련된 데브옵스 엔지니어를 만든답니다.

오늘 바로 실행할 단계별 미션이에요

• 오늘 할 일: Nginx 이미지를 활용해 가장 기본적인 파드 YAML을 작성하고 kubectl apply로 배포해 보기
• 이번 주 할 일: 리소스 제한(CPU/Memory) 옵션을 추가하여 파드의 자원 사용량 모니터링해 보기
• 실행 직전 할 일: VS Code에 Kubernetes 확장 프로그램을 설치하여 자동 완성 환경 구축하기

실습 과정에서 예상치 못한 에러를 만나거나 궁금한 점이 생긴다면 언제든 댓글로 질문을 남겨 주세요. 함께 고민하고 해결해 나가는 과정이 가장 큰 공부가 될 거예요.

관련하여 더 깊이 있는 내용을 공부하고 싶다면, 쿠버네티스 파드 기본 개념 글이나 클러스터 구축 입문 글을 함께 읽어보시는 것을 추천해요.