Yaml
Ch 1. Yaml 이란
Ch 1. Yaml 이란
- Ch 1. Yaml 이란
- 00. Orientation
- Kubernetes YAML의 개념과 yq를 활용한 설정 파일 관리
- YAML이란?
- Kubernetes에서 YAML을 사용하는 이유
- YAML 파일과 Kubernetes 리소스의 관계
- YAML의 기본 구조
- Kubernetes YAML의 주요 필드
- YAML 작성 및 검증 환경 구성
- K3s란?
- Ubuntu 환경에서 K3s 설치
- kubectl과 Kubeconfig
- Visual Studio Code를 이용한 YAML 작성
- yq란?
- yq 버전 선택
- Ubuntu에서 yq 설치
- wget으로 yq 다운로드
- yq를 모든 경로에서 실행하도록 설정
- macOS에서 yq 설치
- yq 기본 사용법
- yq로 배열 조회
- yq로 YAML 값 변경
- Kubernetes YAML에서 yq 활용하기
- yq를 이용해 Deployment 이미지 변경하기
- kubectl과 yq를 함께 사용하기
- YAML을 JSON으로 변환하기
- 여러 Kubernetes 리소스를 하나의 YAML 파일로 관리하기
- YAML과 Helm의 관계
- 실무에서 YAML과 yq를 활용하는 방법
- YAML과 yq 사용 시 주의사항
- 정리
- 01. Yaml 정의
- YAML이란? YAML의 개념과 특징, 데이터 직렬화의 이해
- YAML의 정의
- YAML은 왜 마크업 언어가 아닐까?
- YAML의 핵심 구조: Key와 Value
- YAML의 기본 데이터 구조
- YAML이 사람이 읽기 쉬운 이유
- Human-Friendly와 Machine-Friendly의 차이
- YAML이 설정 파일에 적합한 이유
- 데이터 직렬화란?
- 역직렬화란?
- 직렬화가 필요한 이유
- 서로 다른 프로그래밍 언어가 동일한 데이터를 이해하는 과정
- 데이터 직렬화와 인코딩의 차이
- YAML이 모든 프로그래밍 언어에서 활용될 수 있는 이유
- YAML은 어디에서 활용될까?
- YAML 사용 시 알아야 할 주의사항
- 실무에서 YAML을 이해해야 하는 이유
- 정리
- 02. Yaml vs JSON
- YAML과 JSON 비교: 문법, 구조, 장단점과 실무 활용
- JSON이란?
- JSON의 기본 문법
- JSON은 반드시 중괄호로 시작해야 할까?
- JSON은 한 줄로 작성할 수 있다
- JSON에서 자주 발생하는 문법 오류
- JSON은 주석을 지원하지 않는다
- YAML과 JSON의 문법 비교
- YAML은 JSON보다 다양한 표현 기능을 제공한다
- YAML의 Anchor와 Alias
- YAML의 Merge Key
- YAML의 고급 기능이 오히려 단점이 되는 이유
- YAML은 여러 줄 문자열을 지원한다
- YAML은 여러 문서를 하나의 파일에 작성할 수 있다
- YAML과 JSON의 데이터 타입 비교
- YAML과 JSON의 파싱 성능 차이
- YAML과 JSON의 장단점 비교
- YAML과 JSON 전체 비교
- Kubernetes는 YAML만 지원할까?
- kubectl을 이용해 YAML과 JSON 출력 비교하기
- YAML과 JSON의 변환
- YAML과 JSON을 변환하는 방법
- JSON과 YAML을 Java에서 처리하는 방법
- 실무에서는 YAML과 JSON 중 무엇을 선택해야 할까?
- YAML과 JSON을 선택하는 기준
- 실무에서 주의해야 할 YAML과 JSON의 공통 문제
- 정리
- 03. Yaml in Kubernetes
- Kubernetes YAML과 선언형 리소스 관리
- Kubernetes와 YAML의 관계
- Kubernetes Manifest의 기본 구조
- apiVersion: 리소스의 API 버전
- kind: 생성할 리소스의 종류
- metadata: 리소스의 메타데이터
- spec: 리소스의 원하는 상태
- Pod YAML 전체 예제
- 선언형 관리란?
- 선언형 방식으로 Pod 생성하기
- 선언형 방식으로 Pod 삭제하기
- 명령형 관리란?
- 명령형 방식으로 Pod 생성하기
- 동일한 명령형 명령을 다시 실행하면 어떻게 될까?
- 선언형 방식으로 동일한 설정을 다시 적용하면 어떻게 될까?
- created, configured, unchanged의 차이
- 선언형 방식의 핵심: 멱등성
- 명령형과 선언형 관리 방식 비교
- YAML을 사용하면 무조건 선언형 방식일까?
- kubectl create와 kubectl apply의 차이
- 선언형 관리와 Reconciliation의 관계
- Pod를 직접 생성하는 경우와 Deployment를 사용하는 경우
- kubectl apply는 YAML 변경 사항을 자동으로 감지할까?
- 지속적인 선언형 관리를 위한 GitOps
- 실무에서 선언형 관리가 중요한 이유
- 실무에서 주의해야 할 사항
- Kubernetes YAML을 작성할 때 유용한 명령어
- 명령형과 선언형 관리 실습 전체 흐름
- 정리
- 00. Orientation
00. Orientation
Kubernetes YAML의 개념과 yq를 활용한 설정 파일 관리
Kubernetes에서는 Pod, Deployment, Service, ConfigMap, Secret 등 다양한 리소스를 생성하고 관리한다.
이러한 리소스를 생성하는 방법은 여러 가지가 있지만, 가장 일반적인 방법은 YAML 파일을 작성하여 Kubernetes API에 적용하는 것이다.
예를 들어 애플리케이션을 실행하기 위해 Deployment를 생성하려면 다음과 같은 YAML 파일을 작성할 수 있다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:1.27
ports:
- containerPort: 80
이 파일에는 애플리케이션을 어떤 이미지로 실행할 것인지, Pod를 몇 개 생성할 것인지, 어떤 Label을 사용할 것인지 등의 설정이 정의되어 있다.
Kubernetes는 YAML 파일에 작성된 설정을 기반으로 리소스를 생성하고, 선언된 상태가 유지되도록 지속적으로 관리한다.
하지만 YAML을 단순히 Kubernetes의 설정 파일 형식으로만 이해하면 활용 범위를 제대로 파악하기 어렵다.
YAML은 Kubernetes 전용으로 만들어진 형식이 아니라, 다양한 애플리케이션과 시스템에서 데이터를 표현하기 위해 사용하는 범용 데이터 직렬화 형식이다.
Spring Boot의 application.yml, Docker Compose의 compose.yaml, GitHub Actions의 Workflow 파일에서도 YAML을 사용한다.
따라서 YAML의 기본 구조와 문법을 이해하면 Kubernetes뿐 아니라 여러 개발 환경에서 설정 파일을 더욱 정확하고 효율적으로 관리할 수 있다.
또한 설정 파일의 규모가 커지면 직접 내용을 검색하거나 수정하는 작업이 번거로워질 수 있다.
이러한 상황에서는 YAML을 명령어로 조회하고 수정할 수 있는 yq를 활용할 수 있다.
이번에는 YAML의 기본 개념과 Kubernetes에서의 역할을 살펴보고, 실습 환경을 구성한 뒤 yq를 설치하여 YAML 파일을 다루는 방법까지 알아본다.
YAML이란?
YAML은 YAML Ain’t Markup Language의 약자로, 데이터를 표현하기 위한 사람이 읽기 쉬운 데이터 직렬화 형식이다.
여기서 데이터 직렬화란 객체나 자료구조를 저장하거나 전달할 수 있는 형태로 변환하는 것을 의미한다.
예를 들어 다음과 같은 데이터를 표현한다고 가정하자.
애플리케이션 이름: my-app
서버 포트: 8080
실행 환경: production
이를 YAML로 표현하면 다음과 같다.
application:
name: my-app
port: 8080
environment: production
YAML은 들여쓰기를 사용하여 데이터 사이의 계층 구조를 표현한다.
따라서 중첩된 데이터를 비교적 간결하게 작성할 수 있다.
JSON과 YAML 비교
동일한 데이터를 JSON으로 표현하면 다음과 같다.
{
"application": {
"name": "my-app",
"port": 8080,
"environment": "production"
}
}
YAML에서는 다음과 같이 작성할 수 있다.
application:
name: my-app
port: 8080
environment: production
두 형식은 동일한 데이터를 표현하지만 문법에서 차이가 있다.
| 구분 | YAML | JSON |
|---|---|---|
| 계층 표현 | 들여쓰기 | 중괄호 |
| 배열 표현 | 하이픈 또는 대괄호 | 대괄호 |
| 문자열 표현 | 따옴표 생략 가능 | 큰따옴표 필요 |
| 주석 | 지원 | 표준 JSON에서는 지원하지 않음 |
| 가독성 | 사람이 읽기 편리함 | 구조가 명시적임 |
| 대표 활용 | 설정 파일, Kubernetes | API 응답, 데이터 교환 |
YAML은 중괄호와 쉼표를 반복해서 작성할 필요가 없기 때문에 복잡한 설정을 읽기 쉽게 표현할 수 있다.
반면 들여쓰기가 데이터 구조를 결정하므로 작은 공백 차이로도 의미가 달라질 수 있다는 점에 주의해야 한다.
Kubernetes에서 YAML을 사용하는 이유
Kubernetes는 다양한 종류의 리소스를 관리한다.
대표적인 리소스는 다음과 같다.
| 리소스 | 역할 |
|---|---|
| Pod | 컨테이너를 실행하는 기본 단위 |
| Deployment | 애플리케이션 배포와 업데이트 관리 |
| StatefulSet | 안정적인 식별자와 스토리지가 필요한 애플리케이션 관리 |
| DaemonSet | 특정 Node에 Pod를 실행 |
| Service | Pod에 대한 네트워크 접근 제공 |
| ConfigMap | 일반 설정 데이터 관리 |
| Secret | 비밀번호와 토큰 등 민감한 데이터 관리 |
| PersistentVolumeClaim | 영구 스토리지 요청 |
| HorizontalPodAutoscaler | Pod 수량 자동 조정 |
| Job | 완료를 목적으로 하는 작업 실행 |
| CronJob | 주기적인 작업 실행 |
각 리소스는 서로 다른 목적을 가지고 있으며, 필요한 설정도 다르다.
Kubernetes에서는 이러한 리소스의 원하는 상태를 YAML 파일로 선언할 수 있다.
flowchart TD
A["YAML 설정 파일"] --> B["kubectl apply"]
B --> C["Kubernetes API Server"]
C --> D["Deployment"]
C --> E["Service"]
C --> F["ConfigMap"]
C --> G["Secret"]
D --> H["Pod 생성 및 관리"]
E --> I["네트워크 트래픽 연결"]
F --> J["애플리케이션 설정 제공"]
G --> K["민감한 설정 제공"]
예를 들어 Deployment를 생성하는 YAML 파일은 다음과 같다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
ports:
- containerPort: 80
이 설정을 Kubernetes에 적용하면 Kubernetes는 Pod 2개를 실행하는 Deployment를 생성한다.
kubectl apply -f deployment.yaml
정상적으로 생성되면 다음과 같은 메시지가 출력된다.
deployment.apps/nginx-deployment created
여기서 중요한 점은 YAML 파일이 단순한 실행 명령어가 아니라 시스템이 유지해야 하는 원하는 상태를 선언한다는 것이다.
예를 들어 replicas: 2로 설정했다면 Kubernetes는 Pod 2개가 유지되도록 관리한다.
Pod 하나가 비정상 종료되면 Kubernetes Controller는 실제 상태와 원하는 상태의 차이를 확인하고 새로운 Pod를 생성한다.
flowchart TD
A["YAML: replicas = 2"] --> B["Deployment Controller"]
B --> C["현재 Pod 수량 확인"]
C --> D{"Pod가 2개인가?"}
D -->|"예"| E["현재 상태 유지"]
D -->|"아니오"| F["부족한 Pod 생성"]
F --> C
이러한 동작은 Kubernetes의 선언적 관리 방식과 Reconciliation 구조를 이해하는 데 중요한 개념이다.
YAML 파일과 Kubernetes 리소스의 관계
YAML은 설정을 표현하는 형식이고, Kubernetes Resource는 실제 Kubernetes API가 관리하는 객체이다.
두 개념은 구분해서 이해해야 한다.
YAML
→ 데이터를 표현하는 형식
Kubernetes Manifest
→ Kubernetes 리소스를 정의한 설정
Kubernetes Resource
→ API Server에 등록되어 관리되는 객체
예를 들어 다음 파일은 YAML 문법을 사용한 Kubernetes Manifest이다.
apiVersion: v1
kind: ConfigMap
metadata:
name: my-config
data:
APP_ENV: production
LOG_LEVEL: INFO
여기서 YAML은 데이터를 표현하는 형식일 뿐이다.
apiVersion, kind, metadata, data가 Kubernetes에서 어떤 의미를 가지는지는 Kubernetes API가 결정한다.
즉 YAML 문법을 정확하게 작성했다고 해서 반드시 올바른 Kubernetes Manifest가 되는 것은 아니다.
YAML 문법은 올바르더라도 Kubernetes가 지원하지 않는 필드나 잘못된 리소스 구조를 사용하면 API Server에서 오류가 발생할 수 있다.
따라서 Kubernetes 설정 파일을 작성할 때는 다음 두 가지를 모두 이해해야 한다.
- YAML의 문법과 데이터 구조
- Kubernetes 리소스별 API 구조와 필드 의미
YAML의 기본 구조
YAML은 기본적으로 Key-Value 형태로 데이터를 표현한다.
Key-Value
가장 단순한 형태는 다음과 같다.
name: my-app
port: 8080
enabled: true
각 항목은 다음과 같은 의미를 가진다.
Key: Value
예를 들어 다음과 같다.
port: 8080
port라는 Key에 8080이라는 값을 지정한 것이다.
중첩 구조
YAML은 들여쓰기를 사용해 계층 구조를 표현한다.
server:
port: 8080
address: 0.0.0.0
database:
host: localhost
port: 3306
이 구조는 다음과 같이 해석할 수 있다.
flowchart TD
A["YAML Document"] --> B["server"]
A --> C["database"]
B --> D["port: 8080"]
B --> E["address: 0.0.0.0"]
C --> F["host: localhost"]
C --> G["port: 3306"]
이때 중요한 것은 같은 계층에 속한 항목은 같은 수준으로 들여쓰기해야 한다는 점이다.
일반적으로 공백 2칸을 사용하는 방식이 널리 사용된다.
YAML에서는 들여쓰기에 Tab 문자를 사용하지 않고 공백을 사용해야 한다.
배열
YAML에서 배열은 하이픈(-)을 사용해 표현할 수 있다.
servers:
- server1
- server2
- server3
객체를 배열로 표현할 수도 있다.
containers:
- name: nginx
image: nginx:1.27
- name: redis
image: redis:7
Kubernetes에서는 하나의 Pod에 여러 컨테이너를 정의하거나 환경 변수, Volume 등을 설정할 때 이러한 배열 구조를 자주 사용한다.
주석
YAML에서는 #으로 주석을 작성한다.
# 애플리케이션 실행 환경
environment: production
# HTTP 포트
port: 8080
주석은 설정의 의미를 설명하는 데 유용하다.
다만 중요한 비즈니스 규칙이나 운영 절차를 주석에만 의존하기보다 설정 자체를 이해하기 쉽게 구성하는 것이 좋다.
데이터 타입
YAML은 문자열, 숫자, Boolean, Null 등의 값을 표현할 수 있다.
name: my-app
port: 8080
enabled: true
description: null
값을 명확하게 문자열로 처리하고 싶다면 따옴표를 사용한다.
port: "8080"
enabled: "true"
이 경우 8080과 true는 문자열로 표현된다.
특히 Kubernetes 환경 변수의 value 필드는 문자열을 기대하므로 다음처럼 명시하는 것이 안전하다.
env:
- name: SERVER_PORT
value: "8080"
- name: FEATURE_ENABLED
value: "true"
반대로 다음 설정은 환경 변수의 값에 숫자나 Boolean을 직접 지정하므로 Kubernetes API 검증에서 문제가 발생할 수 있다.
env:
- name: SERVER_PORT
value: 8080
YAML의 데이터 타입과 Kubernetes API 필드의 데이터 타입은 함께 고려해야 한다.
Kubernetes YAML의 주요 필드
Kubernetes Manifest에서는 다음 필드들이 자주 등장한다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:1.27
각 필드의 의미는 다음과 같다.
| 필드 | 설명 |
|---|---|
apiVersion | 사용할 Kubernetes API 버전 |
kind | 생성할 리소스 종류 |
metadata | 리소스 이름, Namespace, Label 등의 메타데이터 |
spec | 리소스의 원하는 상태 |
selector | 관리 대상 리소스를 선택하는 조건 |
template | 생성할 Pod의 템플릿 |
containers | Pod에서 실행할 컨테이너 목록 |
apiVersion, kind, metadata, spec은 많은 Kubernetes 리소스에서 공통적으로 사용된다.
다만 모든 리소스가 같은 구조를 사용하는 것은 아니다.
예를 들어 ConfigMap은 일반적으로 spec 대신 data 필드를 사용한다.
apiVersion: v1
kind: ConfigMap
metadata:
name: application-config
data:
APP_ENV: production
따라서 Kubernetes Manifest를 작성할 때는 리소스 종류에 맞는 API 구조를 사용해야 한다.
YAML 작성 및 검증 환경 구성
YAML 파일 자체를 작성하는 데 반드시 Kubernetes 클러스터가 필요한 것은 아니다.
하지만 작성한 Manifest를 실제로 적용하고 Kubernetes 리소스의 동작을 확인하려면 Kubernetes 환경이 필요하다.
이번 구성에서는 다음 도구를 사용한다.
| 도구 | 목적 |
|---|---|
| Ubuntu Linux | 명령어 실행 환경 |
| K3s | 경량 Kubernetes 클러스터 |
| kubectl | Kubernetes 리소스 관리 |
| Visual Studio Code | YAML 파일 작성 |
| yq | YAML 파일 조회 및 수정 |
이미 Kubernetes 클러스터가 있다면 K3s를 별도로 설치하지 않고 기존 환경을 사용할 수 있다.
K3s란?
K3s는 경량 Kubernetes 배포판이다.
일반적인 Kubernetes 환경보다 간단하게 설치할 수 있도록 구성되어 있으며, 개발 및 테스트 환경이나 리소스가 제한적인 환경에서 활용할 수 있다.
K3s는 Kubernetes의 핵심 기능을 제공하므로 Pod, Deployment, Service, ConfigMap 같은 리소스를 생성하고 관리할 수 있다.
flowchart TD
A["Ubuntu Linux"] --> B["K3s"]
B --> C["Kubernetes API Server"]
B --> D["Kubernetes Controller"]
B --> E["Container Runtime"]
C --> F["Deployment"]
C --> G["Service"]
C --> H["ConfigMap"]
F --> I["Pod"]
단일 서버에 K3s를 설치하면 Kubernetes의 핵심 구성 요소를 포함하는 클러스터를 구성할 수 있다.
다만 실제 운영용 고가용성 클러스터를 구성할 때는 추가 서버, 네트워크, 스토리지 및 장애 복구 전략을 별도로 고려해야 한다.
Ubuntu 환경에서 K3s 설치
K3s 설치
K3s는 설치 스크립트를 제공한다.
curl -sfL https://get.k3s.io | sh -
이 명령어는 설치 스크립트를 다운로드하고 실행한다.
각 요소의 의미는 다음과 같다.
| 항목 | 설명 |
|---|---|
curl | HTTP 요청으로 파일을 다운로드 |
-s | 진행 정보를 최소화 |
-f | HTTP 오류가 발생하면 실패 처리 |
-L | Redirect 응답을 따라 이동 |
sh - | 표준 입력으로 받은 스크립트 실행 |
외부 설치 스크립트를 실행하는 방식이므로 운영 환경에서는 스크립트와 설치 버전을 검토하고 조직의 보안 정책에 맞게 설치해야 한다.
설치가 완료되면 K3s 서비스가 실행되고 Kubernetes를 관리하는 데 필요한 명령어도 제공된다.
K3s 상태 확인
sudo systemctl status k3s
정상적으로 실행되고 있다면 다음과 같은 상태를 확인할 수 있다.
Active: active (running)
Node 확인
sudo k3s kubectl get nodes
예상 출력:
NAME STATUS ROLES AGE VERSION
ubuntu01 Ready control-plane,master 5m v1.xx.x+k3s1
Kubernetes Node가 Ready 상태라면 기본적인 클러스터 구성이 정상적으로 이루어졌음을 확인할 수 있다.
Pod 확인
sudo k3s kubectl get pods -A
-A는 모든 Namespace의 Pod를 조회하는 옵션이다.
시스템 Pod가 정상적으로 실행되는지 확인할 수 있다.
kubectl과 Kubeconfig
kubectl은 Kubernetes API Server와 통신하여 리소스를 조회하거나 변경하는 명령어이다.
flowchart LR
A["kubectl"] --> B["Kubeconfig"]
B --> C["Kubernetes API Server"]
C --> D["Kubernetes Resources"]
K3s는 기본적으로 다음 위치에 Kubeconfig 파일을 생성한다.
/etc/rancher/k3s/k3s.yaml
이 파일에는 클러스터의 접속 주소와 인증 정보 등이 포함되어 있다.
K3s에서 제공하는 kubectl은 기본적으로 해당 Kubeconfig를 사용한다.
별도로 설치한 kubectl을 사용한다면 Kubeconfig 경로를 지정해야 할 수 있다.
sudo kubectl \
--kubeconfig /etc/rancher/k3s/k3s.yaml \
get nodes
Kubeconfig는 클러스터 접근 권한을 포함할 수 있으므로 외부에 노출되지 않도록 주의해야 한다.
특히 K3s의 관리자 Kubeconfig는 높은 권한을 가지므로 일반적인 애플리케이션 설정 파일과 동일하게 취급해서는 안 된다.
Visual Studio Code를 이용한 YAML 작성
YAML은 일반 텍스트 파일이므로 다양한 편집기에서 작성할 수 있다.
하지만 Kubernetes Manifest처럼 중첩 구조가 복잡한 파일은 YAML 문법을 지원하는 편집기를 사용하는 것이 효율적이다.
Visual Studio Code는 YAML 작성에 필요한 다양한 편의 기능을 제공한다.
대표적으로 다음 기능을 활용할 수 있다.
- 문법 하이라이팅
- 자동 들여쓰기
- YAML 구조 확인
- 문법 오류 표시
- 파일 검색
- Kubernetes 설정 파일 편집
YAML 관련 확장 기능을 설치하면 스키마 검증이나 자동 완성 기능도 활용할 수 있다.
들여쓰기 주의사항
다음 YAML은 잘못된 예시이다.
server:
port: 8080
address: localhost
port와 address가 같은 계층에 있어야 하지만 들여쓰기가 다르다.
올바른 YAML은 다음과 같다.
server:
port: 8080
address: localhost
YAML은 들여쓰기만으로 데이터 구조가 결정되기 때문에 편집기의 자동 들여쓰기와 문법 검증 기능을 활용하는 것이 좋다.
yq란?
yq는 YAML 파일을 명령어로 조회하고 수정할 수 있는 CLI 도구이다.
Linux에서 텍스트를 처리할 때 grep, sed, awk 같은 명령어를 자주 사용한다.
하지만 YAML은 단순한 문자열이 아니라 계층 구조를 가진 데이터이기 때문에 일반적인 텍스트 검색만으로 원하는 값을 정확하게 찾아내기 어려울 수 있다.
예를 들어 다음 YAML을 살펴보자.
application:
name: my-app
server:
port: 8080
database:
host: localhost
port: 3306
이 파일에서 port라는 문자열을 검색하면 두 값이 모두 검색된다.
grep port application.yaml
출력:
port: 8080
port: 3306
하지만 원하는 값이 애플리케이션 서버의 포트라면 다음 경로를 기준으로 조회해야 한다.
application.server.port
이때 yq를 사용하면 다음처럼 특정 경로의 값만 조회할 수 있다.
yq '.application.server.port' application.yaml
출력:
8080
즉 yq는 YAML 파일을 단순한 문자열이 아니라 구조화된 데이터로 해석하여 필요한 값을 추출하거나 변경하는 도구이다.
flowchart TD
A["YAML 파일"] --> B["yq"]
B --> C["특정 값 조회"]
B --> D["조건 검색"]
B --> E["값 변경"]
B --> F["파일 병합"]
B --> G["JSON 변환"]
yq는 Go 기반의 실행 파일로 배포되며 Linux, macOS, Windows 등 여러 운영체제에서 사용할 수 있다.
yq 버전 선택
yq는 버전에 따라 명령어와 옵션의 동작이 달라질 수 있다.
특히 과거 v3와 v4는 문법 차이가 있으므로 예제를 실행할 때 버전을 확인하는 것이 중요하다.
여기서는 다음 버전을 기준으로 한다.
yq v4.19.1
v4.19.1은 특정 버전의 사용법을 일관되게 확인하기 위한 기준이다.
현재 배포되는 최신 버전과는 다를 수 있으므로, 실제 운영 환경에서는 사용하는 버전의 변경 사항과 호환성을 확인해야 한다.
또한 v4.18.1부터는 별도의 eval 명령어를 명시하지 않아도 기본 평가 명령으로 처리하는 방식이 지원된다.
따라서 다음 두 명령어를 비슷한 용도로 사용할 수 있다.
yq eval '.metadata.name' deployment.yaml
yq '.metadata.name' deployment.yaml
다만 명령어의 명확성을 위해 처음에는 eval을 명시해서 사용하는 것도 좋은 방법이다.
Ubuntu에서 yq 설치
yq는 GitHub Releases에서 운영체제와 CPU 아키텍처에 맞는 실행 파일을 다운로드하여 설치할 수 있다.
운영체제 및 아키텍처 확인
먼저 실행 환경을 확인한다.
uname -s
Ubuntu에서는 일반적으로 다음과 같이 출력된다.
Linux
CPU 아키텍처를 확인한다.
uname -m
일반적인 64비트 x86 서버에서는 다음과 같이 출력된다.
x86_64
ARM64 환경에서는 다음과 같이 출력될 수 있다.
aarch64
yq에서 사용하는 대표적인 바이너리 이름은 다음과 같다.
| 환경 | 바이너리 |
|---|---|
| Linux x86-64 | yq_linux_amd64 |
| Linux ARM64 | yq_linux_arm64 |
| macOS Intel | yq_darwin_amd64 |
| macOS Apple Silicon | yq_darwin_arm64 |
| Windows x86-64 | yq_windows_amd64.exe |
따라서 실행 환경에 맞는 바이너리를 선택해야 한다.
wget으로 yq 다운로드
Ubuntu x86-64 환경을 기준으로 yq v4.19.1을 다운로드해보자.
1. 버전 및 바이너리 지정
VERSION=v4.19.1
BINARY=yq_linux_amd64
변수의 의미는 다음과 같다.
| 변수 | 값 | 설명 |
|---|---|---|
VERSION | v4.19.1 | 다운로드할 yq 버전 |
BINARY | yq_linux_amd64 | Linux x86-64 실행 파일 |
2. 실행 파일 다운로드
wget \
"https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}" \
-O yq_linux_amd64
wget은 지정한 URL의 파일을 다운로드하는 명령어이다.
여기서 -O는 다운로드한 파일을 어떤 이름으로 저장할지 지정하는 옵션이다.
명령어가 정상적으로 실행되면 현재 디렉터리에 다음 파일이 생성된다.
yq_linux_amd64
파일이 존재하는지 확인한다.
ls -lh yq_linux_amd64
3. 실행 권한 부여
다운로드한 파일에 실행 권한을 부여한다.
chmod +x yq_linux_amd64
chmod는 파일의 권한을 변경하는 명령어이다.
+x는 실행 권한을 추가한다는 의미이다.
4. 실행 확인
./yq_linux_amd64 --version
예상 출력:
yq (https://github.com/mikefarah/yq/) version v4.19.1
이제 다운로드한 yq 실행 파일이 정상적으로 동작하는 것을 확인할 수 있다.
yq를 모든 경로에서 실행하도록 설정
현재 상태에서는 실행 파일이 있는 디렉터리에서 다음과 같이 실행해야 한다.
./yq_linux_amd64 --version
하지만 실제 작업에서는 어떤 디렉터리에서도 yq 명령어를 실행할 수 있는 것이 편리하다.
이를 위해 실행 파일을 PATH에 포함된 디렉터리로 이동한다.
일반적으로 /usr/local/bin을 사용할 수 있다.
sudo mv yq_linux_amd64 /usr/local/bin/yq
설치된 파일을 확인한다.
ls -l /usr/local/bin/yq
이제 현재 디렉터리와 관계없이 다음 명령어를 사용할 수 있다.
yq --version
출력:
yq (https://github.com/mikefarah/yq/) version v4.19.1
실제 실행되는 yq의 위치를 확인하려면 다음 명령어를 사용한다.
which yq
예상 출력:
/usr/local/bin/yq
/usr/local/bin에 설치하는 이유
Linux는 명령어를 실행할 때 PATH 환경 변수에 등록된 디렉터리에서 실행 파일을 검색한다.
현재 PATH를 확인할 수 있다.
echo "$PATH"
출력 예시:
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/bin
/usr/local/bin이 PATH에 포함되어 있다면 해당 디렉터리에 설치된 yq를 어디서든 실행할 수 있다.
flowchart TD
A["터미널에서 yq 입력"] --> B["PATH 검색"]
B --> C["/usr/local/bin/yq 발견"]
C --> D["yq 실행"]
/usr/local/bin에 실행 파일을 직접 설치할 때는 파일의 출처와 무결성을 확인하고, 필요한 권한만 부여하는 것이 좋다.
macOS에서 yq 설치
macOS에서도 yq를 사용할 수 있다.
Homebrew가 설치되어 있다면 다음 명령어로 설치할 수 있다.
brew install yq
설치된 버전을 확인한다.
yq --version
다만 Homebrew는 일반적으로 사용 가능한 최신 버전을 설치하므로 v4.19.1과 정확히 일치하지 않을 수 있다.
특정 버전이 필요하다면 GitHub Releases에서 해당 버전의 바이너리를 다운로드하는 방식으로 설치할 수 있다.
Apple Silicon 환경에서는 darwin_arm64, Intel Mac에서는 darwin_amd64 바이너리를 선택해야 한다.
실무에서는 CI/CD 서버와 로컬 개발 환경의 yq 버전이 다를 경우 예상하지 못한 차이가 발생할 수 있으므로, 자동화 스크립트에서 사용하는 도구 버전을 명확하게 관리하는 것이 좋다.
yq 기본 사용법
yq 설치가 완료되었다면 간단한 YAML 파일을 작성하여 데이터를 조회해보자.
다음 파일을 생성한다.
application.yaml
application:
name: my-app
version: 1.0.0
server:
port: 8080
host: localhost
features:
- login
- payment
- notification
database:
host: localhost
port: 3306
username: admin
전체 내용 출력
yq '.' application.yaml
.은 전체 YAML 문서를 의미한다.
따라서 파일의 전체 내용을 출력한다.
특정 필드 조회
애플리케이션 이름만 확인하려면 다음 명령어를 사용한다.
yq '.application.name' application.yaml
출력:
my-app
서버 포트를 확인하려면 다음과 같이 작성한다.
yq '.application.server.port' application.yaml
출력:
8080
데이터베이스 포트도 같은 방식으로 조회할 수 있다.
yq '.database.port' application.yaml
출력:
3306
이처럼 yq에서는 .으로 시작하는 경로 표현식을 사용하여 중첩된 데이터에 접근한다.
yq로 배열 조회
YAML의 배열도 yq로 조회할 수 있다.
앞서 작성한 파일에는 다음과 같은 배열이 있다.
features:
- login
- payment
- notification
배열 전체를 조회한다.
yq '.application.features' application.yaml
출력:
- login
- payment
- notification
특정 인덱스에 접근할 수도 있다.
yq '.application.features[0]' application.yaml
출력:
login
yq '.application.features[1]' application.yaml
출력:
payment
배열의 모든 요소를 개별적으로 출력하려면 다음과 같이 작성한다.
yq '.application.features[]' application.yaml
출력:
login
payment
notification
이러한 기능은 Kubernetes Deployment에 정의된 여러 컨테이너 중 특정 컨테이너의 이미지나 이름을 확인할 때도 활용할 수 있다.
yq로 YAML 값 변경
yq는 YAML 파일의 값을 조회하는 것뿐 아니라 변경할 수도 있다.
예를 들어 다음 설정을 변경한다고 가정하자.
application:
server:
port: 8080
서버 포트를 9090으로 변경하려면 다음 명령어를 사용한다.
yq '.application.server.port = 9090' application.yaml
이 명령어는 수정된 YAML을 표준 출력으로 보여준다.
원본 파일을 직접 수정하지는 않는다.
실제 파일에 변경 내용을 반영하려면 -i 옵션을 사용해야 한다.
yq -i '.application.server.port = 9090' application.yaml
이후 값을 확인한다.
yq '.application.server.port' application.yaml
출력:
9090
-i는 원본 파일에 변경 결과를 반영하는 옵션이다.
설정 파일을 직접 수정하기 때문에 중요한 파일에 사용하기 전에는 Git 등을 통해 변경 이력을 관리하거나 백업해 두는 것이 좋다.
Kubernetes YAML에서 yq 활용하기
실제 Kubernetes Manifest에서도 yq를 활용할 수 있다.
예를 들어 다음과 같은 Deployment가 있다고 가정하자.
deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:1.27
ports:
- containerPort: 80
resources:
requests:
cpu: "100m"
memory: "128Mi"
limits:
cpu: "500m"
memory: "256Mi"
Deployment 이름 조회
yq '.metadata.name' deployment.yaml
출력:
my-app
replicas 조회
yq '.spec.replicas' deployment.yaml
출력:
3
컨테이너 이미지 조회
yq '.spec.template.spec.containers[0].image' deployment.yaml
출력:
nginx:1.27
CPU requests 조회
yq '.spec.template.spec.containers[0].resources.requests.cpu' deployment.yaml
출력:
100m
Memory limits 조회
yq '.spec.template.spec.containers[0].resources.limits.memory' deployment.yaml
출력:
256Mi
이처럼 Kubernetes YAML의 구조를 이해하면 yq를 이용해 원하는 설정을 정확하게 추출할 수 있다.
yq를 이용해 Deployment 이미지 변경하기
Deployment YAML에 정의된 컨테이너 이미지를 변경해보자.
기존 설정은 다음과 같다.
containers:
- name: my-app
image: nginx:1.27
yq를 사용하면 특정 필드만 수정할 수 있다.
yq -i \
'.spec.template.spec.containers[0].image = "nginx:1.28"' \
deployment.yaml
변경된 값을 확인한다.
yq '.spec.template.spec.containers[0].image' deployment.yaml
출력:
nginx:1.28
여기서 중요한 점은 yq가 Kubernetes 클러스터의 리소스를 직접 수정하는 도구는 아니라는 것이다.
yq는 YAML 파일을 수정한다.
수정한 파일을 Kubernetes에 반영하려면 별도의 kubectl apply 명령이 필요하다.
kubectl apply -f deployment.yaml
전체 흐름은 다음과 같다.
flowchart TD
A["deployment.yaml"] --> B["yq로 이미지 변경"]
B --> C["수정된 deployment.yaml"]
C --> D["kubectl apply"]
D --> E["Kubernetes API Server"]
E --> F["Deployment 업데이트"]
F --> G["Rolling Update 진행"]
이러한 방식은 배포 자동화 스크립트에서 이미지 태그나 replicas를 변경할 때 활용할 수 있다.
다만 여러 배포 프로세스가 동일한 파일을 수정한다면 변경 충돌이 발생할 수 있으므로, 실제 운영에서는 GitOps나 Helm 같은 설정 관리 방식과 함께 사용하는 것이 좋다.
kubectl과 yq를 함께 사용하기
yq는 로컬 YAML 파일뿐 아니라 kubectl이 출력한 YAML 데이터에도 적용할 수 있다.
예를 들어 Kubernetes에 존재하는 Deployment를 조회해보자.
kubectl get deployment my-app -o yaml
이 명령어는 Kubernetes API Server에 저장된 Deployment 정보를 YAML 형식으로 출력한다.
출력에는 사용자가 작성한 설정뿐 아니라 Kubernetes가 추가하거나 관리하는 메타데이터와 상태 정보도 포함될 수 있다.
이 결과를 yq에 전달하면 필요한 값만 추출할 수 있다.
실행 중인 Deployment의 이미지 조회
kubectl get deployment my-app -o yaml |
yq '.spec.template.spec.containers[0].image'
출력 예시:
nginx:1.28
Deployment의 replicas 조회
kubectl get deployment my-app -o yaml |
yq '.spec.replicas'
출력 예시:
3
Deployment의 Ready replicas 조회
kubectl get deployment my-app -o yaml |
yq '.status.readyReplicas'
출력 예시:
3
여기서 spec.replicas와 status.readyReplicas는 서로 다른 의미를 가진다.
| 항목 | 의미 |
|---|---|
spec.replicas | 사용자가 원하는 Pod 수 |
status.readyReplicas | 현재 Ready 상태인 Pod 수 |
예를 들어 다음과 같은 상황이 있을 수 있다.
spec.replicas: 3
status.readyReplicas: 2
이는 3개의 Pod를 유지하려고 하지만 현재 Ready 상태인 Pod는 2개라는 의미이다.
이처럼 kubectl과 yq를 함께 사용하면 Kubernetes의 원하는 상태와 실제 상태를 비교하는 자동화 스크립트도 작성할 수 있다.
YAML을 JSON으로 변환하기
yq는 YAML 데이터를 JSON으로 변환할 수도 있다.
yq -o=json '.' application.yaml
예를 들어 다음 YAML을 변환한다고 가정하자.
application:
name: my-app
port: 8080
변환 결과는 다음과 같다.
{
"application": {
"name": "my-app",
"port": 8080
}
}
반대로 JSON 파일을 YAML로 변환할 수도 있다.
yq -P -o=yaml '.' application.json
YAML은 사람이 설정을 작성하는 데 편리하고, JSON은 다양한 API와 프로그램에서 데이터 교환 형식으로 활용된다.
두 형식을 변환할 수 있으면 서로 다른 시스템 사이에서 설정을 전달하거나 자동화하는 데 도움이 된다.
여러 Kubernetes 리소스를 하나의 YAML 파일로 관리하기
YAML에서는 ---를 사용해 여러 문서를 구분할 수 있다.
Kubernetes에서도 하나의 파일에 여러 리소스를 정의할 때 이 기능을 사용할 수 있다.
예를 들어 다음 파일에는 ConfigMap과 Deployment가 함께 정의되어 있다.
application.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: my-app-config
data:
APP_ENV: production
LOG_LEVEL: INFO
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 2
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:1.27
envFrom:
- configMapRef:
name: my-app-config
---를 기준으로 두 개의 YAML 문서가 구분된다.
flowchart TD
A["application.yaml"] --> B["Document 1"]
A --> C["Document 2"]
B --> D["ConfigMap"]
C --> E["Deployment"]
D --> F["환경 변수 설정"]
E --> G["Pod 생성"]
두 리소스를 한 번에 적용할 수 있다.
kubectl apply -f application.yaml
출력 예시:
configmap/my-app-config created
deployment.apps/my-app created
이처럼 하나의 YAML 파일에 여러 리소스를 작성할 수 있으며, 리소스별로 파일을 나누어 관리할 수도 있다.
실무에서는 설정의 규모와 배포 단위에 따라 적절한 구조를 선택한다.
YAML과 Helm의 관계
Kubernetes 환경에서는 YAML과 함께 Helm이라는 도구도 자주 사용한다.
Helm은 Kubernetes 애플리케이션을 패키징하고 배포하기 위한 패키지 관리자이다.
YAML이 Kubernetes 리소스를 선언하는 형식이라면, Helm은 여러 Kubernetes Manifest를 템플릿으로 관리하고 배포할 수 있도록 도와준다.
예를 들어 개발 환경과 운영 환경에서 사용하는 이미지 태그나 replicas가 다를 수 있다.
개발 환경에서는 다음과 같이 설정할 수 있다.
replicaCount: 1
image:
repository: nginx
tag: "1.27"
운영 환경에서는 다음처럼 설정할 수 있다.
replicaCount: 3
image:
repository: nginx
tag: "1.28"
Helm은 이러한 값을 기반으로 Kubernetes Manifest를 생성한다.
flowchart TD
A["Helm Chart"] --> B["YAML Templates"]
C["values.yaml"] --> D["Helm Rendering"]
B --> D
D --> E["Kubernetes Manifest"]
E --> F["Kubernetes API Server"]
따라서 Helm을 제대로 활용하려면 기본적으로 YAML 문법과 Kubernetes 리소스 구조를 이해해야 한다.
Helm의 템플릿 문법은 일반 YAML과 다르며, 템플릿을 렌더링한 최종 결과가 유효한 Kubernetes Manifest가 되어야 한다.
실무에서 YAML과 yq를 활용하는 방법
YAML과 yq는 단순히 설정 파일을 작성하거나 값을 조회하는 용도 외에도 다양한 상황에서 활용할 수 있다.
1. 배포 전 설정 검증
배포하기 전에 Kubernetes Manifest의 기본적인 오류를 확인할 수 있다.
kubectl apply --dry-run=client -f deployment.yaml
이 명령어는 리소스를 실제로 생성하지 않고 적용 가능 여부를 사전에 확인하는 데 사용한다.
다만 클라이언트 측 검증만으로 모든 서버 측 검증이나 Admission 정책까지 확인할 수 있는 것은 아니다.
API Server의 검증까지 확인하려면 다음 명령어를 사용할 수 있다.
kubectl apply --dry-run=server -f deployment.yaml
서버 측 Dry Run은 클러스터에 접근할 수 있어야 하며, 관련 Admission 구성도 이를 지원해야 한다.
2. 배포 이미지 확인
현재 Deployment에서 사용 중인 이미지를 확인할 수 있다.
kubectl get deployment my-app -o yaml |
yq '.spec.template.spec.containers[].image'
여러 컨테이너가 정의되어 있다면 각 컨테이너의 이미지가 출력된다.
3. CPU와 Memory 설정 확인
kubectl get deployment my-app -o yaml |
yq '.spec.template.spec.containers[].resources'
이 명령어를 사용하면 컨테이너의 requests와 limits 설정을 확인할 수 있다.
4. CI/CD에서 이미지 태그 변경
배포 파이프라인에서 특정 이미지 버전을 적용해야 한다고 가정하자.
IMAGE_TAG=1.2.0
IMAGE_TAG="$IMAGE_TAG" yq -i \
'.spec.template.spec.containers[0].image = "registry.example.com/my-app:" + strenv(IMAGE_TAG)' \
deployment.yaml
strenv()는 환경 변수의 값을 문자열로 가져오는 기능이다.
이 방식은 이미지 버전이 변경될 때 YAML 파일을 자동으로 수정하는 데 사용할 수 있다.
단, 실제 운영에서는 컨테이너 이름을 기준으로 변경 대상을 선택하거나, GitOps 도구가 관리하는 선언적 설정과 충돌하지 않도록 설계하는 것이 좋다.
5. 운영 환경의 설정 차이 확인
개발 환경과 운영 환경의 Kubernetes Manifest를 비교할 때도 yq를 사용할 수 있다.
예를 들어 두 파일의 replicas를 각각 확인한다.
yq '.spec.replicas' deployment-dev.yaml
yq '.spec.replicas' deployment-prod.yaml
출력 예시:
1
3
이러한 방식을 활용하면 환경별 설정 차이를 자동으로 검증하는 스크립트를 만들 수 있다.
YAML과 yq 사용 시 주의사항
YAML의 들여쓰기를 정확하게 작성해야 한다
YAML은 공백으로 계층 구조를 표현한다.
따라서 들여쓰기가 잘못되면 문법 오류가 발생하거나 의도하지 않은 데이터 구조가 만들어질 수 있다.
YAML 문법 검증과 Kubernetes API 검증은 다르다
YAML이 문법적으로 올바르더라도 Kubernetes 리소스의 필드 이름이나 타입이 잘못되면 적용에 실패할 수 있다.
따라서 YAML 문법과 Kubernetes API 구조를 함께 확인해야 한다.
yq 버전을 확인해야 한다
yq는 버전에 따라 일부 명령어나 옵션의 동작이 달라질 수 있다.
특히 자동화 스크립트를 작성할 때는 로컬과 CI/CD 환경의 버전을 일관되게 관리하는 것이 좋다.
원본 파일을 직접 수정할 때 주의해야 한다
yq -i는 원본 파일에 변경 내용을 반영한다.
따라서 변경 전후의 차이를 확인할 수 있도록 Git을 사용하거나 중요한 파일을 백업하는 것이 좋다.
YAML 설정 파일에 민감한 정보를 직접 저장하지 않아야 한다
데이터베이스 비밀번호나 API Key 등의 민감한 정보를 일반 YAML 파일에 직접 작성하면 Git 저장소 등에 노출될 수 있다.
Kubernetes Secret이나 외부 Secret 관리 시스템을 활용하고, 접근 권한을 적절하게 제한해야 한다.
Kubernetes Secret 역시 기본적으로 값을 암호화된 형태로 보장하는 것은 아니므로, 저장 시 암호화와 RBAC 등 추가적인 보안 설정을 고려해야 한다.
정리
Kubernetes에서는 Pod, Deployment, Service, ConfigMap, Secret 등 다양한 리소스를 YAML 파일로 정의하고 관리할 수 있다.
YAML은 사람이 읽기 쉬운 형태로 구조화된 데이터를 표현하는 형식이며, Kubernetes뿐 아니라 Spring Boot, Docker Compose, GitHub Actions 등 여러 개발 환경에서도 사용된다.
이번에 살펴본 핵심 내용을 정리하면 다음과 같다.
| 항목 | 핵심 내용 |
|---|---|
| YAML | 구조화된 데이터를 표현하는 직렬화 형식 |
| Kubernetes Manifest | Kubernetes 리소스의 원하는 상태를 선언한 파일 |
apiVersion | Kubernetes API 버전 |
kind | 리소스 종류 |
metadata | 리소스 이름과 메타데이터 |
spec | 리소스의 원하는 상태 |
| K3s | 가볍게 Kubernetes 환경을 구성할 수 있는 배포판 |
| kubectl | Kubernetes API와 통신하는 CLI |
| yq | YAML 데이터를 조회하고 수정하는 CLI |
yq eval | YAML 경로 표현식을 평가하는 명령어 |
yq -i | YAML 파일을 직접 수정하는 옵션 |
kubectl apply | Kubernetes Manifest를 클러스터에 적용하는 명령어 |
YAML을 사용할 때 가장 중요한 것은 단순히 문법을 암기하는 것이 아니라 들여쓰기와 데이터 구조를 이해하고, 각 설정이 어떤 의미를 가지는지 정확하게 파악하는 것이다.
또한 Kubernetes 환경에서는 YAML이 실제 리소스를 정의하는 수단이기 때문에 Kubernetes API 구조까지 함께 이해해야 한다.
yq를 활용하면 이러한 YAML 설정을 명령어로 조회하거나 변경할 수 있으며, 이를 통해 배포 자동화와 운영 설정 관리 작업을 더욱 효율적으로 구성할 수 있다.
한 줄 요약
YAML은 Kubernetes 리소스의 원하는 상태를 선언하는 데 사용하는 핵심 데이터 형식이며, yq는 YAML 파일을 구조적으로 조회하고 수정하여 설정 관리와 배포 자동화를 효율적으로 수행할 수 있도록 도와주는 도구이다.
01. Yaml 정의
YAML이란? YAML의 개념과 특징, 데이터 직렬화의 이해
Kubernetes에서는 Pod, Deployment, Service, ConfigMap 등 다양한 리소스를 YAML 파일로 정의하고 관리한다.
Spring Boot의 application.yml, Docker Compose의 compose.yaml, GitHub Actions의 Workflow 파일에서도 YAML을 사용한다.
이처럼 YAML은 다양한 개발 환경에서 널리 사용되는 데이터 표현 형식이다.
그렇다면 YAML은 정확히 무엇이며, 여러 시스템에서 공통적으로 사용하는 이유는 무엇일까?
YAML의 가장 큰 특징은 사람이 쉽게 읽고 작성할 수 있도록 설계된 데이터 직렬화 언어라는 점이다.
예를 들어 다음과 같은 데이터를 살펴보자.
name: 홍길동
age: 30
favorites:
food: Steak
musician: The Weeknd
별도의 설명 없이도 다음 정보를 이해할 수 있다.
- 이름은 홍길동이다.
- 나이는 30세이다.
- 좋아하는 음식은 Steak이다.
- 좋아하는 음악가는 The Weeknd이다.
YAML에서는 복잡한 태그나 기호를 반복해서 사용하지 않는다.
대신 콜론(:), 들여쓰기, 하이픈(-)과 같은 간단한 문법으로 데이터를 표현한다.
따라서 사람이 작성하고 읽어야 하는 설정 파일에 특히 적합하다.
YAML을 제대로 이해하려면 다음 세 가지 개념을 먼저 살펴볼 필요가 있다.
- YAML Ain’t Markup Language: YAML은 마크업 언어가 아니다.
- Human-Friendly: 사람이 읽고 작성하기 쉬운 형식이다.
- Data Serialization: 데이터를 저장하거나 전달할 수 있는 형태로 표현한다.
YAML의 정의
YAML은 YAML Ain’t Markup Language의 약자이다.
이름을 그대로 해석하면 ‘YAML은 마크업 언어가 아니다’라는 의미이다.
정확하게는 YAML이 단순히 문서의 구조나 표현 방식을 표시하기 위한 언어가 아니라, 프로그래밍 언어와 관계없이 구조화된 데이터를 표현하기 위해 만들어진 직렬화 언어라는 점을 강조한다.
YAML은 공식적으로 다음 특징을 가진 데이터 언어로 정의된다.
| 특징 | 의미 |
|---|---|
| Human-Friendly | 사람이 읽고 작성하기 쉬움 |
| Cross-Language | 서로 다른 프로그래밍 언어에서 활용 가능 |
| Data Serialization | 데이터를 저장하거나 전달할 수 있는 형태로 표현 |
| Unicode-Based | 다양한 언어의 문자를 표현할 수 있음 |
이러한 특징을 바탕으로 YAML은 애플리케이션 설정, 데이터 저장, 시스템 간 데이터 교환 등에 활용된다.
YAML은 사람이 읽기 쉬운 형식이지만, 단순한 메모 형식은 아니다. 정해진 데이터 모델과 문법을 가진 정식 데이터 직렬화 언어이다.
YAML은 왜 마크업 언어가 아닐까?
YAML의 이름에 포함된 ‘Ain’t Markup Language’를 이해하려면 먼저 마크업 언어가 무엇인지 알아야 한다.
마크업 언어란?
마크업 언어(Markup Language)는 문서의 구조나 의미, 표현 방식을 표시하기 위해 특정한 기호나 태그를 사용하는 언어이다.
대표적인 마크업 언어에는 다음과 같은 것들이 있다.
| 언어 | 주요 용도 |
|---|---|
| HTML | 웹 문서의 구조와 의미 표현 |
| XML | 태그 기반의 구조화된 문서 및 데이터 표현 |
| Markdown | 간단한 문법으로 문서 구조와 서식 표현 |
예를 들어 다음 문장을 작성한다고 가정하자.
내 고양이는 아주 고약해.
여기서 ‘아주’라는 단어를 강조하고 싶다면 HTML에서는 다음과 같이 표현할 수 있다.
<p>내 고양이는 <strong>아주</strong> 고약해.</p>
<strong> 태그는 해당 텍스트가 중요하다는 의미를 나타낸다.
HTML은 이러한 태그를 사용해 문서의 구조와 의미를 표현한다.
XML 역시 태그를 사용하지만 HTML과는 목적이 다르다. XML은 문서뿐 아니라 구조화된 데이터를 표현하는 데도 사용된다.
예를 들어 다음과 같이 작성할 수 있다.
<person>
<name>홍길동</name>
<age>30</age>
<favoriteFood>Steak</favoriteFood>
</person>
여기서 <person>, <name>, <age>는 데이터의 구조와 의미를 나타내는 태그이다.
YAML은 데이터를 어떻게 표현할까?
동일한 데이터를 YAML로 작성하면 다음과 같다.
person:
name: 홍길동
age: 30
favoriteFood: Steak
XML과 달리 시작 태그와 종료 태그를 작성할 필요가 없다.
데이터의 관계를 들여쓰기로 표현하고, 각 항목을 Key-Value 형태로 작성한다.
두 형식을 비교하면 다음과 같다.
XML
<server>
<host>localhost</host>
<port>8080</port>
<enabled>true</enabled>
</server>
YAML
server:
host: localhost
port: 8080
enabled: true
YAML은 데이터의 내용을 표현하는 데 필요한 기호를 최소화하기 때문에 설정 파일처럼 자주 읽고 수정해야 하는 데이터를 간결하게 작성할 수 있다.
다만 XML 역시 데이터 교환에 사용할 수 있고 YAML에도 명확한 구조와 문법이 존재한다.
따라서 ‘YAML은 마크업 언어가 아니다’라는 표현을 ‘XML은 데이터를 표현하지 못한다’거나 ‘YAML에는 구조가 없다’는 의미로 이해해서는 안 된다.
핵심은 YAML이 문서의 마크업보다 데이터 자체의 표현과 직렬화에 초점을 맞춘 언어라는 점이다.
YAML의 핵심 구조: Key와 Value
YAML에서 가장 기본적인 데이터 표현 방식은 Key-Value 구조이다.
name: 홍길동
age: 30
city: Seoul
각 항목은 다음과 같이 구성된다.
Key: Value
예를 들어 다음 데이터를 살펴보자.
age: 30
여기서 각 요소의 의미는 다음과 같다.
| 요소 | 값 | 의미 |
|---|---|---|
| Key | age | 데이터의 이름 |
| Value | 30 | 해당 데이터의 값 |
| 구분 기호 | : | Key와 Value의 구분 |
이러한 Key-Value 관계를 YAML에서는 Mapping이라고 부른다.
다른 프로그래밍 언어에서 사용하는 Map, Dictionary와 비슷한 개념이다.
예를 들어 Java의 Map으로는 다음과 같이 표현할 수 있다.
Map<String, Object> person = new HashMap<>();
person.put("name", "홍길동");
person.put("age", 30);
person.put("city", "Seoul");
이를 YAML로 표현하면 다음과 같다.
name: 홍길동
age: 30
city: Seoul
이처럼 YAML은 프로그래밍 언어에서 사용하는 데이터 구조를 사람이 읽기 쉬운 형식으로 표현할 수 있다.
YAML의 기본 데이터 구조
YAML에서 데이터를 표현하는 핵심 구조는 크게 세 가지이다.
- Scalar
- Mapping
- Sequence
이 세 가지 구조를 조합하면 복잡한 데이터를 표현할 수 있다.
flowchart TD
A["YAML 데이터 구조"] --> B["Scalar"]
A --> C["Mapping"]
A --> D["Sequence"]
B --> E["문자열, 숫자, Boolean 등"]
C --> F["Key-Value 구조"]
D --> G["순서가 있는 데이터 목록"]
Scalar: 하나의 값
Scalar는 하나의 값을 의미한다.
문자열, 숫자, Boolean 등이 대표적인 예시이다.
name: 홍길동
age: 30
height: 175.5
enabled: true
여기서 다음 값들은 모두 Scalar이다.
홍길동
30
175.5
true
YAML은 이러한 값들을 문자열이나 숫자 등의 데이터 타입으로 표현할 수 있다.
Mapping: Key-Value 구조
Mapping은 Key와 Value의 관계를 표현하는 구조이다.
person:
name: 홍길동
age: 30
person의 Value는 단순한 문자열이 아니라 또 다른 Mapping이다.
따라서 중첩된 구조를 표현할 수 있다.
flowchart TD
A["person"] --> B["name"]
A --> C["age"]
B --> D["홍길동"]
C --> E["30"]
Sequence: 여러 값의 목록
Sequence는 순서가 있는 데이터의 목록을 의미한다.
YAML에서는 일반적으로 하이픈(-)을 사용한다.
foods:
- Steak
- Pizza
- Pasta
Java의 List와 비슷한 구조이다.
List<String> foods = List.of(
"Steak",
"Pizza",
"Pasta"
);
Sequence 안에 Mapping을 포함할 수도 있다.
users:
- name: 홍길동
age: 30
- name: 김철수
age: 28
이 구조는 사용자 객체 여러 개를 가진 목록에 해당한다.
Java로 표현하면 다음과 비슷하다.
record User(String name, int age) {}
List<User> users = List.of(
new User("홍길동", 30),
new User("김철수", 28)
);
즉 YAML은 특정 프로그래밍 언어에 종속된 문법을 사용하지 않으면서도 여러 언어에서 사용하는 자료구조를 표현할 수 있다.
YAML이 사람이 읽기 쉬운 이유
YAML의 가장 큰 장점 중 하나는 Human-Friendly한 데이터 표현 방식이다.
Human-Friendly는 사람이 데이터를 쉽게 읽고 이해하고 수정할 수 있도록 설계되었다는 의미이다.
이를 조금 더 구체적으로 살펴보자.
1. 읽는 순서대로 데이터를 이해할 수 있다
다음 YAML을 살펴보자.
person:
name: 홍길동
age: 30
favorites:
food: Steak
musician: The Weeknd
일반적인 문장을 읽는 것처럼 위에서 아래로 데이터를 읽으면 된다.
person
├── name: 홍길동
├── age: 30
└── favorites
├── food: Steak
└── musician: The Weeknd
별도의 파싱 도구를 사용하지 않더라도 데이터의 구조를 직관적으로 파악할 수 있다.
2. 들여쓰기로 데이터의 계층을 표현한다
YAML에서는 들여쓰기를 사용하여 데이터 사이의 관계를 표현한다.
application:
server:
host: localhost
port: 8080
database:
host: mysql
port: 3306
이 구조에서는 application 아래에 server와 database가 존재한다.
그리고 각각의 설정 안에 host와 port가 존재한다.
flowchart TD
A["application"] --> B["server"]
A --> C["database"]
B --> D["host: localhost"]
B --> E["port: 8080"]
C --> F["host: mysql"]
C --> G["port: 3306"]
중괄호나 시작·종료 태그 없이도 계층 구조를 표현할 수 있다는 점이 YAML의 장점이다.
다만 들여쓰기는 단순히 가독성을 높이기 위한 장식이 아니다.
YAML에서는 들여쓰기 자체가 데이터 구조를 결정하는 문법 요소이다.
따라서 들여쓰기가 잘못되면 데이터 구조가 달라지거나 문법 오류가 발생할 수 있다.
3. 하이픈으로 목록을 표현한다
여러 개의 데이터를 나열할 때는 하이픈을 사용할 수 있다.
skills:
- Java
- Spring Boot
- Kubernetes
- Docker
이 구조는 사람이 목록을 작성하는 방식과 비슷하다.
각 항목의 순서도 유지된다.
Kubernetes에서도 Pod의 컨테이너 목록을 정의할 때 이러한 문법을 사용한다.
containers:
- name: application
image: nginx:1.27
- name: redis
image: redis:7
각 하이픈은 하나의 컨테이너 설정을 의미한다.
4. 주석을 작성할 수 있다
YAML에서는 #을 사용하여 주석을 작성할 수 있다.
# 애플리케이션 이름
name: my-app
# 서버 포트
port: 8080
# 운영 환경 여부
production: true
주석은 프로그램에서 처리할 실제 데이터가 아니라 작성자가 설정을 이해하는 데 도움을 주는 설명이다.
복잡한 Kubernetes Manifest나 애플리케이션 설정 파일에서 주석을 사용하면 특정 설정의 목적을 더 쉽게 이해할 수 있다.
다만 주석의 내용을 변경한다고 해서 Kubernetes 리소스의 동작이 변경되는 것은 아니다.
5. 불필요한 기호를 최소화한다
YAML은 데이터를 구분하기 위해 많은 기호를 사용하지 않는다.
예를 들어 다음 설정을 살펴보자.
server:
port: 8080
spring:
application:
name: my-app
중괄호, 세미콜론, 종료 태그가 필요하지 않다.
사람이 주로 읽고 수정하는 설정 파일에서는 이러한 특징이 가독성과 유지보수성에 도움이 된다.
Human-Friendly와 Machine-Friendly의 차이
데이터를 표현하는 방식이 모두 사람에게 읽기 쉬울 필요는 없다.
컴퓨터가 효율적으로 처리하는 데 중점을 둔 데이터 표현 방식도 있다.
대표적인 예시로 Base64 인코딩을 살펴볼 수 있다.
사람이 읽기 쉬운 YAML
다음은 사용자 정보를 YAML로 표현한 예시이다.
name: Hong
age: 30
food: Steak
사람은 별도의 도구 없이 데이터의 의미를 파악할 수 있다.
반면 이러한 텍스트를 Base64로 인코딩하면 사람이 내용을 직접 읽기는 어려워진다.
Base64는 데이터를 문자 형태로 안전하게 표현하기 위한 인코딩 방식이다.
예를 들어 다음 문자열을 살펴보자.
Hello
이를 Base64로 인코딩하면 다음과 같다.
SGVsbG8=
원래 문자열과 인코딩된 문자열을 비교하면 다음과 같다.
| 구분 | 데이터 | 사람이 이해하기 쉬운가? |
|---|---|---|
| 원본 문자열 | Hello | 쉬움 |
| Base64 인코딩 | SGVsbG8= | 디코딩 전에는 어려움 |
Base64로 인코딩된 데이터를 원래 문자열로 복원하려면 디코딩이 필요하다.
flowchart LR
A["원본 데이터"] --> B["Base64 Encoding"]
B --> C["인코딩된 문자열"]
C --> D["Base64 Decoding"]
D --> E["원본 데이터 복원"]
YAML과 Base64는 목적이 다르다
여기서 중요한 점은 YAML과 Base64가 서로 경쟁하는 데이터 형식은 아니라는 것이다.
YAML은 구조화된 데이터를 표현하는 직렬화 언어이다.
반면 Base64는 바이너리 데이터를 제한된 문자 집합으로 표현하기 위한 인코딩 방식이다.
| 구분 | YAML | Base64 |
|---|---|---|
| 분류 | 데이터 직렬화 언어 | 데이터 인코딩 방식 |
| 목적 | 구조화된 데이터 표현 | 데이터를 문자 형태로 변환 |
| 사람이 읽기 쉬운가? | 대체로 쉬움 | 인코딩 전 원본을 알기 어려움 |
| 데이터 구조 표현 | Mapping, Sequence 등 지원 | 자체적인 데이터 구조 표현 기능 없음 |
| 주요 활용 | 설정 파일, 데이터 교환 | 바이너리 데이터의 텍스트 표현 |
따라서 YAML 데이터 전체를 Base64로 인코딩할 수도 있고, YAML의 특정 Value에 Base64 문자열을 넣을 수도 있다.
실제 Kubernetes에서도 두 방식이 함께 사용된다.
예를 들어 Kubernetes Secret의 data 필드에는 Base64로 인코딩된 값이 사용된다.
apiVersion: v1
kind: Secret
metadata:
name: my-secret
type: Opaque
data:
username: YWRtaW4=
여기서 YWRtaW4=는 admin이라는 문자열을 Base64로 인코딩한 값이다.
YAML은 Secret의 전체 구조를 표현하고, Base64는 특정 데이터 값을 인코딩하는 역할을 한다.
단, Base64는 암호화가 아니다.
Base64로 인코딩된 값은 누구나 쉽게 디코딩할 수 있으므로, 민감한 정보를 보호하려면 Kubernetes Secret에 대한 접근 권한 관리와 저장 시 암호화 등의 추가적인 보안 조치가 필요하다.
YAML이 설정 파일에 적합한 이유
YAML은 사람이 자주 읽고 수정해야 하는 데이터를 표현할 때 장점이 크다.
애플리케이션 설정 파일을 예로 들어보자.
server:
port: 8080
spring:
application:
name: payment-service
datasource:
url: jdbc:mysql://localhost:3306/payment
username: payment_user
password: ${DB_PASSWORD}
이 설정에서 다음 내용을 쉽게 확인할 수 있다.
- 애플리케이션의 이름
- 서버 포트
- 데이터베이스 연결 주소
- 데이터베이스 사용자
- 환경 변수로 주입받는 비밀번호
이러한 데이터를 사람이 읽기 쉬운 형태로 관리할 수 있기 때문에 YAML은 설정 파일에 널리 사용된다.
또한 YAML은 중첩 구조를 자연스럽게 표현할 수 있어 설정 항목이 많아져도 데이터 사이의 관계를 파악하기 쉽다.
다만 설정 파일이 지나치게 커지면 깊은 들여쓰기 구조가 오히려 가독성을 떨어뜨릴 수 있다.
따라서 실무에서는 YAML이라는 형식 자체뿐 아니라 파일 분리, 환경별 설정 관리, 명확한 Key 이름 등도 함께 고려해야 한다.
데이터 직렬화란?
YAML의 또 다른 핵심 특징은 데이터 직렬화(Data Serialization)이다.
직렬화란 프로그램 내부의 객체나 자료구조를 저장하거나 다른 시스템에 전달할 수 있는 형태로 변환하는 과정이다.
예를 들어 Java 애플리케이션에서 사용자 정보를 객체로 관리한다고 가정하자.
public record User(
String name,
int age,
String favoriteFood
) {
}
이 객체를 생성한다.
User user = new User(
"홍길동",
30,
"Steak"
);
Java 애플리케이션은 해당 객체를 메모리에서 관리할 수 있다.
하지만 이 객체를 파일에 저장하거나 다른 애플리케이션에 전달하려면 어떻게 해야 할까?
Java 객체를 그대로 다른 프로그래밍 언어에서 사용할 수 있는 것은 아니다.
객체의 필드와 값을 공통으로 이해할 수 있는 데이터 형식으로 표현해야 한다.
이때 사용하는 과정이 직렬화이다.
flowchart LR
A["Java 객체"] --> B["Serialization"]
B --> C["YAML 데이터"]
C --> D["파일 저장 또는 네트워크 전달"]
앞서 생성한 사용자 객체를 YAML로 표현하면 다음과 같다.
name: 홍길동
age: 30
favoriteFood: Steak
Java 객체의 필드와 값이 YAML 문서로 표현된 것이다.
이렇게 변환된 데이터는 파일로 저장하거나 네트워크를 통해 다른 시스템으로 전달할 수 있다.
단, 직렬화는 단순히 메모리에 있는 객체를 그대로 복사하는 과정이 아니다.
객체의 데이터를 특정한 형식으로 표현하여 저장하거나 전달할 수 있도록 만드는 과정이다.
역직렬화란?
직렬화의 반대 과정은 역직렬화(Deserialization)이다.
역직렬화란 저장되거나 전달된 데이터를 애플리케이션이 사용할 수 있는 객체나 자료구조로 복원하는 과정이다.
예를 들어 YAML 파일에 다음 데이터가 저장되어 있다고 가정하자.
name: 홍길동
age: 30
favoriteFood: Steak
Java 애플리케이션이 이 YAML을 읽어 User 객체로 변환하면 역직렬화가 이루어진 것이다.
flowchart LR
A["YAML 데이터"] --> B["Deserialization"]
B --> C["Java User 객체"]
직렬화와 역직렬화를 하나의 흐름으로 표현하면 다음과 같다.
flowchart LR
A["Java 객체"] --> B["Serialization"]
B --> C["YAML 문서"]
C --> D["Deserialization"]
D --> E["Java 객체"]
이를 통해 애플리케이션은 프로그램 내부의 데이터를 외부에 저장하고, 필요할 때 다시 복원할 수 있다.
직렬화와 역직렬화 비교
| 구분 | Serialization | Deserialization |
|---|---|---|
| 한글 명칭 | 직렬화 | 역직렬화 |
| 변환 방향 | 객체 → 데이터 표현 | 데이터 표현 → 객체 |
| 주요 목적 | 저장 및 전달 | 데이터 복원 |
| 입력 | 객체 또는 자료구조 | YAML, JSON 등 |
| 출력 | 직렬화된 데이터 | 객체 또는 자료구조 |
직렬화가 필요한 이유
직렬화의 필요성을 이해하려면 프로그램 내부의 데이터가 다른 프로그램으로 전달되는 상황을 생각해 보면 된다.
예를 들어 다음 두 애플리케이션이 있다고 가정하자.
서비스 A: Java
서비스 B: Python
Java와 Python은 객체를 메모리에서 표현하는 방식이 다르다.
Java의 객체를 그대로 Python 애플리케이션에 전달한다고 해서 Python이 이를 자동으로 이해할 수 있는 것은 아니다.
각 프로그래밍 언어의 객체 모델과 런타임 구조가 다르기 때문이다.
따라서 서로 다른 언어로 개발된 애플리케이션이 데이터를 교환하려면 양쪽에서 이해할 수 있는 공통 데이터 형식이 필요하다.
이때 YAML이나 JSON과 같은 데이터 직렬화 형식을 활용할 수 있다.
flowchart LR
A["Java Application"] --> B["Java 객체"]
B --> C["Serialization"]
C --> D["공통 데이터 형식"]
D --> E["Deserialization"]
E --> F["Python 객체"]
F --> G["Python Application"]
Java에서 생성한 데이터를 YAML로 직렬화하고 Python에서 해당 YAML을 역직렬화한다면 서로 다른 프로그래밍 언어 사이에서도 데이터를 교환할 수 있다.
예를 들어 Java 애플리케이션이 다음 데이터를 생성했다고 가정하자.
order:
id: 1001
product: Keyboard
quantity: 2
price: 50000
Python 애플리케이션도 동일한 YAML 구조를 파싱하여 주문 정보를 사용할 수 있다.
중요한 것은 두 언어가 같은 객체를 메모리에 생성하는 것이 아니라는 점이다.
각 애플리케이션은 공통 데이터 형식을 해석하여 자신의 언어에 맞는 객체나 자료구조를 생성한다.
이것이 직렬화 언어가 시스템 사이의 데이터 교환에서 중요한 이유이다.
서로 다른 프로그래밍 언어가 동일한 데이터를 이해하는 과정
Java와 Python을 예로 들어 직렬화와 역직렬화 과정을 조금 더 자세히 살펴보자.
1. Java 애플리케이션에서 객체 생성
public record Order(
Long id,
String product,
int quantity
) {
}
다음과 같은 주문 객체를 생성한다.
Order order = new Order(
1001L,
"Keyboard",
2
);
2. YAML 형식으로 직렬화
해당 객체를 YAML로 직렬화하면 다음과 같은 데이터로 표현할 수 있다.
id: 1001
product: Keyboard
quantity: 2
직렬화된 데이터는 Java 객체 자체가 아니다.
언어에 종속되지 않는 형태로 표현된 데이터이다.
3. 다른 애플리케이션으로 데이터 전달
이 YAML 데이터를 파일로 저장하거나 네트워크를 통해 다른 애플리케이션에 전달한다.
flowchart TD
A["Java Order 객체"] --> B["YAML 직렬화"]
B --> C["YAML 데이터 생성"]
C --> D["파일 또는 네트워크 전달"]
D --> E["Python 애플리케이션"]
4. Python에서 역직렬화
Python은 YAML 파서를 이용해 다음과 같은 자료구조로 데이터를 복원할 수 있다.
order = {
"id": 1001,
"product": "Keyboard",
"quantity": 2
}
여기서 Java의 Order 객체와 Python의 Dictionary는 서로 다른 자료구조이다.
하지만 다음 데이터의 의미는 동일하다.
주문 번호: 1001
상품: Keyboard
수량: 2
결과적으로 서로 다른 프로그래밍 언어 사이에서도 데이터를 교환할 수 있게 된다.
다만 공통 직렬화 형식을 사용한다고 해서 모든 문제가 자동으로 해결되는 것은 아니다.
양쪽 애플리케이션이 필드 이름, 데이터 타입, 필수 항목, 기본값 등에 대해서도 동일한 규칙을 이해해야 한다.
이러한 규칙을 데이터 스키마 또는 데이터 계약이라고 부를 수 있다.
데이터 직렬화와 인코딩의 차이
직렬화와 인코딩은 함께 사용되는 경우가 많아 혼동하기 쉽다.
하지만 두 개념은 서로 다르다.
데이터 직렬화
직렬화는 객체나 자료구조를 저장하거나 전달할 수 있는 형식으로 변환한다.
Java 객체
↓
YAML 직렬화
↓
YAML 문서
데이터 인코딩
인코딩은 데이터를 특정한 규칙에 따라 다른 표현 형태로 변환한다.
대표적인 예시가 Base64 인코딩이다.
원본 데이터
↓
Base64 Encoding
↓
Base64 문자열
두 과정을 함께 사용할 수도 있다.
flowchart TD
A["애플리케이션 객체"] --> B["YAML 직렬화"]
B --> C["YAML 텍스트"]
C --> D["UTF-8 인코딩"]
D --> E["바이트 데이터"]
E --> F["파일 저장 또는 네트워크 전송"]
여기서 YAML 직렬화는 데이터의 구조와 값을 표현하는 역할을 한다.
UTF-8 인코딩은 문자를 바이트로 표현하는 역할을 한다.
실제로 파일이나 네트워크를 통해 데이터를 전달할 때는 이러한 개념이 서로 연결된다.
따라서 직렬화와 인코딩을 같은 의미로 사용하는 것은 정확하지 않다.
YAML이 모든 프로그래밍 언어에서 활용될 수 있는 이유
YAML은 특정 프로그래밍 언어의 문법이나 객체 구조에 종속되지 않도록 설계되었다.
예를 들어 다음 YAML은 어떤 특정 프로그래밍 언어에만 속하는 데이터가 아니다.
application:
name: payment-service
enabled: true
servers:
- host: server1
port: 8080
- host: server2
port: 8080
Java에서는 객체나 Map으로 표현할 수 있다.
Python에서는 Dictionary와 List로 표현할 수 있다.
JavaScript에서는 Object와 Array로 표현할 수 있다.
flowchart TD
A["YAML 문서"] --> B["YAML Parser"]
B --> C["Java"]
B --> D["Python"]
B --> E["JavaScript"]
C --> F["Object 또는 Map"]
D --> G["Dictionary와 List"]
E --> H["Object와 Array"]
각 언어에서 사용하는 객체 모델은 다르지만 YAML의 기본 구조를 해석하는 방식은 공통으로 사용할 수 있다.
이것이 YAML의 Cross-Language 특성이다.
다만 YAML 파서의 버전이나 스키마에 따라 일부 데이터 타입이 다르게 해석될 수 있으므로, 여러 언어가 데이터를 교환하는 환경에서는 타입과 스키마를 명확하게 정의하는 것이 좋다.
YAML은 어디에서 활용될까?
YAML은 읽기 쉬운 형식과 데이터 직렬화라는 특징을 바탕으로 다양한 환경에서 활용된다.
1. Kubernetes 리소스 정의
Kubernetes에서는 원하는 리소스 상태를 YAML로 작성할 수 있다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
여기서 YAML은 Deployment의 원하는 상태를 표현한다.
Kubernetes API Server는 전달받은 설정을 해석하고 리소스를 생성하거나 수정한다.
2. Spring Boot 설정 관리
Spring Boot에서는 application.yml을 사용해 애플리케이션 설정을 관리할 수 있다.
server:
port: 8080
spring:
application:
name: order-service
logging:
level:
root: INFO
환경별 설정을 관리하거나 중첩된 설정을 표현할 때 유용하다.
3. Docker Compose
Docker Compose에서도 YAML 파일을 사용해 여러 컨테이너의 실행 구성을 정의할 수 있다.
services:
redis:
image: redis:7
ports:
- "6379:6379"
mysql:
image: mysql:8.4
environment:
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
컨테이너 이미지, 포트, 환경 변수 등의 설정을 구조적으로 표현할 수 있다.
4. GitHub Actions
GitHub Actions에서는 YAML을 사용해 자동화 Workflow를 정의한다.
name: Build
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Print message
run: echo "Build started"
애플리케이션 빌드나 테스트, 배포 작업을 YAML로 선언할 수 있다.
이처럼 YAML은 특정 시스템의 전용 언어가 아니라 여러 시스템에서 공통으로 사용하는 데이터 표현 형식이다.
YAML 사용 시 알아야 할 주의사항
YAML은 읽기 쉬운 형식이지만 문법을 정확하게 이해하지 못하면 예상하지 못한 문제가 발생할 수 있다.
1. 들여쓰기 자체가 문법이다
다음 YAML은 정상적인 예시이다.
server:
host: localhost
port: 8080
반면 다음은 잘못된 예시이다.
server:
host: localhost
port: 8080
같은 계층에 있어야 하는 host와 port의 들여쓰기가 다르다.
YAML에서는 들여쓰기에 Tab 대신 공백을 사용해야 한다.
2. 데이터 타입을 정확하게 구분해야 한다
다음 값은 숫자이다.
port: 8080
반면 다음 값은 문자열이다.
port: "8080"
두 값은 화면에서 비슷하게 보이지만 타입이 다르다.
특히 Kubernetes의 환경 변수 설정에서는 문자열을 사용해야 한다.
env:
- name: SERVER_PORT
value: "8080"
설정 파일을 읽는 애플리케이션이 어떤 타입을 기대하는지 함께 고려해야 한다.
3. 일부 문자열에는 따옴표가 필요하다
YAML에서는 문자열을 따옴표 없이 작성할 수 있다.
name: my-app
하지만 특수문자가 포함되거나 다른 데이터 타입으로 해석될 가능성이 있는 값은 따옴표로 감싸는 것이 안전하다.
message: "Hello: World"
version: "1.0"
enabled: "true"
특히 YAML 파서의 버전에 따라 문자열과 Boolean 등으로 해석되는 규칙이 달라질 수 있다.
실무에서는 데이터 타입이 중요한 값에 따옴표를 명시하여 해석상의 모호함을 줄이는 것이 좋다.
4. YAML은 실행 가능한 프로그래밍 언어가 아니다
YAML 자체는 일반적인 프로그래밍 언어처럼 조건문이나 반복문을 실행하는 언어가 아니다.
다음과 같은 설정이 있다고 가정하자.
replicas: 3
이 설정이 Pod 3개를 직접 생성하는 것은 아니다.
Kubernetes가 YAML을 파싱하고 replicas 필드의 의미를 해석하여 필요한 동작을 수행하는 것이다.
즉 YAML은 데이터를 표현하고, 그 데이터를 사용하는 프로그램이 실제 동작을 결정한다.
flowchart LR
A["YAML 설정"] --> B["YAML Parser"]
B --> C["설정 데이터"]
C --> D["애플리케이션"]
D --> E["실제 동작 수행"]
이 차이를 이해하면 YAML과 Kubernetes의 역할을 더 명확하게 구분할 수 있다.
실무에서 YAML을 이해해야 하는 이유
백엔드 개발에서는 애플리케이션의 코드를 작성하는 것만큼 실행 환경과 설정을 관리하는 일도 중요하다.
예를 들어 Spring Boot 애플리케이션을 Kubernetes에 배포한다고 가정하자.
이 과정에서는 여러 YAML 파일을 사용할 수 있다.
Spring Boot
└── application.yml
├── 서버 설정
├── 데이터베이스 설정
└── 로깅 설정
Kubernetes
├── deployment.yaml
├── service.yaml
├── configmap.yaml
└── hpa.yaml
각 YAML 파일은 서로 다른 역할을 한다.
하지만 기본적인 데이터 표현 방식은 동일하다.
flowchart TD
A["YAML 문법"] --> B["Spring Boot 설정"]
A --> C["Kubernetes Manifest"]
A --> D["Docker Compose"]
A --> E["CI/CD Workflow"]
B --> F["애플리케이션 실행 설정"]
C --> G["클러스터 리소스 관리"]
D --> H["컨테이너 실행 구성"]
E --> I["자동화 작업 정의"]
따라서 YAML의 기본 개념을 정확하게 이해하면 특정 도구의 문법을 무작정 암기하지 않아도 설정 파일의 구조를 빠르게 파악할 수 있다.
실무에서는 다음과 같은 능력으로 이어진다.
- 중첩된 설정의 구조를 정확하게 이해할 수 있다.
- 설정 파일의 오류를 빠르게 찾을 수 있다.
- 서로 다른 환경의 설정을 비교하기 쉬워진다.
- CI/CD에서 설정 파일을 자동으로 수정하거나 검증할 수 있다.
- Kubernetes Manifest를 더 안전하게 작성할 수 있다.
- 다른 개발자가 작성한 설정 파일을 빠르게 분석할 수 있다.
특히 Kubernetes 환경에서는 YAML을 통해 시스템의 원하는 상태를 선언하기 때문에 설정 하나가 실제 운영 환경에 영향을 줄 수 있다.
따라서 YAML을 단순한 텍스트 파일로 생각하기보다 애플리케이션과 인프라의 동작을 정의하는 구조화된 데이터로 이해하는 것이 중요하다.
정리
YAML은 사람이 읽고 작성하기 쉽도록 설계된 데이터 직렬화 언어이다.
YAML의 이름은 YAML Ain't Markup Language이며, 문서에 태그를 붙이는 마크업보다 데이터 자체를 표현하는 데 중점을 둔다.
YAML의 핵심적인 특징은 다음과 같다.
| 특징 | 설명 |
|---|---|
| Human-Friendly | 사람이 쉽게 읽고 작성할 수 있는 문법 |
| Data Serialization | 객체와 자료구조를 저장하거나 전달할 수 있는 형식으로 표현 |
| Cross-Language | 서로 다른 프로그래밍 언어에서도 활용 가능 |
| Key-Value | 데이터를 이름과 값의 관계로 표현 |
| Indentation | 들여쓰기를 사용해 데이터의 계층 구조 표현 |
| Sequence | 하이픈을 사용해 데이터 목록 표현 |
| Comment | #으로 주석 작성 |
| Unicode | 다양한 언어의 문자 표현 가능 |
또한 직렬화와 역직렬화의 개념을 이해하는 것도 중요하다.
직렬화(Serialization) 는 애플리케이션의 객체나 자료구조를 저장하거나 전달할 수 있는 데이터 형식으로 변환하는 과정이다.
역직렬화(Deserialization) 는 직렬화된 데이터를 애플리케이션이 사용할 수 있는 객체나 자료구조로 복원하는 과정이다.
flowchart LR
A["애플리케이션 객체"] --> B["직렬화"]
B --> C["YAML 데이터"]
C --> D["저장 또는 전달"]
D --> E["역직렬화"]
E --> F["애플리케이션 객체"]
이러한 특성 때문에 YAML은 Kubernetes, Spring Boot, Docker Compose, GitHub Actions 등 다양한 개발 환경에서 활용된다.
다만 YAML은 읽기 쉬운 형식이라는 장점이 있는 반면, 들여쓰기와 데이터 타입에 민감하다는 특징도 가지고 있다.
따라서 YAML을 정확하게 활용하려면 기본 문법뿐 아니라 데이터의 계층 구조와 직렬화 개념을 함께 이해해야 한다.
한 줄 요약
YAML은 Key-Value, 들여쓰기, 목록 등을 이용해 구조화된 데이터를 사람이 읽기 쉬운 형태로 표현하는 데이터 직렬화 언어이며, 서로 다른 애플리케이션과 프로그래밍 언어 사이에서 데이터를 저장하고 전달하는 데 활용된다.
02. Yaml vs JSON
YAML과 JSON 비교: 문법, 구조, 장단점과 실무 활용
애플리케이션을 개발하다 보면 데이터를 저장하거나 다른 시스템에 전달하기 위해 일정한 형식으로 표현해야 하는 상황이 자주 발생한다.
대표적으로 REST API를 개발할 때는 JSON을 사용하고, Kubernetes나 Spring Boot의 설정 파일을 작성할 때는 YAML을 사용하는 경우가 많다.
두 형식은 모두 데이터를 저장하고 교환하는 데 사용할 수 있는 텍스트 기반 데이터 직렬화 형식(Data Serialization Format) 이다.
하지만 데이터를 표현하는 문법과 설계 목적에는 차이가 있다.
JSON은 간결하고 명확한 문법을 기반으로 데이터를 표현하는 데 중점을 두고, YAML은 사람이 데이터를 쉽게 읽고 작성할 수 있도록 가독성과 표현력을 높이는 데 중점을 둔다.
예를 들어 사용자 정보를 표현한다고 가정하자.
JSON
{
"name": "Hong",
"age": 30,
"favorites": {
"food": "Steak",
"musician": "The Weeknd"
}
}
YAML
name: Hong
age: 30
favorites:
food: Steak
musician: The Weeknd
두 데이터는 동일한 정보를 표현하지만 작성 방식은 다르다.
JSON은 중괄호와 큰따옴표를 이용해 데이터의 구조를 명시적으로 표현한다.
반면 YAML은 들여쓰기를 사용해 데이터의 계층 구조를 표현한다.
그렇다면 두 형식 중 어떤 것이 더 좋은 형식일까?
단순히 가독성만 비교하면 YAML이 유리해 보일 수 있다. 하지만 JSON은 단순한 문법 덕분에 파싱과 데이터 교환 측면에서 장점을 가진다.
또한 YAML은 다양한 표현 기능을 제공하지만, 이러한 기능이 복잡한 설정 파일에서는 오히려 가독성을 떨어뜨리는 원인이 되기도 한다.
따라서 두 형식을 정확하게 이해하려면 문법뿐 아니라 설계 목적, 데이터 구조, 파싱 방식, 실제 사용 환경까지 함께 비교해야 한다.
JSON이란?
JSON은 JavaScript Object Notation의 약자로, 구조화된 데이터를 표현하고 교환하기 위한 가벼운 텍스트 기반 데이터 형식이다.
이름에서 알 수 있듯이 JavaScript의 객체 표기법에서 유래했다.
하지만 JSON은 JavaScript에서만 사용하는 형식이 아니다.
현재는 Java, Python, Go, JavaScript 등 거의 모든 주요 프로그래밍 언어에서 JSON을 처리할 수 있다.
특히 웹 애플리케이션과 REST API에서 데이터를 교환하는 대표적인 형식으로 사용된다.
예를 들어 사용자 정보를 조회하는 API가 있다고 가정하자.
GET /api/users/100
서버는 다음과 같은 JSON 데이터를 응답할 수 있다.
{
"id": 100,
"name": "Hong",
"email": "hong@example.com",
"active": true
}
클라이언트는 JSON 데이터를 역직렬화하여 자신의 프로그래밍 언어에서 사용하는 객체로 변환할 수 있다.
flowchart LR
A["Client"] -->|"HTTP Request"| B["Backend API"]
B --> C["Java 객체"]
C --> D["JSON 직렬화"]
D -->|"HTTP Response"| A
A --> E["JSON 역직렬화"]
E --> F["JavaScript 객체"]
이처럼 JSON은 프로그래밍 언어와 관계없이 구조화된 데이터를 전달할 수 있다는 장점을 가진다.
JSON의 기본 문법
JSON은 비교적 적은 수의 문법 요소를 사용한다.
대표적인 구성 요소는 다음과 같다.
| 문법 요소 | 의미 |
|---|---|
{ } | 객체(Object) |
[ ] | 배열(Array) |
: | Key와 Value 구분 |
, | 객체의 멤버 또는 배열 요소 구분 |
" " | 문자열 표현 |
true, false | Boolean |
null | 값이 없음을 표현 |
이 요소들을 조합하면 복잡한 데이터 구조도 표현할 수 있다.
객체는 중괄호로 표현한다
JSON에서 객체는 중괄호({ })로 표현한다.
{
"name": "Hong",
"age": 30,
"city": "Seoul"
}
객체 내부에는 여러 개의 Key-Value 쌍이 존재한다.
"Key": Value
예를 들어 다음 항목을 살펴보자.
{
"age": 30
}
age는 Key이고 30은 Value이다.
JSON 객체의 Key는 반드시 문자열이어야 하며, 큰따옴표로 감싸야 한다.
반면 Value는 문자열뿐 아니라 숫자, Boolean, 배열, 객체 등 다양한 타입을 사용할 수 있다.
문자열은 큰따옴표로 표현한다
JSON에서 문자열은 반드시 큰따옴표(" ")로 감싸야 한다.
{
"name": "Hong",
"city": "Seoul"
}
문자열 대신 숫자나 Boolean을 사용하는 경우에는 큰따옴표를 사용하지 않는다.
{
"name": "Hong",
"age": 30,
"active": true
}
각 필드의 데이터 타입은 다음과 같다.
| 필드 | 값 | 데이터 타입 |
|---|---|---|
name | "Hong" | String |
age | 30 | Number |
active | true | Boolean |
반면 다음과 같이 작성하면 데이터 타입이 달라진다.
{
"age": "30",
"active": "true"
}
이 경우 두 값은 모두 문자열이다.
화면에 표시되는 값이 비슷하더라도 데이터 타입은 다르게 처리되므로 주의해야 한다.
쉼표로 데이터를 구분한다
JSON은 객체의 각 Key-Value 쌍을 쉼표(,)로 구분한다.
{
"name": "Hong",
"age": 30,
"city": "Seoul"
}
쉼표는 각 항목의 끝에 작성하지만 마지막 항목 뒤에는 작성하지 않는다.
이 점은 JSON에서 자주 발생하는 문법 오류와 관련이 있다.
배열은 대괄호로 표현한다
JSON에서 배열은 대괄호([ ])를 사용한다.
{
"skills": [
"Java",
"Spring Boot",
"Kubernetes"
]
}
skills의 Value는 문자열 하나가 아니라 여러 문자열을 포함하는 배열이다.
배열 안에는 문자열뿐 아니라 객체도 포함할 수 있다.
{
"jobs": [
{
"company": "Company A",
"position": "Backend Developer"
},
{
"company": "Company B",
"position": "Software Engineer"
}
]
}
이처럼 JSON에서는 객체와 배열을 조합해 복잡한 데이터 구조를 표현할 수 있다.
flowchart TD
A["JSON Object"] --> B["name: Hong"]
A --> C["jobs: Array"]
C --> D["Object 1"]
C --> E["Object 2"]
D --> F["company: Company A"]
D --> G["position: Backend Developer"]
E --> H["company: Company B"]
E --> I["position: Software Engineer"]
JSON은 반드시 중괄호로 시작해야 할까?
JSON을 사용하다 보면 대부분 중괄호로 시작하는 데이터를 접하게 된다.
{
"name": "Hong"
}
하지만 JSON은 반드시 중괄호로 시작할 필요가 없다.
JSON 문서의 최상위 값은 객체뿐 아니라 배열도 될 수 있다.
예를 들어 다음 JSON은 올바른 형식이다.
[
{
"id": 1,
"name": "Hong"
},
{
"id": 2,
"name": "Kim"
}
]
이 데이터는 최상위에 객체가 아니라 배열이 존재한다.
배열 안에 사용자 객체가 포함된 구조이다.
또한 현재 JSON 규격에서는 문자열, 숫자, Boolean, null 같은 값도 최상위 JSON 값으로 사용할 수 있다.
"Hello World"
100
true
따라서 JSON의 최상위 구조가 반드시 { }라는 설명은 정확하지 않다.
다만 실제 REST API에서는 데이터를 구조화하고 확장하기 쉬운 객체나 배열 형태를 사용하는 경우가 일반적이다.
JSON은 한 줄로 작성할 수 있다
JSON에서는 중괄호, 대괄호, 쉼표 등을 이용해 데이터의 구조를 표현한다.
따라서 줄바꿈이나 들여쓰기가 없어도 데이터를 해석할 수 있다.
예를 들어 다음 JSON을 살펴보자.
{
"name": "Hong",
"age": 30,
"skills": [
"Java",
"Kubernetes"
]
}
동일한 데이터를 다음과 같이 한 줄로 작성할 수도 있다.
{"name":"Hong","age":30,"skills":["Java","Kubernetes"]}
두 JSON은 같은 데이터를 표현한다.
JSON에서는 구조를 구분하는 기호가 명확하기 때문에 이러한 표현이 가능하다.
이 특징은 네트워크 통신에서도 활용할 수 있다.
예를 들어 서버가 JSON 데이터를 응답할 때 불필요한 공백과 줄바꿈을 제거하면 전송할 텍스트 크기를 줄일 수 있다.
다만 데이터의 크기는 필드명과 문자열 값의 길이에도 영향을 받기 때문에 단순히 한 줄로 작성했다고 해서 항상 큰 성능 차이가 발생하는 것은 아니다.
또한 읽기 쉬운 형태로 출력한 JSON을 Pretty JSON이라고 부르기도 한다.
{
"message": "success",
"data": {
"id": 100,
"name": "Hong"
}
}
개발과 디버깅 과정에서는 Pretty JSON이 유리하지만, 실제 데이터 교환에서는 공백을 제거한 JSON을 사용할 수 있다.
JSON에서 자주 발생하는 문법 오류
JSON은 문법이 단순하지만 그만큼 작은 기호 하나가 잘못되어도 파싱 오류가 발생할 수 있다.
대표적인 사례가 쉼표와 큰따옴표 관련 오류이다.
마지막 항목 뒤에 쉼표를 작성한 경우
다음 JSON을 살펴보자.
{
"name": "Hong",
"age": 30,
"city": "Seoul",
}
위 JSON에는 문법 오류가 있다.
마지막 항목인 "city": "Seoul" 뒤에 쉼표가 존재하기 때문이다.
JSON에서는 마지막 항목 뒤에 쉼표를 작성할 수 없다.
올바른 JSON은 다음과 같다.
{
"name": "Hong",
"age": 30,
"city": "Seoul"
}
이처럼 마지막에 불필요하게 추가된 쉼표를 Trailing Comma라고 한다.
JavaScript의 객체 리터럴에서는 일부 상황에서 Trailing Comma를 사용할 수 있지만, 표준 JSON에서는 허용되지 않는다.
따라서 JavaScript 객체 리터럴과 JSON을 완전히 동일한 문법으로 생각해서는 안 된다.
Key에 큰따옴표를 사용하지 않은 경우
다음 데이터도 JSON 문법에 맞지 않는다.
{
name: "Hong",
age: 30
}
JavaScript 객체 리터럴에서는 사용할 수 있는 형태이지만, JSON에서는 객체의 Key에 큰따옴표가 필요하다.
올바른 JSON은 다음과 같다.
{
"name": "Hong",
"age": 30
}
문자열에 작은따옴표를 사용한 경우
다음 데이터도 표준 JSON이 아니다.
{
'name': 'Hong'
}
JSON에서 문자열은 큰따옴표를 사용해야 한다.
{
"name": "Hong"
}
문자열 내부의 큰따옴표를 이스케이프하지 않은 경우
다음 JSON은 잘못된 형식이다.
{
"message": "He said "Hello""
}
문자열 안에서 큰따옴표를 사용하려면 이스케이프 문자가 필요하다.
{
"message": "He said \"Hello\""
}
JSON을 직접 작성할 때는 이러한 문법 오류를 주의해야 한다.
다만 실제 백엔드 개발에서는 JSON 문자열을 수작업으로 연결하기보다는 Jackson과 같은 직렬화 라이브러리를 사용하는 것이 안전하다.
JSON은 주석을 지원하지 않는다
JSON의 특징 중 하나는 표준 문법에 주석이 포함되어 있지 않다는 점이다.
예를 들어 다음과 같은 데이터는 표준 JSON으로 처리할 수 없다.
{
// 애플리케이션 이름
"name": "my-app",
// 서버 포트
"port": 8080
}
JavaScript에서는 // 주석을 사용할 수 있지만 JSON에서는 허용되지 않는다.
다음과 같은 주석도 마찬가지이다.
{
/* 서버 설정 */
"port": 8080
}
일부 개발 도구에서는 JSONC(JSON with Comments)나 JSON5 같은 확장 형식을 지원한다.
그러나 이러한 형식은 표준 JSON과 구분해야 한다.
즉 특정 편집기에서 주석이 포함된 파일이 정상적으로 열리더라도 모든 JSON 파서가 이를 처리할 수 있는 것은 아니다.
이 때문에 사람이 직접 작성하고 관리해야 하는 복잡한 설정 파일에서는 주석을 지원하는 YAML이 유리할 수 있다.
YAML과 JSON의 문법 비교
JSON의 기본 구조를 이해했다면 이제 동일한 데이터를 YAML과 JSON으로 각각 표현해보자.
다음과 같은 애플리케이션 설정이 있다고 가정하자.
- 애플리케이션 이름은
payment-service - 실행 포트는
8080 - 운영 환경 여부는
true - 개발자는 두 명
- 배치 작업은 두 개
- 데이터베이스는 MySQL 사용
먼저 JSON으로 표현하면 다음과 같다.
JSON으로 작성한 설정
{
"application": {
"name": "payment-service",
"port": 8080,
"production": true,
"developers": [
"Hong",
"Kim"
],
"jobs": [
{
"name": "payment-reconciliation",
"enabled": true
},
{
"name": "settlement",
"enabled": false
}
],
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306
}
}
}
동일한 설정을 YAML로 표현하면 다음과 같다.
YAML로 작성한 설정
application:
name: payment-service
port: 8080
production: true
developers:
- Hong
- Kim
jobs:
- name: payment-reconciliation
enabled: true
- name: settlement
enabled: false
database:
type: mysql
host: localhost
port: 3306
두 형식 모두 동일한 데이터 구조를 표현한다.
하지만 표현 방식에는 명확한 차이가 있다.
| 비교 항목 | JSON | YAML |
|---|---|---|
| 객체 표현 | { } | 들여쓰기 기반 Mapping |
| 배열 표현 | [ ] | 하이픈(-) |
| Key 표현 | 큰따옴표 필수 | 일반적으로 생략 가능 |
| 문자열 표현 | 큰따옴표 필수 | 상황에 따라 생략 가능 |
| 항목 구분 | 쉼표(,) | 줄바꿈과 들여쓰기 |
| 계층 구조 | 중괄호와 대괄호 | 들여쓰기 |
| 주석 | 표준 문법에서 미지원 | # 지원 |
| 마지막 쉼표 | 허용하지 않음 | 블록 스타일에서는 쉼표가 필요 없음 |
| 복잡한 설정 | 기호가 많아질 수 있음 | 상대적으로 간결하게 표현 가능 |
이처럼 단순한 설정 파일에서는 YAML이 더 읽기 쉬운 형태로 보일 수 있다.
특히 중첩된 객체나 배열이 여러 개 존재하는 경우에는 중괄호와 쉼표가 없어 전체 구조를 비교적 직관적으로 파악할 수 있다.
하지만 여기서 한 가지 중요한 점이 있다.
YAML이 항상 JSON보다 읽기 쉬운 것은 아니다.
YAML에는 JSON에 없는 다양한 표현 기능이 존재하고, 이러한 기능을 복합적으로 사용하면 오히려 설정 파일의 의미를 이해하기 어려워질 수 있다.
YAML은 JSON보다 다양한 표현 기능을 제공한다
JSON은 객체, 배열, 문자열, 숫자, Boolean, Null 등의 기본 데이터 타입을 중심으로 구성된다.
반면 YAML은 이러한 데이터 구조 외에도 설정 파일을 간결하게 작성하기 위한 다양한 표현 기능을 제공한다.
대표적으로 다음과 같은 기능이 있다.
- Anchor
- Alias
- Merge Key
- 여러 줄 문자열
- 여러 YAML 문서 구분
- 명시적인 데이터 타입 표현
이러한 기능들은 반복되는 설정을 줄이고 복잡한 데이터를 표현하는 데 도움이 된다.
하지만 문법을 이해하지 못하면 설정의 실제 값을 파악하기 어려울 수도 있다.
YAML의 Anchor와 Alias
YAML에서는 특정 데이터에 이름을 부여하고 다른 위치에서 참조할 수 있다.
이를 위해 사용하는 기능이 Anchor와 Alias이다.
Anchor란?
Anchor는 YAML 데이터에 이름을 부여하는 기능이다.
앰퍼샌드(&)를 사용한다.
defaults: &common
timeout: 30
retries: 3
여기서 다음 부분이 Anchor이다.
&common
defaults라는 Mapping에 common이라는 Anchor 이름을 부여한 것이다.
Anchor는 YAML 문서 내부에서 해당 데이터를 다시 참조할 수 있도록 한다.
Alias란?
Alias는 앞에서 정의한 Anchor를 참조하는 기능이다.
별표(*)를 사용한다.
defaults: &common
timeout: 30
retries: 3
backup: *common
여기서 *common은 앞에서 정의한 &common을 참조한다.
따라서 backup에는 defaults와 동일한 Mapping 데이터가 연결된다.
이를 개념적으로 풀어 쓰면 다음과 같은 형태이다.
defaults:
timeout: 30
retries: 3
backup:
timeout: 30
retries: 3
이러한 기능은 반복되는 설정을 줄이는 데 도움이 된다.
flowchart TD
A["defaults Anchor: common"] --> B["timeout: 30"]
A --> C["retries: 3"]
D["backup Alias: common"] --> A
다만 Anchor와 Alias는 프로그래밍 언어의 변수처럼 값을 동적으로 계산하는 기능은 아니다.
YAML 문서 내부에서 이미 정의된 노드를 참조하는 기능이다.
또한 역직렬화 과정에서 참조 대상의 동일성이 유지되는지는 사용하는 라이브러리와 데이터 구조에 따라 달라질 수 있다.
YAML의 Merge Key
Anchor와 Alias를 사용하면 데이터 전체를 참조할 수 있다.
그런데 기존 설정의 일부를 재사용하면서 특정 값만 변경하고 싶을 수도 있다.
이러한 상황에서는 일부 YAML 처리기가 지원하는 Merge Key 기능을 활용할 수 있다.
Merge Key는 <<로 표현한다.
다음 예시를 살펴보자.
defaults: &defaults
timeout: 30
retries: 3
enabled: true
development:
<<: *defaults
timeout: 10
production:
<<: *defaults
retries: 5
여기서 defaults에는 공통 설정이 정의되어 있다.
defaults: &defaults
timeout: 30
retries: 3
enabled: true
development에서는 공통 설정을 가져오면서 timeout만 변경한다.
development:
<<: *defaults
timeout: 10
production에서는 retries만 변경한다.
production:
<<: *defaults
retries: 5
Merge Key를 지원하는 파서에서 이를 해석하면 개념적으로 다음과 같은 데이터가 된다.
defaults:
timeout: 30
retries: 3
enabled: true
development:
timeout: 10
retries: 3
enabled: true
production:
timeout: 30
retries: 5
enabled: true
이 구조를 Mermaid로 표현하면 다음과 같다.
flowchart TD
A["공통 설정"] --> B["timeout: 30"]
A --> C["retries: 3"]
A --> D["enabled: true"]
A --> E["Development"]
A --> F["Production"]
E --> G["timeout을 10으로 재정의"]
F --> H["retries를 5로 재정의"]
이를 통해 여러 환경에서 공통으로 사용하는 설정을 중복해서 작성하지 않을 수 있다.
Merge Key 사용 시 주의사항
여기서 중요한 차이점이 있다.
Anchor와 Alias는 YAML의 기본 문법에 포함되지만, << Merge Key는 YAML 1.1에서 별도로 정의되었던 확장 기능이다.
YAML 1.2의 핵심 규격에는 Merge Key가 포함되어 있지 않다.
따라서 사용하는 YAML 파서에 따라 <<가 Mapping 병합 기능으로 동작하지 않거나 일반적인 Key로 처리될 수 있다.
특히 여러 도구가 동일한 YAML 파일을 처리하는 환경에서는 Merge Key 지원 여부를 확인해야 한다.
실무에서는 반복 설정을 줄이는 장점뿐 아니라 파서 호환성과 설정의 명확성도 함께 고려하는 것이 좋다.
YAML의 고급 기능이 오히려 단점이 되는 이유
Anchor, Alias, Merge Key는 설정을 간결하게 작성하는 데 유용하다.
하지만 너무 많이 사용하면 실제 설정값을 파악하기 어려워진다.
예를 들어 다음 YAML을 살펴보자.
common: &common
replicas: 3
timeout: 30
database: &database
host: mysql
port: 3306
production:
<<: *common
database:
<<: *database
host: production-mysql
이 설정을 처음 본 개발자는 다음 내용을 추가로 확인해야 한다.
&common이 무엇을 의미하는가?*common은 어떤 데이터를 참조하는가?<<는 어떤 동작을 수행하는가?production의 최종 replicas는 몇 개인가?database.host는 어떤 값으로 결정되는가?
반면 같은 결과를 명시적으로 작성하면 다음과 같다.
production:
replicas: 3
timeout: 30
database:
host: production-mysql
port: 3306
파일의 길이는 늘어날 수 있지만 최종 설정을 바로 이해할 수 있다.
즉 YAML의 고급 기능은 중복을 줄이는 장점과 설정의 의미를 추적하기 어렵게 만드는 단점을 동시에 가진다.
이러한 특성 때문에 다음 두 가지를 구분하는 것이 중요하다.
설정 파일이 짧다는 것과 설정 파일을 이해하기 쉽다는 것은 같은 의미가 아니다.
반복을 줄이는 것도 중요하지만, 운영 환경에서는 실제로 어떤 설정이 적용되는지를 빠르게 파악할 수 있어야 한다.
특히 장애 대응 과정에서는 명시적인 설정이 유지보수에 유리할 수 있다.
YAML은 여러 줄 문자열을 지원한다
YAML에는 여러 줄로 이루어진 문자열을 간편하게 작성하는 기능도 있다.
대표적으로 |와 >를 사용한다.
Literal Block Scalar: |
파이프(|)를 사용하면 줄바꿈을 유지하는 여러 줄 문자열을 작성할 수 있다.
message: |
Hello
Kubernetes
YAML
이 값은 개념적으로 다음 문자열에 해당한다.
Hello\nKubernetes\nYAML\n
기본적으로 각 줄의 줄바꿈이 유지되고 마지막 줄바꿈도 포함된다.
이러한 기능은 Shell Script나 긴 설정 문자열을 작성할 때 유용하다.
예를 들어 다음과 같이 작성할 수 있다.
script: |
#!/bin/sh
echo "Application started"
echo "Environment: production"
Folded Block Scalar: >
꺾쇠(>)를 사용하면 일반적인 줄바꿈을 공백으로 접어서 하나의 문자열처럼 표현할 수 있다.
description: >
This application
provides payment
processing APIs.
기본적인 결과는 다음과 같다.
This application provides payment processing APIs.\n
일반적인 줄바꿈은 공백으로 변환되며, 빈 줄이나 들여쓰기된 줄 등에서는 별도의 규칙이 적용된다.
|와 >의 비교
| 문법 | 기능 | 대표 사용처 |
|---|---|---|
| | 줄바꿈 유지 | Shell Script, 인증서, 여러 줄 메시지 |
> | 일반적인 줄바꿈을 공백으로 변환 | 긴 설명, 긴 명령어 |
JSON에서도 여러 줄 문자열을 표현할 수 있지만, 문자열 내부의 줄바꿈은 \n 등으로 이스케이프해야 한다.
따라서 사람이 직접 작성하는 여러 줄 텍스트에서는 YAML이 더 편리할 수 있다.
YAML은 여러 문서를 하나의 파일에 작성할 수 있다
YAML은 ---를 사용해 여러 문서를 구분할 수 있다.
예를 들어 다음과 같이 작성할 수 있다.
name: application-a
port: 8080
---
name: application-b
port: 9090
이 파일에는 두 개의 YAML 문서가 존재한다.
첫 번째 문서는 다음과 같다.
name: application-a
port: 8080
두 번째 문서는 다음과 같다.
name: application-b
port: 9090
이러한 기능은 Kubernetes에서 여러 리소스를 하나의 파일로 관리할 때 활용할 수 있다.
apiVersion: v1
kind: ConfigMap
metadata:
name: application-config
data:
APP_ENV: production
---
apiVersion: v1
kind: Service
metadata:
name: application-service
spec:
selector:
app: my-app
ports:
- port: 80
targetPort: 8080
이 파일을 적용하면 ConfigMap과 Service를 함께 생성하거나 수정할 수 있다.
kubectl apply -f application.yaml
정상적으로 적용되면 다음과 같은 메시지가 출력될 수 있다.
configmap/application-config created
service/application-service created
JSON은 하나의 JSON 텍스트에 하나의 최상위 값을 표현한다.
여러 객체를 하나의 JSON 문서로 묶고 싶다면 배열 등의 구조를 사용해야 한다.
물론 NDJSON처럼 여러 JSON 데이터를 줄 단위로 나열하는 별도의 형식도 존재하지만, 이는 일반적인 단일 JSON 문서와는 구분된다.
이처럼 YAML의 다중 문서 기능은 여러 설정을 함께 관리하는 데 유용하다.
YAML과 JSON의 데이터 타입 비교
두 형식은 모두 문자열, 숫자, Boolean, Null, 객체, 배열에 해당하는 구조를 표현할 수 있다.
다만 데이터 타입을 표현하는 방식에는 차이가 있다.
| 데이터 타입 | JSON | YAML |
|---|---|---|
| 문자열 | "hello" | hello 또는 "hello" |
| 정수 | 30 | 30 |
| 실수 | 3.14 | 3.14 |
| Boolean | true, false | true, false |
| Null | null | null, ~ 등 |
| 객체 | { } | Mapping |
| 배열 | [ ] | Sequence |
| 명시적 타입 태그 | 지원하지 않음 | 지원 |
| Anchor / Alias | 지원하지 않음 | 지원 |
YAML은 다양한 타입 표현 기능을 제공하지만 그만큼 값이 어떤 타입으로 해석되는지 주의해야 한다.
예를 들어 다음 데이터를 살펴보자.
version: 1.0
enabled: true
code: 00123
이 값들은 파서와 스키마에 따라 개발자가 의도한 문자열이 아니라 숫자나 Boolean 등의 타입으로 해석될 수 있다.
따라서 문자열로 처리해야 하는 값은 따옴표를 사용하는 것이 안전하다.
version: "1.0"
enabled: "true"
code: "00123"
특히 YAML 1.1과 YAML 1.2 사이에는 일부 타입 해석 규칙에 차이가 있다.
예를 들어 YAML 1.1 계열의 일부 파서는 yes, no, on, off 같은 값을 Boolean으로 해석한다.
반면 YAML 1.2의 기본적인 Core Schema에서는 이러한 값들을 문자열로 취급한다.
이처럼 동일한 YAML 파일이라도 처리하는 파서의 버전과 스키마에 따라 값의 타입이 달라질 수 있다.
이 문제는 Kubernetes, Helm, Spring Boot처럼 서로 다른 YAML 처리기가 사용되는 환경에서 주의할 필요가 있다.
YAML과 JSON의 파싱 성능 차이
YAML과 JSON을 비교할 때 자주 언급되는 내용 중 하나가 파싱 성능이다.
일반적으로 JSON은 YAML보다 문법이 단순하기 때문에 빠른 파서를 구현하기 유리하다.
JSON은 객체, 배열, 문자열, 숫자, Boolean, Null 등으로 구성되며 문법이 비교적 제한적이다.
반면 YAML은 다음과 같은 기능을 추가로 처리해야 할 수 있다.
- 들여쓰기를 통한 계층 구조
- 다양한 문자열 표현 방식
- Anchor와 Alias
- 여러 줄 문자열
- 명시적인 타입 정보
- 여러 문서로 구성된 데이터
따라서 YAML 파서는 JSON 파서보다 처리해야 하는 문법 요소가 많을 수 있다.
flowchart TD
A["입력 데이터"] --> B["JSON Parser"]
A --> C["YAML Parser"]
B --> D["객체와 배열 구조 해석"]
C --> E["들여쓰기와 확장 문법 해석"]
D --> F["애플리케이션 데이터"]
E --> F
하지만 여기서 주의해야 할 점이 있다.
JSON이 항상 YAML보다 빠르다고 단정할 수는 없다.
실제 파싱 성능은 다음 요소에 따라 달라진다.
- 사용하는 프로그래밍 언어
- JSON/YAML 파서 구현체
- 데이터 크기
- 중첩 구조의 깊이
- Anchor와 Alias 사용 여부
- 타입 변환 및 객체 매핑 방식
예를 들어 최적화된 JSON 파서와 일반적인 YAML 파서를 비교하면 JSON이 빠른 경우가 많다.
반대로 단순한 YAML 문서를 효율적인 파서로 처리하는 경우에는 차이가 크지 않을 수도 있다.
따라서 성능이 중요한 시스템에서는 형식의 일반적인 특성뿐 아니라 실제 사용하는 라이브러리와 데이터를 기준으로 측정해야 한다.
데이터 처리 목적에 따른 차이
설정 파일과 API 응답은 데이터 처리 방식부터 다르다.
애플리케이션 설정 파일은 일반적으로 시작할 때 읽거나 설정을 갱신할 때만 읽는다.
반면 API 요청과 응답 데이터는 수많은 요청마다 반복적으로 직렬화하고 역직렬화할 수 있다.
flowchart TD
A["데이터 처리 목적"] --> B["설정 파일"]
A --> C["API 데이터 교환"]
B --> D["읽기 쉬운 구조 중요"]
B --> E["변경과 유지보수 중요"]
C --> F["반복적인 직렬화와 역직렬화"]
C --> G["파싱 비용과 호환성 중요"]
D --> H["YAML 활용"]
G --> I["JSON 활용"]
이러한 사용 패턴의 차이도 YAML과 JSON이 서로 다른 영역에서 널리 활용되는 이유 중 하나이다.
YAML과 JSON의 장단점 비교
지금까지 살펴본 특징을 바탕으로 두 형식의 장단점을 정리해보자.
YAML의 장점
1. 사람이 읽기 쉽다.
중괄호와 쉼표 대신 들여쓰기를 사용하기 때문에 복잡한 설정을 비교적 간결하게 표현할 수 있다.
2. 작성해야 할 문법 요소가 적다.
일반적인 문자열에서는 큰따옴표를 생략할 수 있고, 배열은 하이픈으로 표현할 수 있다.
3. 주석을 지원한다.
설정의 목적이나 주의사항을 파일 내부에 작성할 수 있다.
4. 반복되는 데이터를 재사용할 수 있다.
Anchor와 Alias를 이용해 동일한 데이터를 여러 위치에서 참조할 수 있다.
5. 여러 줄 문자열을 편리하게 작성할 수 있다.
|와 >를 사용해 긴 문자열을 읽기 쉬운 형태로 표현할 수 있다.
6. 여러 문서를 하나의 파일에 포함할 수 있다.
---를 사용해 여러 YAML 문서를 구분할 수 있다.
YAML의 단점
1. 들여쓰기에 민감하다.
공백 하나가 잘못되면 문법 오류가 발생하거나 데이터 구조가 달라질 수 있다.
2. 데이터 타입 해석이 모호할 수 있다.
따옴표를 생략한 문자열이 숫자나 Boolean으로 해석될 수 있다.
3. 고급 문법이 복잡해질 수 있다.
Anchor, Alias, Merge Key 등을 과도하게 사용하면 실제 설정을 이해하기 어려워질 수 있다.
4. 파서의 버전과 구현체에 따라 차이가 발생할 수 있다.
특히 YAML 1.1과 YAML 1.2의 타입 처리 방식에는 차이가 있다.
5. JSON보다 처리 비용이 커질 수 있다.
지원하는 문법이 복잡하므로 동일한 조건에서 파싱 비용이 더 크게 발생할 가능성이 있다.
JSON의 장점
1. 문법이 단순하고 명확하다.
객체, 배열, 문자열 등의 구조를 제한된 문법으로 표현한다.
2. 프로그래밍 언어 간 데이터 교환에 적합하다.
다양한 언어에서 JSON 파서를 제공하기 때문에 호환성이 높다.
3. 빠른 파서 구현에 유리하다.
문법이 단순하기 때문에 고성능 파서를 구현하고 활용하기 쉽다.
4. 데이터 구조가 명시적이다.
객체는 중괄호, 배열은 대괄호로 구분되므로 들여쓰기와 관계없이 구조를 파악할 수 있다.
5. 한 줄로 압축할 수 있다.
불필요한 공백과 줄바꿈을 제거해 데이터를 간결하게 표현할 수 있다.
6. REST API에서 널리 사용된다.
브라우저와 백엔드 프레임워크에서 JSON을 쉽게 처리할 수 있다.
JSON의 단점
1. 중괄호와 대괄호가 많아질 수 있다.
중첩 구조가 복잡할수록 문법 기호의 비중이 증가한다.
2. 큰따옴표와 쉼표를 정확하게 작성해야 한다.
작은 문법 실수로도 파싱 오류가 발생할 수 있다.
3. 표준 문법에서 주석을 지원하지 않는다.
설정 파일에 설명을 추가하기 어렵다.
4. 데이터 재사용을 위한 Anchor나 Alias 기능이 없다.
동일한 설정을 여러 위치에서 사용하려면 중복해서 작성하거나 애플리케이션에서 별도로 처리해야 한다.
5. 여러 줄 문자열을 직접 작성하기 불편할 수 있다.
줄바꿈을 이스케이프 문자로 표현해야 한다.
YAML과 JSON 전체 비교
| 비교 항목 | YAML | JSON |
|---|---|---|
| 정식 명칭 | YAML Ain’t Markup Language | JavaScript Object Notation |
| 주요 목적 | 사람이 읽기 쉬운 데이터 표현 | 간결하고 명확한 데이터 교환 |
| 직렬화 형식 | 지원 | 지원 |
| 언어 독립성 | 지원 | 지원 |
| 가독성 | 설정 파일에 유리 | 단순 데이터 구조에 유리 |
| 객체 표현 | Mapping | Object |
| 배열 표현 | Sequence | Array |
| 계층 구조 | 들여쓰기 중심 | 중괄호와 대괄호 |
| 문자열 따옴표 | 생략 가능 | 큰따옴표 필요 |
| 주석 | 지원 | 표준 문법에서 미지원 |
| 여러 줄 문자열 | \|, > 지원 | 이스케이프 문자 사용 |
| Anchor / Alias | 지원 | 미지원 |
| Merge Key | 일부 파서에서 지원 | 미지원 |
| 여러 문서 | ---로 구분 가능 | 단일 JSON 텍스트는 하나의 최상위 값 |
| 문법 복잡도 | 상대적으로 높음 | 상대적으로 낮음 |
| 파싱 성능 | 구현에 따라 추가 비용 가능 | 일반적으로 최적화에 유리 |
| 타입 해석 | 파서와 스키마에 따른 차이 가능 | 비교적 명확 |
| 대표 사용처 | Kubernetes, Spring Boot, Docker Compose | REST API, 웹 애플리케이션 |
| 설정 파일 적합성 | 높음 | 사용 가능 |
| API 데이터 교환 | 사용 가능 | 매우 널리 사용 |
두 형식은 서로 다른 장점을 가지고 있기 때문에 특정 형식이 모든 상황에서 우월하다고 판단하기는 어렵다.
중요한 것은 데이터를 어떤 목적으로 사용하느냐이다.
Kubernetes는 YAML만 지원할까?
Kubernetes를 사용하다 보면 대부분 YAML 파일로 리소스를 정의한다.
그렇다면 Kubernetes는 YAML만 지원할까?
그렇지 않다.
Kubernetes는 YAML과 JSON 형식의 Manifest를 모두 사용할 수 있다.
예를 들어 다음과 같은 ConfigMap을 생성한다고 가정하자.
YAML Manifest
apiVersion: v1
kind: ConfigMap
metadata:
name: application-config
data:
APP_ENV: production
LOG_LEVEL: INFO
동일한 리소스를 JSON으로 작성할 수도 있다.
JSON Manifest
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "application-config"
},
"data": {
"APP_ENV": "production",
"LOG_LEVEL": "INFO"
}
}
두 파일 모두 Kubernetes에 적용할 수 있다.
YAML 파일을 사용하는 경우:
kubectl apply -f configmap.yaml
JSON 파일을 사용하는 경우:
kubectl apply -f configmap.json
새로운 리소스를 생성하면 다음과 같은 메시지가 출력될 수 있다.
configmap/application-config created
즉 Kubernetes가 YAML만 이해하는 것은 아니다.
YAML을 사용하는 경우 Kubernetes 클라이언트는 Manifest를 해석해 Kubernetes API가 처리할 수 있는 형태로 전달한다.
Kubernetes의 리소스 구조는 YAML 문법 자체가 아니라 API의 데이터 모델과 스키마로 정의된다.
따라서 같은 Kubernetes 리소스를 YAML과 JSON 양쪽으로 표현할 수 있다.
kubectl을 이용해 YAML과 JSON 출력 비교하기
Kubernetes에 이미 생성된 리소스를 조회할 때도 원하는 출력 형식을 지정할 수 있다.
예를 들어 Deployment를 조회한다고 가정하자.
kubectl get deployment my-app -o yaml
이 명령어는 Deployment 정보를 YAML 형식으로 출력한다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
반대로 JSON 형식으로 조회할 수도 있다.
kubectl get deployment my-app -o json
출력 형식은 다음과 같다.
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "my-app"
},
"spec": {
"replicas": 3
}
}
위 출력은 주요 필드만 간추린 예시이며, 실제 kubectl get 결과에는 더 많은 메타데이터와 상태 정보가 포함된다.
두 명령어는 동일한 Kubernetes 리소스를 조회하지만 출력 형식이 다르다.
| 명령어 | 출력 형식 |
|---|---|
kubectl get deployment my-app -o yaml | YAML |
kubectl get deployment my-app -o json | JSON |
이 기능을 이해하면 Kubernetes 리소스를 사람이 읽기 쉬운 형태로 확인하거나, 자동화 프로그램에서 처리하기 쉬운 형태로 가져올 수 있다.
YAML과 JSON의 변환
YAML과 JSON은 기본적인 자료구조가 유사하기 때문에 서로 변환할 수 있다.
예를 들어 다음 YAML이 있다고 가정하자.
application:
name: my-app
port: 8080
features:
- login
- payment
이를 JSON으로 변환하면 다음과 같다.
{
"application": {
"name": "my-app",
"port": 8080,
"features": [
"login",
"payment"
]
}
}
두 데이터는 동일한 구조를 표현한다.
다만 YAML의 모든 기능을 JSON에서 그대로 보존할 수 있는 것은 아니다.
예를 들어 YAML에는 다음과 같은 정보가 포함될 수 있다.
- 주석
- Anchor 이름
- Alias
- 여러 문서 구분
- 명시적인 타입 태그
- 문자열 표현 스타일
이 중 일부는 JSON에 직접 대응하는 문법이 없다.
따라서 YAML을 JSON으로 변환할 때는 실제 데이터의 값은 유지하더라도 YAML 고유의 표현 정보가 사라질 수 있다.
예를 들어 다음 YAML을 살펴보자.
# 애플리케이션 설정
application:
name: my-app
JSON으로 변환하면 일반적으로 다음과 같이 표현된다.
{
"application": {
"name": "my-app"
}
}
YAML에 작성된 주석은 JSON에 포함되지 않는다.
따라서 변환 과정에서는 데이터 자체와 표현 방식이 서로 다르다는 점을 이해해야 한다.
YAML과 JSON을 변환하는 방법
YAML을 JSON으로 변환할 때는 yq를 사용할 수 있다.
예를 들어 다음 파일이 있다고 가정하자.
application.yaml
application:
name: payment-service
port: 8080
enabled: true
다음 명령어를 실행한다.
yq -o=json '.' application.yaml
여기서 각 요소의 의미는 다음과 같다.
| 요소 | 의미 |
|---|---|
yq | YAML 처리 도구 |
-o=json | JSON 형식으로 출력 |
. | 전체 문서 선택 |
application.yaml | 입력 파일 |
출력 결과는 다음과 같다.
{
"application": {
"name": "payment-service",
"port": 8080,
"enabled": true
}
}
반대로 JSON을 YAML로 변환할 수도 있다.
application.json
{
"application": {
"name": "payment-service",
"port": 8080,
"enabled": true
}
}
다음 명령어를 실행한다.
yq -P -o=yaml '.' application.json
출력 결과는 다음과 같다.
application:
name: payment-service
port: 8080
enabled: true
이러한 변환 기능은 다음과 같은 상황에서 유용하다.
- JSON으로 제공되는 설정을 YAML로 관리하고 싶은 경우
- YAML 설정을 JSON 기반 프로그램에 전달해야 하는 경우
- Kubernetes Manifest를 다른 형식으로 분석해야 하는 경우
- CI/CD에서 서로 다른 설정 형식을 처리해야 하는 경우
다만 사용하는 yq의 종류와 버전에 따라 명령어 문법이 다를 수 있다.
위 예시는 Mike Farah의 yq v4 계열을 기준으로 작성한 것이다.
JSON과 YAML을 Java에서 처리하는 방법
백엔드 개발 관점에서는 두 형식이 객체와 어떻게 연결되는지도 중요하다.
Java에서는 Jackson을 사용해 JSON을 직렬화하고 역직렬화할 수 있다.
또한 Jackson YAML 모듈을 사용하면 YAML도 객체로 변환할 수 있다.
Java 객체 정의
먼저 간단한 설정 객체를 정의하자.
public record ApplicationConfig(
String name,
int port,
boolean enabled
) {
}
다음 객체를 생성한다.
ApplicationConfig config = new ApplicationConfig(
"payment-service",
8080,
true
);
JSON 직렬화
Jackson의 ObjectMapper를 사용하면 객체를 JSON으로 변환할 수 있다.
import com.fasterxml.jackson.databind.ObjectMapper;
public class JsonExample {
public static void main(String[] args) throws Exception {
ObjectMapper mapper = new ObjectMapper();
ApplicationConfig config = new ApplicationConfig(
"payment-service",
8080,
true
);
String json = mapper
.writerWithDefaultPrettyPrinter()
.writeValueAsString(config);
System.out.println(json);
}
}
출력 결과:
{
"name": "payment-service",
"port": 8080,
"enabled": true
}
YAML 직렬화
Jackson YAML 모듈을 사용하면 YAMLFactory를 통해 YAML을 처리할 수 있다.
프로젝트에는 jackson-dataformat-yaml 의존성이 필요하다.
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
public class YamlExample {
public static void main(String[] args) throws Exception {
ObjectMapper mapper = new ObjectMapper(
new YAMLFactory()
);
ApplicationConfig config = new ApplicationConfig(
"payment-service",
8080,
true
);
String yaml = mapper.writeValueAsString(config);
System.out.println(yaml);
}
}
출력 형식은 Jackson 버전과 설정에 따라 차이가 있을 수 있지만 다음과 같은 구조가 된다.
---
name: "payment-service"
port: 8080
enabled: true
JSON과 YAML 모두 동일한 Java 객체를 기반으로 직렬화할 수 있다는 점을 확인할 수 있다.
flowchart TD
A["Java ApplicationConfig 객체"] --> B["Jackson ObjectMapper"]
B --> C["JSON Serializer"]
B --> D["YAML Serializer"]
C --> E["JSON 데이터"]
D --> F["YAML 데이터"]
즉 JSON과 YAML은 서로 다른 데이터 표현 방식이지만, 애플리케이션에서는 동일한 객체 모델을 사용해 처리할 수 있다.
실무에서는 YAML과 JSON 중 무엇을 선택해야 할까?
두 형식의 특징을 이해했다면 실제 개발 환경에서 어떤 기준으로 선택해야 하는지 살펴보자.
1. REST API에서는 JSON이 일반적으로 적합하다
REST API에서는 요청과 응답 데이터를 반복적으로 처리한다.
예를 들어 다음과 같은 API가 있다고 가정하자.
POST /api/payments
Content-Type: application/json
요청 데이터:
{
"orderId": 1001,
"amount": 50000,
"currency": "KRW"
}
이러한 환경에서는 JSON이 유리하다.
주요 이유는 다음과 같다.
- 대부분의 웹 프레임워크에서 기본적으로 지원한다.
- 클라이언트와 서버에서 쉽게 직렬화하고 역직렬화할 수 있다.
- 단순한 문법으로 데이터를 표현할 수 있다.
- 브라우저와 JavaScript 환경에서 처리하기 편리하다.
- OpenAPI 등 API 생태계에서 널리 사용된다.
따라서 일반적인 HTTP API의 요청과 응답에는 JSON을 우선적으로 고려할 수 있다.
2. 애플리케이션 설정 파일에서는 YAML이 유리할 수 있다
Spring Boot의 설정 파일을 생각해보자.
server:
port: 8080
spring:
application:
name: payment-service
datasource:
url: jdbc:mysql://localhost:3306/payment
username: payment_user
password: ${DB_PASSWORD}
이러한 설정은 개발자가 직접 읽고 수정하는 경우가 많다.
또한 설정 항목이 계층 구조로 이루어져 있다.
이때 YAML을 사용하면 데이터의 구조를 비교적 간결하게 표현할 수 있다.
주석을 통해 설정의 의도를 설명할 수도 있다.
따라서 설정 파일에서는 YAML이 좋은 선택이 될 수 있다.
3. Kubernetes Manifest에서는 YAML이 일반적이다
Kubernetes는 JSON과 YAML을 모두 지원하지만, 실제로 리소스를 정의할 때는 YAML을 많이 사용한다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: payment-service
spec:
replicas: 3
selector:
matchLabels:
app: payment-service
template:
metadata:
labels:
app: payment-service
spec:
containers:
- name: payment-service
image: example/payment-service:1.0.0
Kubernetes Manifest는 사람이 구조를 이해하고 설정을 변경해야 하는 경우가 많다.
특히 Deployment, Service, ConfigMap, Secret 등을 함께 관리하는 환경에서는 YAML의 가독성과 다중 문서 기능이 유용하다.
4. 자동화 프로그램에서 생성하는 데이터는 JSON이 편리할 수 있다
프로그램이 데이터를 생성하고 다른 프로그램이 이를 처리하는 환경에서는 사람이 직접 읽기 쉬운가보다 데이터 형식의 단순성과 호환성이 중요할 수 있다.
예를 들어 다음과 같은 상황이다.
flowchart LR
A["Backend Service"] --> B["JSON 직렬화"]
B --> C["HTTP API"]
C --> D["JSON 역직렬화"]
D --> E["Client Application"]
이러한 환경에서는 JSON이 실용적인 선택인 경우가 많다.
반면 사람이 직접 작성하고 변경하는 설정에서는 YAML이 유리할 수 있다.
따라서 데이터를 사용하는 주체에 따라 선택 기준이 달라진다.
YAML과 JSON을 선택하는 기준
| 사용 환경 | 권장 형식 | 주요 이유 |
|---|---|---|
| REST API 요청·응답 | JSON | 높은 호환성, 단순한 파싱 |
| Spring Boot 설정 파일 | YAML | 계층 구조 표현과 가독성 |
| Kubernetes Manifest | YAML | 선언적 리소스 설정 관리 |
| Docker Compose | YAML | 복잡한 컨테이너 구성 표현 |
| GitHub Actions | YAML | Workflow 설정과 주석 지원 |
| 프로그램 간 데이터 교환 | JSON | 넓은 라이브러리 지원 |
| 사람이 수정하는 복잡한 설정 | YAML | 간결한 문법과 주석 |
| 외부 시스템으로 전달하는 데이터 | JSON | 명확한 데이터 구조와 호환성 |
| 자동 생성되는 대량의 데이터 | JSON | 파서 지원과 처리 효율 |
| 반복적인 공통 설정 | YAML | Anchor와 Alias 활용 가능 |
물론 이 표가 절대적인 기준은 아니다.
예를 들어 Kubernetes에서도 JSON Manifest를 사용할 수 있고, 애플리케이션의 설정을 JSON으로 관리할 수도 있다.
중요한 것은 다음과 같은 관점이다.
사람이 자주 읽고 수정하는 데이터인가, 아니면 프로그램이 반복적으로 교환하고 처리하는 데이터인가?
이 질문을 기준으로 형식을 선택하면 대부분의 상황에서 합리적인 판단을 내릴 수 있다.
실무에서 주의해야 할 YAML과 JSON의 공통 문제
YAML과 JSON은 문법이 다르지만 공통적으로 주의해야 하는 문제도 있다.
1. 중복된 Key
다음 JSON을 살펴보자.
{
"port": 8080,
"port": 9090
}
동일한 Key가 두 번 등장한다.
일부 JSON 파서는 마지막 값을 사용하기도 하지만, 중복 Key 처리 방식은 구현체마다 다를 수 있다.
따라서 중복된 Key를 작성하지 않아야 한다.
YAML에서도 마찬가지이다.
port: 8080
port: 9090
YAML Mapping에서도 Key는 고유해야 한다.
하지만 실제 파서의 오류 처리 방식에는 차이가 있을 수 있으므로 설정 검증 과정에서 중복 Key를 확인하는 것이 좋다.
2. 데이터 타입 불일치
다음 JSON을 살펴보자.
{
"port": "8080"
}
이 값은 문자열이다.
반면 다음 값은 숫자이다.
{
"port": 8080
}
YAML에서도 동일한 문제가 발생할 수 있다.
port: "8080"
port: 8080
두 값은 타입이 다르다.
특히 애플리케이션의 설정이나 API 요청에서 타입이 다르면 역직렬화 오류가 발생할 수 있다.
따라서 데이터 형식뿐 아니라 애플리케이션이 기대하는 타입을 함께 확인해야 한다.
3. 깊은 중첩 구조
JSON과 YAML 모두 중첩된 객체와 배열을 표현할 수 있다.
하지만 중첩 구조가 지나치게 깊어지면 사람이 읽기 어려워진다.
application:
server:
connection:
pool:
settings:
timeout:
value: 30
JSON도 마찬가지이다.
{
"application": {
"server": {
"connection": {
"pool": {
"settings": {
"timeout": {
"value": 30
}
}
}
}
}
}
}
중첩 구조가 지나치게 복잡하다면 데이터 모델 자체를 단순화하는 것이 좋다.
단순히 YAML을 JSON으로 변경하거나 JSON을 YAML로 변경한다고 구조적 복잡성이 사라지는 것은 아니다.
4. 외부에서 전달받은 데이터 검증
YAML과 JSON 모두 외부에서 전달받은 데이터를 처리할 수 있다.
하지만 데이터를 역직렬화했다고 해서 그 값이 안전하거나 올바르다는 의미는 아니다.
예를 들어 다음 값이 들어올 수 있다.
{
"amount": -10000,
"quantity": 0
}
문법적으로는 올바른 JSON이지만 비즈니스 규칙에서는 허용되지 않을 수 있다.
따라서 역직렬화 이후에도 데이터 검증이 필요하다.
또한 YAML은 Alias나 사용자 정의 타입 같은 기능을 지원하므로, 신뢰할 수 없는 YAML 데이터를 처리할 때는 안전한 로딩 방식과 파서의 보안 설정을 고려해야 한다.
정리
YAML과 JSON은 모두 구조화된 데이터를 표현하고 교환하기 위한 대표적인 텍스트 기반 데이터 직렬화 형식이다.
하지만 두 형식은 서로 다른 방향으로 설계되었다.
JSON은 JavaScript 객체 표기법에서 유래했으며, 중괄호와 대괄호를 사용해 데이터 구조를 명시적으로 표현한다.
문법이 단순하고 대부분의 프로그래밍 언어에서 지원하기 때문에 REST API나 애플리케이션 간 데이터 교환에 널리 사용된다.
반면 YAML은 사람이 데이터를 쉽게 읽고 작성할 수 있도록 설계되었다.
들여쓰기로 계층 구조를 표현하고, 하이픈으로 배열을 작성하며, 주석을 통해 설정의 의미를 설명할 수 있다.
또한 Anchor, Alias, 여러 줄 문자열, 다중 문서 등의 기능을 제공하므로 복잡한 설정을 간결하게 작성할 수 있다.
다만 YAML의 다양한 기능은 장점인 동시에 단점이 될 수 있다.
복잡한 참조 구조와 타입 해석 규칙 때문에 실제 설정값을 이해하기 어려워질 수 있으며, 사용하는 파서와 스키마에 따라 처리 결과가 달라질 수 있기 때문이다.
두 형식의 핵심적인 차이를 정리하면 다음과 같다.
| 핵심 관점 | YAML | JSON |
|---|---|---|
| 설계 방향 | 사람 중심의 가독성 | 단순하고 명확한 데이터 교환 |
| 데이터 구조 | Mapping, Sequence, Scalar | Object, Array, Primitive Value |
| 문법 특징 | 들여쓰기 중심 | 중괄호, 대괄호, 쉼표 중심 |
| 주요 장점 | 가독성, 주석, 다양한 표현 기능 | 단순성, 호환성, 파싱 효율 |
| 주요 단점 | 복잡한 문법과 타입 해석 | 주석 미지원, 반복적인 기호 |
| 대표 활용 | 설정 파일 및 Kubernetes | REST API 및 시스템 간 통신 |
결국 YAML과 JSON 중 어느 형식이 더 좋은지를 결정하기보다는, 데이터의 사용 목적에 따라 적절한 형식을 선택하는 것이 중요하다.
사람이 자주 읽고 수정하는 설정 파일이라면 YAML이 유리할 수 있다.
반면 프로그램이 빈번하게 데이터를 교환하고 처리해야 한다면 JSON이 실용적인 선택인 경우가 많다.
또한 Kubernetes에서는 두 형식을 모두 사용할 수 있지만, 사람이 관리하기 쉬운 YAML을 일반적으로 사용한다.
따라서 Kubernetes 환경에서 YAML을 이해하는 것은 단순히 설정 파일의 문법을 배우는 것을 넘어, Kubernetes 리소스의 구조와 설정 관리 방식을 이해하는 데 도움이 된다.
한 줄 요약
YAML은 사람이 읽고 작성하기 쉬운 데이터 직렬화 형식이고, JSON은 단순하고 명확한 문법으로 시스템 간 데이터를 교환하기에 적합한 형식이다. 두 형식은 우열의 관계가 아니라 사용 목적에 따라 선택해야 하는 상호 보완적인 기술이다.
03. Yaml in Kubernetes
Kubernetes YAML과 선언형 리소스 관리
Kubernetes는 Pod, Deployment, Service, ConfigMap, Secret 등 다양한 리소스를 통해 애플리케이션을 실행하고 관리한다.
이러한 리소스를 생성하는 방법은 크게 두 가지로 구분할 수 있다.
바로 명령형(Imperative) 관리 방식과 선언형(Declarative) 관리 방식이다.
명령형 방식은 Kubernetes에 수행해야 할 작업을 직접 명령하는 방식이고, 선언형 방식은 시스템이 유지해야 하는 원하는 상태를 정의하는 방식이다.
예를 들어 Nginx 컨테이너를 실행하는 Pod를 생성한다고 가정하자.
명령형 방식에서는 다음과 같이 명령어를 실행할 수 있다.
kubectl run nginx --image=nginx:1.27
반면 선언형 방식에서는 다음과 같이 YAML 파일을 작성할 수 있다.
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
그리고 다음 명령어로 Kubernetes에 적용한다.
kubectl apply -f pod.yaml
두 방식 모두 Nginx Pod를 생성할 수 있다.
하지만 리소스를 관리하는 관점에는 중요한 차이가 있다.
명령형 방식은 어떤 작업을 수행할 것인가(How) 에 초점을 맞춘다.
반면 선언형 방식은 어떤 상태가 되어야 하는가(What) 에 초점을 맞춘다.
이러한 차이는 리소스를 처음 생성할 때보다, 이미 존재하는 리소스를 수정하거나 동일한 설정을 반복해서 적용할 때 더욱 명확하게 드러난다.
이번에는 Kubernetes Manifest의 구조를 살펴보고, 실제 Pod를 생성하면서 명령형 방식과 선언형 방식의 차이를 알아본다.
Kubernetes와 YAML의 관계
Kubernetes에서는 다양한 리소스를 YAML 파일로 정의할 수 있다.
대표적인 리소스는 다음과 같다.
| 리소스 | 주요 역할 |
|---|---|
| Pod | 하나 이상의 컨테이너를 실행하는 기본 단위 |
| Deployment | 애플리케이션 배포와 업데이트 관리 |
| ReplicaSet | 지정한 수량의 Pod 유지 |
| StatefulSet | 안정적인 식별자와 스토리지가 필요한 애플리케이션 관리 |
| DaemonSet | 특정 Node에 Pod 실행 |
| Service | Pod에 대한 네트워크 접근 제공 |
| ConfigMap | 애플리케이션의 일반 설정 관리 |
| Secret | 비밀번호나 토큰 등의 민감한 데이터 관리 |
| PersistentVolumeClaim | 스토리지 사용 요청 |
| HorizontalPodAutoscaler | Pod 수량 자동 조정 |
이러한 리소스는 각각 다른 목적을 가지고 있지만, Kubernetes API를 통해 생성하고 관리한다는 공통점이 있다.
Kubernetes Manifest는 이러한 리소스의 구성 정보를 파일로 표현한 것이다.
flowchart TD
A["Kubernetes Manifest"] --> B["Pod"]
A --> C["Deployment"]
A --> D["Service"]
A --> E["ConfigMap"]
A --> F["Secret"]
B --> G["컨테이너 실행"]
C --> H["애플리케이션 배포 관리"]
D --> I["네트워크 연결"]
E --> J["일반 설정 제공"]
F --> K["민감한 설정 제공"]
YAML은 Kubernetes 전용 언어가 아니다.
YAML 자체는 구조화된 데이터를 표현하기 위한 데이터 직렬화 형식이다.
Kubernetes는 이 형식을 사용하여 리소스의 원하는 상태를 표현할 수 있도록 한다.
따라서 다음 두 개념을 구분해야 한다.
YAML은 데이터를 표현하는 형식이고, Kubernetes Manifest는 Kubernetes 리소스를 정의한 설정이다.
실제로 Kubernetes는 YAML뿐 아니라 JSON 형식의 Manifest도 지원한다.
다만 사람이 직접 읽고 작성하기 쉬운 특성 때문에 YAML을 일반적으로 많이 사용한다.
Kubernetes Manifest의 기본 구조
Kubernetes에서 사용하는 Manifest에는 여러 리소스에서 공통으로 등장하는 필드들이 있다.
대표적인 필드는 다음과 같다.
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
여기서 핵심적인 필드는 다음 네 가지이다.
| 필드 | 의미 |
|---|---|
apiVersion | 리소스를 처리할 Kubernetes API 버전 |
kind | 생성할 리소스의 종류 |
metadata | 리소스의 이름과 부가 정보 |
spec | 리소스의 원하는 상태 |
Pod나 Deployment처럼 spec을 사용하는 리소스에서는 이 네 가지 필드를 중심으로 Manifest를 이해할 수 있다.
다만 모든 Kubernetes 리소스에 spec이 필수로 존재하는 것은 아니다.
예를 들어 ConfigMap에서는 다음과 같이 data를 사용한다.
apiVersion: v1
kind: ConfigMap
metadata:
name: application-config
data:
APP_ENV: production
LOG_LEVEL: INFO
따라서 Kubernetes Manifest의 공통적인 구조를 이해하되, 실제 필드 구성은 리소스 종류에 따라 달라질 수 있다는 점을 알아두어야 한다.
apiVersion: 리소스의 API 버전
apiVersion은 해당 리소스를 어떤 Kubernetes API 버전으로 처리할 것인지 지정한다.
예를 들어 Pod는 다음과 같이 정의한다.
apiVersion: v1
Deployment는 다음과 같이 정의한다.
apiVersion: apps/v1
HorizontalPodAutoscaler는 다음과 같이 정의할 수 있다.
apiVersion: autoscaling/v2
같은 Kubernetes 리소스라도 API 버전에 따라 지원하는 필드나 동작이 달라질 수 있다.
또한 리소스의 종류에 따라 사용해야 하는 API Group과 버전이 다르다.
| 리소스 | 대표적인 apiVersion |
|---|---|
| Pod | v1 |
| Service | v1 |
| ConfigMap | v1 |
| Secret | v1 |
| Deployment | apps/v1 |
| StatefulSet | apps/v1 |
| DaemonSet | apps/v1 |
| Job | batch/v1 |
| CronJob | batch/v1 |
| HorizontalPodAutoscaler | autoscaling/v2 |
예를 들어 Deployment를 생성하면서 다음과 같이 작성하면 올바르지 않다.
apiVersion: v1
kind: Deployment
Deployment는 apps/v1 API를 사용해야 하기 때문이다.
올바른 설정은 다음과 같다.
apiVersion: apps/v1
kind: Deployment
사용하는 클러스터에서 어떤 API 리소스를 지원하는지 확인하려면 다음 명령어를 사용할 수 있다.
kubectl api-resources
특정 API 버전에 속한 리소스를 조회할 수도 있다.
kubectl api-resources --api-group=apps
이러한 명령어는 새로운 Kubernetes 리소스를 사용하거나 기존 Manifest를 업데이트할 때 유용하다.
kind: 생성할 리소스의 종류
kind는 Kubernetes에서 생성하거나 관리할 리소스의 종류를 나타낸다.
예를 들어 다음 설정은 Pod를 의미한다.
kind: Pod
다음 설정은 Deployment를 의미한다.
kind: Deployment
Kubernetes는 apiVersion과 kind를 함께 사용하여 어떤 종류의 객체를 생성하거나 수정할 것인지 판단한다.
flowchart TD
A["Kubernetes Manifest"] --> B["apiVersion"]
A --> C["kind"]
B --> D["API 버전 결정"]
C --> E["리소스 종류 결정"]
D --> F["Kubernetes API Server"]
E --> F
F --> G["해당 리소스의 API 규칙에 따라 처리"]
따라서 같은 YAML 문법을 사용하더라도 kind에 따라 의미가 완전히 달라질 수 있다.
metadata: 리소스의 메타데이터
metadata에는 리소스의 이름, Namespace, Label, Annotation 등 리소스를 식별하고 관리하는 데 필요한 정보를 작성한다.
metadata:
name: nginx
namespace: default
labels:
app: nginx
environment: development
각 필드의 의미는 다음과 같다.
| 필드 | 설명 |
|---|---|
name | 리소스의 이름 |
namespace | 리소스가 속하는 Namespace |
labels | 리소스를 분류하고 선택하기 위한 정보 |
annotations | 추가적인 메타데이터 |
예를 들어 다음 설정을 살펴보자.
metadata:
name: nginx
이 설정은 nginx라는 이름으로 리소스를 생성하겠다는 의미이다.
Kubernetes에서는 일반적으로 같은 Namespace 안에서 동일한 종류의 리소스가 같은 이름을 가질 수 없다.
따라서 동일한 Namespace에 nginx라는 Pod가 이미 존재한다면 같은 이름으로 또 다른 Pod를 생성할 수 없다.
이러한 특성은 이후 명령형과 선언형 방식의 차이를 이해할 때 중요하게 작용한다.
spec: 리소스의 원하는 상태
spec에는 Kubernetes가 유지하거나 구현해야 하는 원하는 상태를 정의한다.
예를 들어 Pod에서 사용할 컨테이너 이미지, DNS 정책, 재시작 정책 등을 작성할 수 있다.
spec:
containers:
- name: nginx
image: nginx:1.27
dnsPolicy: ClusterFirst
restartPolicy: Always
이 설정의 의미는 다음과 같다.
containers
Pod 내부에서 실행할 컨테이너를 정의한다.
dnsPolicy
Pod가 사용할 DNS 정책을 정의한다.
restartPolicy
컨테이너가 종료되었을 때 재시작할지 결정하는 정책이다.
Kubernetes는 이러한 설정을 기반으로 Pod의 실행 환경을 구성한다.
여기서 spec과 함께 알아두면 좋은 개념이 status이다.
spec은 원하는 상태를 나타내고, status는 현재 관찰된 실제 상태를 나타낸다.
flowchart TD
A["Kubernetes Resource"] --> B["spec"]
A --> C["status"]
B --> D["원하는 상태"]
C --> E["현재 관찰된 상태"]
D --> F["Kubernetes Controller"]
E --> F
F --> G["상태 차이를 확인하고 필요한 작업 수행"]
예를 들어 Deployment의 spec.replicas가 3이라면 Pod 3개를 유지하려는 의도를 의미한다.
반면 status.readyReplicas가 2라면 현재 Ready 상태인 Pod가 2개라는 의미이다.
spec:
replicas: 3
status:
readyReplicas: 2
이 경우 Kubernetes는 Deployment의 원하는 상태와 현재 상태 사이에 차이가 있음을 확인할 수 있다.
다만 status는 일반적으로 Controller 등 Kubernetes의 구성 요소가 갱신하므로 사용자가 작성하는 기본 Manifest에는 포함하지 않는다.
Pod YAML 전체 예제
이제 실제로 Nginx Pod를 생성할 수 있는 YAML 파일을 작성해보자.
파일 이름은 nginx-pod.yaml로 지정한다.
apiVersion: v1
kind: Pod
metadata:
name: nginx
namespace: default
labels:
app: nginx
environment: development
spec:
containers:
- name: nginx
image: nginx:1.27
imagePullPolicy: IfNotPresent
ports:
- containerPort: 80
name: http
resources:
requests:
cpu: "100m"
memory: "64Mi"
limits:
cpu: "500m"
memory: "128Mi"
dnsPolicy: ClusterFirst
restartPolicy: Always
이 설정은 다음과 같은 Pod를 생성한다.
Pod 이름: nginx
Namespace: default
Container
├── 이름: nginx
├── 이미지: nginx:1.27
├── Container Port: 80
├── CPU requests: 100m
├── Memory requests: 64Mi
├── CPU limits: 500m
└── Memory limits: 128Mi
DNS Policy: ClusterFirst
Restart Policy: Always
주요 설정을 조금 더 자세히 살펴보자.
containers
containers:
- name: nginx
image: nginx:1.27
Pod 내부에서 실행할 컨테이너의 이름과 이미지를 지정한다.
containers는 배열이므로 하나의 Pod 안에 여러 컨테이너를 정의할 수도 있다.
imagePullPolicy
imagePullPolicy: IfNotPresent
Node에 필요한 이미지가 이미 존재한다면 이를 사용하고, 이미지가 없다면 Container Registry에서 다운로드하는 정책이다.
대표적인 이미지 Pull 정책은 다음과 같다.
| 정책 | 설명 |
|---|---|
Always | 컨테이너를 시작할 때 이미지 참조를 확인 |
IfNotPresent | 이미지가 로컬에 없을 때 다운로드 |
Never | 이미지를 다운로드하지 않고 로컬 이미지만 사용 |
Always라고 해서 반드시 이미지의 모든 레이어를 매번 새로 다운로드하는 것은 아니다. 이미지 캐시를 재사용할 수 있다.
ports
ports:
- containerPort: 80
name: http
컨테이너가 사용하는 포트를 선언한다.
다만 containerPort를 80으로 작성한다고 해서 애플리케이션이 자동으로 80번 포트에서 실행되는 것은 아니다.
실제 애플리케이션이 해당 포트에서 요청을 수신하도록 설정되어 있어야 한다.
Nginx의 기본 HTTP 포트는 일반적으로 80번이다.
dnsPolicy
dnsPolicy: ClusterFirst
ClusterFirst는 Kubernetes 클러스터 DNS를 우선적으로 사용하는 정책이다.
이를 통해 Pod는 클러스터 내부 Service 이름을 DNS로 조회할 수 있다.
예를 들어 같은 Namespace의 Service에 다음과 같이 접근할 수 있다.
http://payment-service:8080
restartPolicy
restartPolicy: Always
Pod 내부의 일반 애플리케이션 컨테이너가 종료되면 재시작하도록 설정한다.
대표적인 정책은 다음과 같다.
| 정책 | 설명 |
|---|---|
Always | 종료 상태와 관계없이 재시작 |
OnFailure | 오류로 종료되었을 때 재시작 |
Never | 자동 재시작하지 않음 |
여기서 주의할 점은 restartPolicy가 Pod 객체 자체를 다시 생성하는 기능은 아니라는 것이다.
이 정책은 기본적으로 kubelet이 Pod 내부 컨테이너를 재시작하는 방식에 적용된다.
Pod 객체가 삭제되었을 때 새로운 Pod를 다시 생성하려면 Deployment나 ReplicaSet과 같은 상위 Controller가 필요하다.
선언형 관리란?
선언형 관리(Declarative Management)는 시스템이 도달해야 하는 원하는 상태를 정의하는 방식이다.
사용자는 Kubernetes에 무엇을 유지해야 하는지 선언하고, Kubernetes는 해당 설정을 해석하여 필요한 작업을 수행한다.
예를 들어 다음 YAML을 살펴보자.
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
이 파일에는 다음과 같은 의도가 담겨 있다.
nginx라는 이름의 Pod가 존재하고, 그 안에서 Nginx 컨테이너가 실행되도록 구성한다.
선언형 관리에서는 이를 구현하기 위해 어떤 API 요청을 보내야 하는지 사용자가 일일이 명령하지 않는다.
대신 Kubernetes에 원하는 상태를 전달한다.
flowchart TD
A["사용자가 원하는 상태 정의"] --> B["YAML Manifest"]
B --> C["kubectl apply"]
C --> D["Kubernetes API Server"]
D --> E{"리소스가 존재하는가?"}
E -->|"존재하지 않음"| F["리소스 생성"]
E -->|"이미 존재함"| G{"설정에 차이가 있는가?"}
G -->|"차이 없음"| H["설정 변경 없음"]
G -->|"차이 있음"| I["필요한 필드 업데이트"]
이 방식의 핵심은 기존 리소스가 존재하는지와 어떤 설정이 달라졌는지를 고려하여 필요한 작업을 수행한다는 것이다.
따라서 같은 Manifest를 반복해서 적용하더라도 설정이 동일하다면 불필요한 변경을 발생시키지 않을 수 있다.
선언형 방식으로 Pod 생성하기
앞서 작성한 nginx-pod.yaml을 사용해 Pod를 생성해보자.
1. YAML 파일 작성
다음 명령어로 파일을 생성한다.
vi nginx-pod.yaml
파일에는 앞서 작성한 Pod Manifest를 저장한다.
2. Pod 생성
kubectl apply -f nginx-pod.yaml
여기서 각 요소의 의미는 다음과 같다.
| 항목 | 의미 |
|---|---|
kubectl | Kubernetes API와 통신하는 CLI |
apply | 원하는 설정을 리소스에 적용 |
-f | 파일을 입력으로 사용 |
nginx-pod.yaml | 적용할 Manifest 파일 |
리소스가 존재하지 않는다면 Kubernetes에 새로운 Pod가 생성된다.
예상 출력:
pod/nginx created
여기서 created는 새로운 리소스가 생성되었다는 의미이다.
3. Pod 상태 확인
kubectl get pods
예상 출력:
NAME READY STATUS RESTARTS AGE
nginx 1/1 Running 0 15s
Running 상태는 Pod가 Node에 배치되어 컨테이너가 실행되고 있음을 나타낸다.
다만 명령어를 실행한 직후에는 이미지 다운로드나 컨테이너 생성이 진행 중이어서 Pending 또는 ContainerCreating 상태가 나타날 수 있다.
Pod가 준비될 때까지 기다리려면 다음 명령어를 사용할 수 있다.
kubectl wait \
--for=condition=Ready \
pod/nginx \
--timeout=120s
정상적으로 Ready 상태가 되면 다음과 같은 메시지가 출력된다.
pod/nginx condition met
4. 생성된 리소스 확인
현재 Kubernetes에 저장된 Pod 설정을 확인할 수 있다.
kubectl get pod nginx -o yaml
이 명령어는 API Server에 저장된 Pod 객체를 YAML 형식으로 출력한다.
출력에는 사용자가 작성한 설정뿐 아니라 Kubernetes가 자동으로 추가한 정보도 포함될 수 있다.
대표적으로 다음과 같은 항목이 있다.
- Pod UID
- 생성 시간
- Node 정보
- Container 상태
- Pod IP
- 실행 상태
이러한 정보는 Kubernetes가 실제 리소스를 관리하면서 생성하거나 갱신하는 값이다.
선언형 방식으로 Pod 삭제하기
생성한 Pod를 삭제하려면 다음 명령어를 사용할 수 있다.
kubectl delete -f nginx-pod.yaml
이 명령어는 YAML 파일에 정의된 리소스를 식별하여 Kubernetes에서 삭제한다.
예상 출력:
pod "nginx" deleted
Pod 상태를 확인한다.
kubectl get pods
Pod가 삭제되었다면 더 이상 목록에 나타나지 않는다.
여기서 중요한 점이 있다.
YAML 파일을 사용했다고 해서 모든 명령어가 선언형 명령이 되는 것은 아니다.
kubectl delete -f는 파일을 이용해 삭제 대상을 지정하지만, 실제 수행하는 작업은 명시적인 삭제 명령이다.
즉 삭제 자체는 명령형 작업에 해당한다.
또한 YAML 파일을 삭제하거나 해당 파일을 디렉터리에서 제거한다고 해서 Kubernetes의 리소스가 자동으로 삭제되는 것은 아니다.
kubectl apply는 일반적으로 명령이 실행되는 시점에 파일의 내용을 적용한다.
이 차이는 이후 선언형 관리와 지속적인 상태 동기화를 구분할 때 중요하다.
명령형 관리란?
명령형 관리(Imperative Management)는 Kubernetes에 수행할 작업을 직접 명령하는 방식이다.
예를 들어 다음과 같은 작업이 있다.
- Pod 생성
- Deployment 수량 변경
- 특정 리소스 삭제
- 컨테이너 이미지 변경
명령형 방식에서는 원하는 상태를 파일로 선언하는 대신, 실행할 작업을 명령어의 형태로 전달한다.
flowchart TD
A["사용자"] --> B["kubectl 명령어"]
B --> C["Kubernetes API Server"]
C --> D["명령에 해당하는 작업 수행"]
D --> E["리소스 생성"]
D --> F["리소스 수정"]
D --> G["리소스 삭제"]
대표적인 명령형 명령어는 다음과 같다.
| 명령어 | 역할 |
|---|---|
kubectl run | 이미지로 Pod 생성 |
kubectl create | 리소스 생성 |
kubectl delete | 리소스 삭제 |
kubectl scale | replicas 변경 |
kubectl set image | 컨테이너 이미지 변경 |
kubectl edit | 리소스 직접 편집 |
명령형 방식은 특정 작업을 빠르게 수행해야 할 때 유용하다.
다만 명령어만으로 관리하면 어떤 설정이 최종적으로 적용되어야 하는지 추적하기 어려워질 수 있다.
명령형 방식으로 Pod 생성하기
이번에는 YAML 파일을 사용하지 않고 명령어만으로 Pod를 생성해보자.
1. kubectl run 실행
kubectl run nginx-imperative \
--image=nginx:1.27 \
--port=80
각 옵션의 의미는 다음과 같다.
| 옵션 | 설명 |
|---|---|
nginx-imperative | 생성할 Pod 이름 |
--image=nginx:1.27 | 사용할 컨테이너 이미지 |
--port=80 | 컨테이너 포트 선언 |
정상적으로 실행되면 다음과 같은 메시지가 출력된다.
pod/nginx-imperative created
여기서 --port=80은 컨테이너의 포트 정보를 선언하는 옵션이다.
이 옵션만으로 Service가 생성되거나 외부에서 접근할 수 있는 네트워크 경로가 만들어지는 것은 아니다.
2. Pod 상태 확인
kubectl get pods
예상 출력:
NAME READY STATUS RESTARTS AGE
nginx-imperative 1/1 Running 0 10s
YAML 파일을 사용하지 않았지만 Kubernetes에 Pod가 정상적으로 생성되었다.
이처럼 명령형 방식은 간단한 리소스를 빠르게 생성할 수 있다.
동일한 명령형 명령을 다시 실행하면 어떻게 될까?
앞에서 실행한 명령어를 다시 실행해보자.
kubectl run nginx-imperative \
--image=nginx:1.27 \
--port=80
이번에는 다음과 같은 오류가 발생한다.
Error from server (AlreadyExists): pods "nginx-imperative" already exists
이 오류가 발생하는 이유는 무엇일까?
kubectl run은 지정한 이름의 새로운 Pod를 생성하는 명령이기 때문이다.
첫 번째 실행에서 이미 nginx-imperative라는 Pod가 생성되었다.
동일한 이름으로 새로운 Pod를 생성하려고 하면 Kubernetes API Server는 해당 이름의 Pod가 이미 존재한다는 사실을 확인한다.
따라서 새로운 Pod를 생성하지 않고 오류를 반환한다.
flowchart TD
A["kubectl run nginx-imperative"] --> B["Kubernetes API Server"]
B --> C{"동일한 이름의 Pod 존재?"}
C -->|"아니오"| D["Pod 생성"]
C -->|"예"| E["AlreadyExists 오류"]
이것이 명령형 생성 명령의 대표적인 특징이다.
사용자가 새로운 리소스를 생성하라고 명령했기 때문에, 이미 해당 리소스가 존재하면 생성 작업이 실패할 수 있다.
다만 모든 명령형 명령이 반복 실행할 때 반드시 오류를 발생시키는 것은 아니다.
명령형 방식에도 작업 종류에 따라 반복 실행 가능한 명령이 있다.
여기서는 kubectl run과 같은 명시적인 생성 명령을 기준으로 비교하고 있다.
선언형 방식으로 동일한 설정을 다시 적용하면 어떻게 될까?
이번에는 같은 상황을 선언형 방식으로 확인해보자.
먼저 앞에서 사용한 nginx-pod.yaml을 다시 적용한다.
kubectl apply -f nginx-pod.yaml
Pod가 존재하지 않는다면 새로운 Pod가 생성된다.
pod/nginx created
이제 동일한 명령어를 다시 실행한다.
kubectl apply -f nginx-pod.yaml
예상 출력:
pod/nginx unchanged
이번에는 AlreadyExists 오류가 발생하지 않는다.
대신 unchanged라는 결과가 나타난다.
그 이유는 kubectl apply가 단순한 생성 명령이 아니기 때문이다.
kubectl apply는 현재 Kubernetes에 존재하는 객체와 적용하려는 설정을 비교하여 필요한 변경을 반영한다.
이미 같은 설정이 적용되어 있다면 추가로 수정할 필요가 없다.
따라서 변경하지 않았다는 결과를 반환한다.
flowchart TD
A["kubectl apply -f nginx-pod.yaml"] --> B["Kubernetes API Server"]
B --> C{"Pod가 존재하는가?"}
C -->|"아니오"| D["Pod 생성"]
C -->|"예"| E{"설정에 변경 사항이 있는가?"}
E -->|"아니오"| F["unchanged"]
E -->|"예"| G["변경 가능한 필드 업데이트"]
이러한 특징은 선언형 관리의 중요한 장점이다.
동일한 설정을 반복해서 적용해도 불필요한 리소스 변경을 최소화할 수 있다.
created, configured, unchanged의 차이
kubectl apply를 사용하다 보면 다음 세 가지 결과를 자주 확인하게 된다.
created
configured
unchanged
각각의 의미는 다음과 같다.
| 결과 | 의미 |
|---|---|
created | 새로운 리소스를 생성함 |
configured | 기존 리소스의 설정을 변경함 |
unchanged | 적용할 설정에 변경 사항이 없음 |
예를 들어 다음과 같은 Pod Manifest가 있다고 가정하자.
apiVersion: v1
kind: Pod
metadata:
name: nginx
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
첫 번째 적용
kubectl apply -f nginx-pod.yaml
결과:
pod/nginx created
두 번째 적용
kubectl apply -f nginx-pod.yaml
결과:
pod/nginx unchanged
설정 변경 후 적용
이제 metadata.labels에 새로운 Label을 추가해보자.
metadata:
name: nginx
labels:
app: nginx
team: backend
다시 적용한다.
kubectl apply -f nginx-pod.yaml
결과:
pod/nginx configured
기존 Pod가 존재하지만 Label이 변경되었으므로 필요한 설정이 업데이트된 것이다.
이 과정을 정리하면 다음과 같다.
flowchart TD
A["Manifest 작성"] --> B["첫 번째 apply"]
B --> C["created"]
C --> D["동일한 Manifest 재적용"]
D --> E["unchanged"]
E --> F["Manifest의 Label 변경"]
F --> G["다시 apply"]
G --> H["configured"]
이처럼 선언형 방식은 생성과 수정을 별도의 명령으로 구분하지 않고 원하는 상태를 적용하는 방식으로 관리할 수 있다.
단, apply로 모든 필드를 자유롭게 변경할 수 있는 것은 아니다.
Kubernetes에서는 리소스 종류에 따라 변경할 수 없는 필드가 존재하며, 이 경우에는 apply도 오류를 반환할 수 있다.
선언형 방식의 핵심: 멱등성
지금까지 살펴본 선언형 관리의 특징은 멱등성(Idempotency)과 밀접하게 관련되어 있다.
멱등성이란 같은 작업을 여러 번 수행하더라도 최종 결과가 한 번 수행한 결과와 동일하게 유지되는 성질이다.
예를 들어 다음과 같은 작업을 생각해보자.
원하는 상태: nginx Pod가 존재해야 한다.
처음 적용했을 때는 Pod가 생성된다.
첫 번째 apply
→ Pod 생성
두 번째 적용했을 때는 이미 원하는 상태가 충족되어 있으므로 설정 변경이 필요하지 않다.
두 번째 apply
→ 변경 없음
세 번째 적용해도 마찬가지이다.
세 번째 apply
→ 변경 없음
flowchart TD
A["원하는 상태: nginx Pod 존재"] --> B["apply 1회"]
B --> C["Pod 생성"]
C --> D["apply 2회"]
D --> E["동일한 상태 유지"]
E --> F["apply 3회"]
F --> G["동일한 상태 유지"]
이러한 성질은 자동화 시스템에서 중요하다.
예를 들어 CI/CD 파이프라인이 네트워크 오류나 일시적인 문제로 인해 같은 배포 작업을 다시 수행할 수 있다.
이때 선언형 관리 방식에서는 기존에 같은 설정이 적용되어 있다면 불필요한 변경을 최소화할 수 있다.
반면 단순 생성 명령을 반복 실행하면 이미 존재하는 리소스를 다시 생성하려다가 오류가 발생할 수 있다.
단, 멱등성은 최종 상태에 관한 개념이다.
kubectl apply를 반복 실행할 때 Kubernetes API 요청 자체가 생략되는 것은 아니며, 설정 충돌이나 권한 오류 등으로 실패할 수도 있다.
명령형과 선언형 관리 방식 비교
두 방식을 정리하면 다음과 같다.
| 비교 항목 | 명령형 방식 | 선언형 방식 |
|---|---|---|
| 핵심 관점 | 무엇을 실행할 것인가 | 어떤 상태를 유지할 것인가 |
| 대표 명령어 | kubectl run, kubectl create | kubectl apply |
| 설정 관리 | 명령어와 옵션 중심 | Manifest 중심 |
| 리소스 생성 | 명시적으로 생성 요청 | 존재하지 않으면 생성 |
| 리소스 수정 | 별도의 수정 명령 사용 가능 | 차이를 계산해 필요한 변경 반영 |
| 반복 실행 | 명령 종류에 따라 오류 가능 | 동일 설정이면 변경 최소화 |
| 변경 이력 관리 | 명령 실행 기록에 의존할 수 있음 | Git으로 Manifest 관리 가능 |
| 자동화 | 단순 작업에 편리 | 반복 배포와 구성 관리에 유리 |
| 대표 사용 상황 | 테스트, 일회성 작업 | 운영 환경, CI/CD, GitOps |
각 방식의 특징을 조금 더 구체적으로 살펴보자.
명령형 방식이 유리한 경우
명령형 방식은 특정 작업을 빠르게 수행해야 할 때 유용하다.
예를 들어 테스트용 Pod를 하나 생성하고 싶다면 다음 명령어를 사용할 수 있다.
kubectl run test-nginx \
--image=nginx:1.27
또는 Deployment의 replicas를 즉시 변경할 수도 있다.
kubectl scale deployment/my-app --replicas=5
이러한 방식은 간단하고 빠르다.
반면 장기간 운영할 애플리케이션을 여러 명이 관리해야 한다면 변경 이력을 추적하거나 동일한 환경을 재현하기 어려워질 수 있다.
선언형 방식이 유리한 경우
선언형 방식에서는 원하는 구성을 YAML 파일로 관리할 수 있다.
예를 들어 다음과 같은 Deployment를 정의한다고 가정하자.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:1.27
ports:
- containerPort: 80
이 파일을 Git에 저장하면 다음과 같은 이점을 얻을 수 있다.
- 애플리케이션의 원하는 구성을 코드처럼 관리할 수 있다.
- 설정 변경 이력을 확인할 수 있다.
- 코드 리뷰를 통해 변경 내용을 검토할 수 있다.
- 동일한 설정을 다른 환경에 적용할 수 있다.
- 자동화된 배포 파이프라인과 연결할 수 있다.
이 때문에 운영 환경에서는 일반적으로 선언형 관리 방식이 널리 활용된다.
YAML을 사용하면 무조건 선언형 방식일까?
여기서 혼동하기 쉬운 개념이 있다.
YAML 파일을 사용하면 선언형 방식이고, 명령어를 사용하면 명령형 방식이라고 생각할 수 있다.
하지만 정확히는 그렇지 않다.
YAML은 데이터 표현 형식이고, 명령형과 선언형은 리소스를 관리하는 방식이다.
예를 들어 다음 명령어를 살펴보자.
kubectl create -f nginx-pod.yaml
이 명령어는 YAML 파일을 사용한다.
하지만 create는 새로운 리소스를 생성하라는 명시적인 명령이다.
따라서 명령형 관리 방식에 해당한다.
반면 다음 명령어는 선언형 관리 방식에 해당한다.
kubectl apply -f nginx-pod.yaml
두 명령어 모두 같은 YAML 파일을 사용하지만 동작 방식이 다르다.
이를 표로 비교하면 다음과 같다.
| 명령어 | YAML 사용 | 관리 방식 |
|---|---|---|
kubectl run nginx --image=nginx | 사용하지 않음 | 명령형 |
kubectl create -f pod.yaml | 사용 | 명령형 |
kubectl delete -f pod.yaml | 사용 | 명령형 삭제 |
kubectl apply -f pod.yaml | 사용 | 선언형 |
kubectl scale deployment/my-app --replicas=3 | 사용하지 않음 | 명령형 |
따라서 YAML 사용 여부가 아니라 Kubernetes에 어떤 방식으로 변경을 요청하는지가 핵심적인 차이이다.
kubectl create와 kubectl apply의 차이
두 명령어 모두 YAML 파일을 사용할 수 있기 때문에 자주 혼동된다.
kubectl create
kubectl create -f nginx-pod.yaml
create는 새로운 Kubernetes 리소스를 생성한다.
이미 같은 이름의 리소스가 존재한다면 다음과 같은 오류가 발생할 수 있다.
Error from server (AlreadyExists): pods "nginx" already exists
kubectl apply
kubectl apply -f nginx-pod.yaml
apply는 Manifest에 정의된 원하는 상태를 적용한다.
리소스가 없다면 생성하고, 이미 존재한다면 필요한 변경을 반영한다.
설정이 동일하다면 다음과 같은 결과가 나타난다.
pod/nginx unchanged
따라서 create와 apply는 다음과 같이 구분할 수 있다.
flowchart TD
A["Kubernetes 리소스 관리"] --> B["kubectl create"]
A --> C["kubectl apply"]
B --> D["새로운 리소스 생성 요청"]
D --> E{"이미 존재하는가?"}
E -->|"예"| F["AlreadyExists 오류"]
E -->|"아니오"| G["created"]
C --> H["원하는 상태 적용"]
H --> I{"이미 존재하는가?"}
I -->|"아니오"| J["created"]
I -->|"예"| K["설정 차이 확인"]
K --> L["configured 또는 unchanged"]
이러한 차이를 이해하면 동일한 Kubernetes 리소스를 반복적으로 관리하는 자동화 작업을 더 안정적으로 구성할 수 있다.
선언형 관리와 Reconciliation의 관계
Kubernetes의 핵심 특징 중 하나는 Reconciliation이다.
Reconciliation은 원하는 상태와 실제 상태를 비교하고, 둘 사이의 차이를 줄이기 위해 필요한 작업을 수행하는 과정이다.
예를 들어 다음과 같은 Deployment를 생성했다고 가정하자.
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
image: nginx:1.27
이 설정의 핵심은 다음과 같다.
replicas: 3
Kubernetes는 Nginx Pod 3개가 유지되도록 Deployment와 ReplicaSet을 관리한다.
flowchart TD
A["Deployment"] --> B["원하는 상태: replicas 3"]
B --> C["ReplicaSet"]
C --> D["Pod A"]
C --> E["Pod B"]
C --> F["Pod C"]
이 상태에서 Pod 하나가 삭제되었다고 가정하자.
원하는 Pod 수량: 3
실제 Pod 수량: 2
ReplicaSet Controller는 부족한 Pod를 다시 생성한다.
flowchart TD
A["Deployment replicas: 3"] --> B["ReplicaSet Controller"]
B --> C["현재 Pod 수량 확인"]
C --> D{"현재 Pod 수량이 3인가?"}
D -->|"예"| E["상태 유지"]
D -->|"아니오"| F["부족한 Pod 생성"]
F --> C
이것이 Kubernetes의 Reconciliation 동작이다.
다만 여기서는 중요한 차이를 이해해야 한다.
kubectl apply가 지속적으로 상태를 감시하는 것은 아니다.
kubectl apply는 실행하는 시점에 원하는 설정을 API Server에 적용한다.
이후 Pod 수량을 지속적으로 감시하고 조정하는 것은 Deployment Controller나 ReplicaSet Controller와 같은 Kubernetes의 Controller이다.
즉 다음 두 가지는 서로 다른 역할이다.
kubectl apply
Manifest에 정의된 원하는 상태를 Kubernetes API에 전달한다.
Kubernetes Controller
자신이 관리하는 리소스의 원하는 상태와 실제 상태를 지속적으로 비교하고 필요한 조치를 수행한다.
Pod를 직접 생성하는 경우와 Deployment를 사용하는 경우
앞에서 nginx-pod.yaml을 이용해 Pod를 직접 생성했다.
그렇다면 이 Pod를 삭제하면 어떻게 될까?
kubectl delete pod nginx
Pod를 직접 생성한 경우에는 일반적으로 해당 Pod를 다시 생성해 주는 상위 Controller가 존재하지 않는다.
따라서 Pod가 삭제되면 그대로 사라진다.
반면 Deployment가 생성한 Pod는 다르다.
Deployment가 원하는 수량을 유지하도록 관리하기 때문이다.
flowchart TD
A["Pod 생성 방식"] --> B["직접 생성한 Pod"]
A --> C["Deployment가 관리하는 Pod"]
B --> D["Pod 삭제"]
D --> E["Pod가 사라짐"]
C --> F["Pod 삭제"]
F --> G["ReplicaSet이 수량 부족 감지"]
G --> H["새로운 Pod 생성"]
이러한 차이 때문에 실제 운영 환경에서는 일반적인 API 서버를 Pod 객체 하나로 직접 실행하기보다 Deployment를 사용하는 경우가 많다.
또한 Pod를 직접 생성하는 것과 Deployment를 선언형으로 관리하는 것은 서로 다른 개념이다.
Pod도 YAML을 이용해 선언형으로 생성할 수 있다.
하지만 Pod 객체 자체를 선언형으로 생성했다고 해서 삭제된 Pod를 자동으로 다시 생성하는 Controller까지 생기는 것은 아니다.
이는 선언형 관리와 Self-Healing이 서로 연결되어 있지만 동일한 개념은 아니라는 점을 보여준다.
kubectl apply는 YAML 변경 사항을 자동으로 감지할까?
선언형 관리에서 자주 혼동하는 부분이 하나 더 있다.
YAML 파일을 작성하고 kubectl apply를 실행한 다음, 로컬 YAML 파일의 내용을 수정하면 Kubernetes가 이를 자동으로 감지할까?
그렇지 않다.
예를 들어 다음 Deployment를 적용했다고 가정하자.
spec:
replicas: 3
kubectl apply -f deployment.yaml
이후 로컬 파일의 설정을 다음과 같이 변경한다.
spec:
replicas: 5
하지만 파일만 수정하고 kubectl apply를 다시 실행하지 않았다면 Kubernetes의 Deployment 설정은 자동으로 변경되지 않는다.
변경 사항을 반영하려면 다시 적용해야 한다.
kubectl apply -f deployment.yaml
flowchart TD
A["로컬 YAML 작성"] --> B["kubectl apply"]
B --> C["Kubernetes에 원하는 상태 반영"]
C --> D["로컬 YAML 수정"]
D --> E{"다시 apply 실행했는가?"}
E -->|"아니오"| F["클러스터 설정은 변경되지 않음"]
E -->|"예"| G["변경된 설정 반영"]
즉 kubectl apply는 실행하는 시점에 선언된 상태를 적용하는 도구이다.
로컬 파일 자체를 지속적으로 감시하는 기능은 아니다.
지속적인 선언형 관리를 위한 GitOps
앞서 살펴본 것처럼 kubectl apply는 사용자가 실행해야 변경 사항이 반영된다.
그렇다면 Git 저장소에 정의된 YAML과 Kubernetes의 실제 설정을 지속적으로 비교하여 자동으로 동기화하고 싶다면 어떻게 해야 할까?
이러한 목적에는 GitOps 방식이 활용된다.
대표적인 도구로 Argo CD와 Flux가 있다.
GitOps 환경에서는 Git 저장소에 Kubernetes Manifest를 보관하고, 별도의 Controller가 저장소의 설정과 클러스터 상태를 비교한다.
flowchart TD
A["Developer"] --> B["Git Repository"]
B --> C["GitOps Controller"]
C --> D["Kubernetes API Server"]
D --> E["Deployment"]
E --> F["ReplicaSet"]
F --> G["Pod"]
C --> H["설정 차이 감지"]
H --> C
예를 들어 Git 저장소에 다음 설정이 있다고 가정하자.
spec:
replicas: 3
클러스터에서 누군가 직접 replicas를 5로 변경했다고 가정해보자.
kubectl scale deployment/nginx-deployment --replicas=5
일반적으로 이 명령만 실행했다면 Deployment의 replicas는 5로 변경된다.
하지만 GitOps Controller가 해당 필드를 Git에 선언된 상태로 동기화하도록 구성되어 있다면, 다시 3으로 되돌릴 수 있다.
Git의 원하는 상태: 3
클러스터의 실제 설정: 5
GitOps 동기화
→ replicas를 3으로 복구
단, 실제 동작은 GitOps 도구의 자동 동기화 설정과 관리 대상 필드, HPA 연동 방식 등에 따라 달라질 수 있다.
이러한 방식은 선언형 관리의 장점을 더욱 확장한다.
특히 여러 개발자가 동일한 Kubernetes 클러스터를 관리하는 환경에서 설정 변경 이력을 추적하고 운영 환경의 구성 일관성을 유지하는 데 도움이 된다.
실무에서 선언형 관리가 중요한 이유
Kubernetes의 선언형 관리가 중요한 이유는 단순히 YAML 파일을 작성하기 편리하기 때문이 아니다.
핵심은 운영 환경의 구성을 명시적으로 정의하고 반복적으로 재현할 수 있다는 점이다.
1. 동일한 설정을 반복 적용할 수 있다
CI/CD에서는 배포 과정이 실패하거나 재시도되는 상황이 발생할 수 있다.
이때 선언형 방식은 동일한 Manifest를 다시 적용해도 불필요한 리소스 변경을 줄일 수 있다.
예를 들어 다음과 같이 실행한다.
kubectl apply -f deployment.yaml
이미 동일한 설정이 적용되어 있다면 변경 없이 종료될 수 있다.
이를 통해 자동화 작업을 비교적 안정적으로 구성할 수 있다.
2. 환경 구성을 Git으로 관리할 수 있다
YAML 파일을 Git 저장소에 보관하면 설정 변경 이력을 관리할 수 있다.
예를 들어 다음과 같은 구조로 관리할 수 있다.
kubernetes/
├── development/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── configmap.yaml
│
└── production/
├── deployment.yaml
├── service.yaml
└── configmap.yaml
환경별 설정을 분리하면 개발 환경과 운영 환경에서 어떤 차이가 있는지 확인하기 쉬워진다.
다만 실제 운영에서는 환경별 설정 중복을 줄이기 위해 Kustomize나 Helm을 활용할 수도 있다.
3. 장애 복구에 활용할 수 있다
운영 환경에서 특정 리소스의 설정이 잘못 변경되었다면 Git에 저장된 정상적인 Manifest를 다시 적용하는 방식으로 복구할 수 있다.
kubectl apply -f deployment.yaml
하지만 모든 문제를 단순히 다시 적용하는 것만으로 해결할 수 있는 것은 아니다.
예를 들어 Deployment의 변경 불가능한 필드를 수정하거나, 외부 데이터베이스 상태가 변경된 경우에는 별도의 복구 절차가 필요하다.
따라서 선언형 관리의 장점을 활용하면서도 각 리소스의 동작 특성을 이해해야 한다.
4. 코드 리뷰를 통해 변경 사항을 검토할 수 있다
운영 환경의 Deployment에 다음과 같은 변경이 발생했다고 가정하자.
spec:
replicas: 3
이를 다음과 같이 변경한다.
spec:
replicas: 10
명령형 방식에서는 변경 명령을 즉시 실행할 수 있다.
반면 Git에 Manifest를 보관하는 방식에서는 Pull Request를 통해 변경 이유와 영향을 검토할 수 있다.
특히 replicas, requests, limits, 환경 변수, Volume 등 운영에 영향을 주는 설정은 변경 전 검토 과정이 중요하다.
실무에서 주의해야 할 사항
kubectl apply가 항상 성공하는 것은 아니다
apply는 이미 존재하는 리소스를 인식하고 필요한 변경을 수행할 수 있다.
하지만 다음과 같은 상황에서는 오류가 발생할 수 있다.
- YAML 문법이 잘못된 경우
- Kubernetes API가 지원하지 않는 필드를 사용한 경우
- 리소스 생성 또는 수정 권한이 부족한 경우
- 변경할 수 없는 필드를 수정하려는 경우
- Admission 정책을 위반한 경우
- 서버 측 필드 소유권 충돌이 발생한 경우
특히 Pod는 생성 후 일부 필드를 자유롭게 수정할 수 없다.
따라서 Pod에 대한 모든 설정이 kubectl apply로 즉시 변경된다고 생각해서는 안 된다.
일반적인 애플리케이션에서는 Deployment를 사용해 새로운 Pod Template을 선언하고 Rolling Update를 수행하는 방식이 적절하다.
선언형 방식에서도 리소스 삭제는 별도로 관리해야 한다
Manifest 파일에서 리소스 정의를 삭제했다고 해서 클러스터에 존재하는 해당 리소스가 자동으로 제거되지는 않는다.
일반적인 kubectl apply -f는 파일에 없는 기존 리소스를 일괄적으로 삭제하는 명령이 아니기 때문이다.
리소스를 삭제하려면 다음과 같이 명시적으로 요청할 수 있다.
kubectl delete -f nginx-pod.yaml
여러 리소스의 추가·변경·삭제를 지속적으로 동기화하려면 GitOps 도구의 Prune 기능과 같은 별도 관리 방식도 고려할 수 있다.
다만 자동 삭제 기능은 의도하지 않은 리소스까지 제거할 수 있으므로 적용 범위와 권한을 신중하게 관리해야 한다.
명령형과 선언형 변경을 혼합하면 설정 충돌이 발생할 수 있다
예를 들어 선언형으로 관리하는 Deployment의 replicas가 다음과 같다고 가정하자.
replicas: 3
운영자가 다음 명령어로 replicas를 변경한다.
kubectl scale deployment/my-app --replicas=5
이후 관리 중인 YAML 파일을 다시 적용하는 경우, apply 방식과 필드 소유권, 기존 적용 이력에 따라 설정이 변경되거나 유지될 수 있다.
이처럼 여러 도구나 관리자가 같은 필드를 수정하면 실제 적용되는 값이 예상과 달라질 수 있다.
따라서 운영 환경에서는 특정 필드를 누가 관리하는지 명확하게 정의하는 것이 중요하다.
예를 들어 HPA가 replicas를 관리하는 환경에서는 Deployment YAML에 지정된 replicas와 HPA 설정 사이의 관계도 고려해야 한다.
Kubernetes YAML을 작성할 때 유용한 명령어
Kubernetes Manifest를 작성하고 적용할 때는 다음 명령어들을 함께 알아두면 좋다.
적용 전 변경 사항 확인
kubectl diff -f nginx-pod.yaml
현재 클러스터에 저장된 설정과 Manifest 사이의 차이를 확인한다.
설정에 변경 사항이 있다면 해당 차이가 출력된다.
kubectl diff는 차이가 있으면 종료 코드 1을 반환할 수 있으므로 Shell Script에서 사용할 때는 이 점을 고려해야 한다.
서버 측 검증
kubectl apply \
--dry-run=server \
-f nginx-pod.yaml
실제로 리소스를 변경하지 않고 API Server에서 적용 가능 여부를 확인한다.
다만 Dry Run으로 모든 런타임 오류나 스케줄링 문제까지 검증할 수 있는 것은 아니다.
리소스 구조 확인
kubectl explain pod
Pod 리소스의 기본 구조를 확인할 수 있다.
특정 필드의 구조도 확인할 수 있다.
kubectl explain pod.spec
kubectl explain pod.spec.containers
이 명령어를 사용하면 각 필드의 의미와 사용할 수 있는 구조를 확인할 수 있다.
명령형 명령으로 YAML 생성
kubectl run을 이용해 YAML의 기본 구조를 생성할 수도 있다.
kubectl run nginx \
--image=nginx:1.27 \
--port=80 \
--dry-run=client \
-o yaml
--dry-run=client는 실제 Kubernetes 클러스터에 리소스를 생성하지 않고 로컬에서 생성 결과를 확인하는 옵션이다.
-o yaml은 해당 결과를 YAML 형식으로 출력한다.
파일로 저장하려면 다음과 같이 사용할 수 있다.
kubectl run nginx \
--image=nginx:1.27 \
--port=80 \
--dry-run=client \
-o yaml > nginx-pod.yaml
이후 생성된 파일을 수정하고 적용할 수 있다.
kubectl apply -f nginx-pod.yaml
이러한 방식은 Kubernetes Manifest의 기본 구조를 빠르게 생성할 때 유용하다.
명령형과 선언형 관리 실습 전체 흐름
지금까지 살펴본 과정을 정리하면 다음과 같다.
flowchart TD
A["Kubernetes Pod 생성"] --> B["명령형 방식"]
A --> C["선언형 방식"]
B --> D["kubectl run"]
D --> E["Pod 생성 성공"]
E --> F["동일 명령 재실행"]
F --> G["AlreadyExists 오류"]
C --> H["YAML Manifest 작성"]
H --> I["kubectl apply"]
I --> J["Pod 생성 성공"]
J --> K["동일 Manifest 재적용"]
K --> L["unchanged"]
L --> M["Manifest 설정 변경"]
M --> N["kubectl apply"]
N --> O["configured"]
여기서 가장 중요한 차이는 다음과 같다.
명령형 방식에서는 사용자가 명령한 작업을 실행하려고 한다.
반면 선언형 방식에서는 사용자가 정의한 원하는 상태를 기준으로 필요한 작업을 수행한다.
이 차이 때문에 선언형 관리에서는 동일한 설정을 반복해서 적용하거나 Git으로 설정 변경 이력을 관리하기가 편리하다.
정리
Kubernetes에서는 YAML을 이용해 Pod, Deployment, Service, ConfigMap 등 다양한 리소스의 원하는 상태를 정의할 수 있다.
이때 YAML은 데이터를 표현하는 형식이고, Manifest는 Kubernetes 리소스의 구성 정보를 나타낸다.
Pod와 Deployment를 비롯한 여러 Kubernetes 리소스에서는 apiVersion, kind, metadata, spec을 중심으로 설정을 작성한다.
각 필드는 다음 의미를 가진다.
| 필드 | 역할 |
|---|---|
apiVersion | Kubernetes API 버전 정의 |
kind | 리소스 종류 정의 |
metadata | 리소스 이름과 메타데이터 정의 |
spec | 리소스의 원하는 상태 정의 |
Kubernetes 리소스를 관리하는 방식은 명령형과 선언형으로 구분할 수 있다.
명령형 관리 방식은 수행할 작업을 직접 명령하는 방식이다.
예를 들어 kubectl run이나 kubectl create를 사용하여 리소스를 생성할 수 있다.
이미 같은 이름의 리소스가 존재하는데 새로운 리소스를 생성하려고 하면 AlreadyExists 오류가 발생할 수 있다.
반면 선언형 관리 방식은 원하는 상태를 정의하고 이를 Kubernetes에 적용하는 방식이다.
대표적으로 kubectl apply를 사용한다.
리소스가 존재하지 않으면 생성하고, 기존 리소스의 설정이 달라졌다면 필요한 변경을 반영한다.
설정이 동일하다면 unchanged 결과가 나타날 수 있다.
두 방식의 핵심 차이를 정리하면 다음과 같다.
| 구분 | 명령형 | 선언형 |
|---|---|---|
| 관심사 | 어떤 작업을 수행할 것인가 | 어떤 상태를 유지할 것인가 |
| 대표 명령 | kubectl run, kubectl create | kubectl apply |
| 기존 리소스 존재 | 생성 명령은 오류 가능 | 기존 설정을 확인하고 필요한 변경 반영 |
| 반복 적용 | 명령에 따라 결과가 달라짐 | 동일 설정의 불필요한 변경 최소화 |
| 운영 관리 | 일회성 작업에 편리 | 반복 배포와 설정 관리에 적합 |
또한 선언형 관리를 이해할 때는 Kubernetes의 Reconciliation 구조도 함께 이해해야 한다.
kubectl apply는 사용자가 정의한 원하는 상태를 Kubernetes API에 전달한다.
이후 Deployment나 ReplicaSet 같은 Controller는 자신의 관리 대상에 대해 원하는 상태와 실제 상태를 지속적으로 비교하고 필요한 작업을 수행한다.
이것이 Kubernetes가 선언적 상태를 기반으로 리소스를 관리할 수 있는 핵심적인 이유이다.
실무에서는 이러한 특징을 활용해 Kubernetes Manifest를 Git으로 관리하고, CI/CD 또는 GitOps 도구와 연결하여 반복 가능하고 추적 가능한 배포 환경을 구성할 수 있다.
다만 선언형 방식이라고 해서 모든 설정을 자유롭게 변경할 수 있거나 장애가 자동으로 해결되는 것은 아니다.
각 리소스의 API 구조와 변경 가능한 필드, Controller의 동작 방식까지 함께 이해해야 Kubernetes를 안정적으로 운영할 수 있다.
한 줄 요약
Kubernetes의 선언형 관리는 YAML 등으로 리소스의 원하는 상태를 정의하고
kubectl apply를 통해 적용하는 방식이며, 명령형 관리와 달리 동일한 설정을 반복 적용하고 변경 사항을 체계적으로 관리하는 데 유리하다.