쿠버네티스 기본 개념 정리(2) — 매니페스트 작성과 파드 배포 실습

Seung Hyeon ·2026년 7월 15일

개발 스터디

목록 보기

29/29

웹 서버 nginx를 파드(Pod)로 띄워보기

매니페스트 파일은 쿠버네티스에서 리소스를 생성하고 관리하기 위해 사용하는 파일이다.
공식문서를 참고하여 가장 단순한 리소스인 파드부터 매니페스트로 직접 띄워보았다
공식문서 링크

# nginx-pod.yaml

apiVersion: v1        # Pod를 생성할 때는 v1이라고 기재한다 (공식 문서)
kind: Pod             # Pod를 생성한다고 명시
metadata:             # Pod에 대한 기본적인 정보
  name: nginx-pod     # Pod에 이름 붙이는 기능
spec:                 # Pod에 대한 세부 정보
  containers:
    - name: nginx-container   # 생성할 컨테이너의 이름
      image: nginx            # 컨테이너를 생성할 때 사용할 Docker 이미지
      ports:
        - containerPort: 80   # 해당 컨테이너가 어떤 포트를 사용하는지 명시적으로 표현

작성한 매니페스트를 클러스터에 적용하고 파드가 떴는지 확인한다.

네트워크 차이 — 도커 vs 쿠버네티스

파드는 떴지만, 브라우저에서 localhost:80을 열면 nginx 페이지가 나오지 않는다.
→ 네트워크가 분리되어 있기 때문이다.

도커: 컨테이너 내부와 외부의 네트워크가 서로 독립적으로 분리된다
쿠버네티스: 파드의 네트워크가 로컬 컴퓨터의 네트워크와 독립적으로 분리된다. 대신 파드 내부의 네트워크는 컨테이너들이 공유한다

도커는 컨테이너 단위로, 쿠버네티스는 파드 단위로 네트워크를 나눈다.
로컬 컴퓨터의 localhost와 파드 안의 localhost는 서로 다른 세계여서, 밖에서 localhost:80으로 접근해도 nginx에 연결되지 않는다.

nginx가 띄우는 웹페이지에 접근하는 방법

파드의 네트워크가 분리되어있으니, 접근하려면 두 가지 방법이 있다.

① 파드 내부로 들어가 접근한다 (파드 안에서 요청 보내기)
② 파드 내부 네트워크를 외부에서도 접속할 수 있도록 포트 포워딩한다. 즉, 로컬의 Port와 파드(컨테이너)의 Port를 "연결"시켜서 접속하는 방식이다

실습-① 파드 내부로 들어가 접근

kubectl exec -it nginx-pod -- bash

파드 안에서 요청을 보내면 정상 응답을 받는다.

curl localhost:80

파드 안에서의 localhost는 파드 내부 네트워크를 가리키므로 여기서는 nginx가 응답한다

실습-② 포트 포워딩

로컬의 80번 포트와 파드의 80번 포트를 연결한다.

sudo kubectl port-forward pod/nginx-pod 80:80 # pod/{pod 명칭}

이제 로컬 컴퓨터에서 localhost:80 으로 접근하면 nginx가 응답한다.

Pod 디버깅 방법

파드가 정상적으로 실행되지 않을 때는 다음 세 명령으로 디버깅을 해본다. (에러 메시지 확인, 어떤 에러인가 등등)

kubectl describe pods nginx-pod   # 파드 세부정보 조회 - 이벤트, 에러 메시지
kubectl logs nginx-pod            # 로그 확인
kubectl exec -it nginx-pod -- bash  # 파드 내부 접속 후 디버깅 (bash 대신 sh도 가능)

Deployment 매니페스트 작성

디플로이먼트로 파드를 배포한다.

# spring-deployment.yaml

apiVersion: apps/v1    # Pod(v1)와 달리 Deployment는 apps 그룹
kind: Deployment

metadata:
  name: spring-deployment

spec:                  # Deployment 세부정보
  replicas: 3          # Pod 3개 생성 (복제본) = 서버 개수

  selector:
    matchLabels:
      app: backend-app # 이 레이블을 가진 Pod가 관리 대상

  template:            # 배포할 Pod 정의
    metadata:
      labels:
        app: backend-app   # 생성될 Pod에 붙는 레이블 — selector와 일치해야 함
    spec:
      containers:      # 파드에 띄울 컨테이너 정보
        - name: spring-container
          image: (사용할 이미지)
          imagePullPolicy: IfNotPresent   # 로컬에 이미지가 있으면 재사용
          ports:
            - containerPort: 8080   # 파드 및 컨테이너의 포트

실행하고 확인한다.

kubectl apply -f spring-deployment.yaml
kubectl get deployment
kubectl get pods

서비스를 활용해 통신해보기

디플로이먼트로 파드 3개를 띄웠지만, 아직 외부에서 접근할 방법이 없다. 이 문제를 Service로 해결한다.

# spring-service.yaml

apiVersion: v1
kind: Service

metadata:
  name: spring-service

# 세부정보
spec:                    # 세부정보
  type: NodePort         # 서비스 종류

  selector:
    app: backend-app     # 해당 파드의 트래픽을 분배하겠다

  ports:
    - protocol: TCP      # 서비스에 접속하기 위한 프로토콜
      port: 8080         # 쿠버네티스 내부에서 Service에 접속하기 위한 포트
      targetPort: 8080   # 매핑하기 위한 파드의 포트
      nodePort: 30000    # 외부에서 사용자들이 접근하게 될 포트