FormatArc의 한국어 JSON to YAML 변환기 화면에서 변환된 YAML 결과FormatArc의 한국어 JSON to YAML 변환기 화면에서 변환된 YAML 결과
저자: FormatArc게시일: 2026-08-22갱신일: 2026-09-09

JSON YAML 변환 가이드 - Kubernetes·Docker·Python·CLI 정리

TL;DR — 용도별 최적의 방법 10초 요약

  • 지금 바로 변환·설치 불필요 → FormatArc JSON to YAML (브라우저 완결, 업로드 불필요, JSON 문법 검증, 키 순서 보존)
  • CLI / 터미널 한 줄 명령어 → yq -P '.' file.json (DevOps 표준, -P로 블록 형식 지정)
  • Python 스크립트 + 키 순서 유지 → yaml.dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True)
  • Node.js 애플리케이션 → js-yaml의 yaml.dump(data, { lineWidth: -1 })
  • Go 서비스 → gopkg.in/yaml.v3의 yaml.Marshal
  • Kubernetes 라운드트립 → kubectl get ... -o json | jq '...' | yq -P '.'
  • JSON 배열을 멀티 도큐먼트 YAML로 분할 → yq -P '.[]' --split-exp 'true' array.json
방법설치·준비키 순서 보존블록 스칼라 (|)멀티 도큐먼트 출력주석 삽입
FormatArc 브라우저없음지원지원미지원미지원 (변환 후 수동 추가)
yq -P '.'brew install yq지원지원지원 (split-exp)미지원
Python yaml.dump (PyYAML)pip install pyyamlsort_keys=False 필수지원수동 --- 구분미지원
Python ruamel.yamlpip install ruamel.yaml지원지원지원지원 (API 경유)
Node js-yamlnpm install js-yaml지원지원수동미지원
Go yaml.Marshalgo get gopkg.in/yaml.v3지원 (yaml.Node 경유)지원Encoder 루프미지원

JSON → YAML 변환은 구조적으로는 명확합니다(두 형식 모두 동일한 데이터 모델을 표현합니다). 실무에서 까다로운 부분은 키 순서의 보존, 문자열 따옴표 처리, 여러 줄 문자열(줄바꿈)의 다룸, JSON 배열의 멀티 도큐먼트 YAML 분할, Norway 문제 회피 등 구현상의 주의점입니다.

JSON을 YAML로 변환하는 이유

JSON과 YAML은 동일한 데이터 구조(맵/객체, 리스트/배열, 문자열, 숫자, 불리언, null)를 표현할 수 있습니다. 기능적으로는 상호 호환되지만, 실행 환경의 생태계와 가독성에 따라 적절한 형식을 선택합니다.

Kubernetes와 컨테이너 오케스트레이션

Kubernetes는 리소스 정의로 JSON과 YAML을 모두 받아들이지만, 생태계는 압도적으로 YAML 중심입니다. 공식 문서, 튜토리얼, 기술 블로그, 커뮤니티 답변도 거의 대부분 YAML로 작성되어 있습니다. 프로그램이나 API가 생성한 리소스 정의(대부분 JSON)를 YAML로 변환하면 클러스터 설정 전체와 일관성을 유지할 수 있고, 풀 리퀘스트(PR) 검토도 훨씬 수월해집니다.

kubectl에는 다음과 같이 YAML 출력 플래그가 있습니다.

kubectl get deployment web-app -o yaml > deployment.yaml

하지만 원천 데이터(Source of Truth)가 JSON인 경우(Admission Controller 웹훅 응답, Terraform Kubernetes 공급자의 출력, 커스텀 오퍼레이터의 조정 결과 등)에는 명시적인 변환 작업이 필요합니다.

Docker Compose와 Helm values

Docker Compose 파일은 YAML 형식을 표준으로 정의합니다. 서비스 설정이 구성 관리 API나 서비스 메시 컨트롤 플레인 등에서 JSON 형태로 제공된다면 Compose 파일로 사용하기 전에 YAML 변환이 필요합니다.

Helm 차트의 values.yaml 파일 역시 YAML입니다. HashiCorp Vault나 AWS Systems Manager Parameter Store 같은 외부 시크릿 소스에서 설정을 가져올 때(JSON으로 반환됨), helm install -f values.yaml에 전달하기 전에 YAML로 변환해야 합니다.

Ansible 플레이북

Ansible 플레이북과 인벤토리 파일은 YAML 형식입니다. 클라우드 API, CMDB, 자산 관리 데이터베이스 등에서 내보낸 데이터는 일반적으로 JSON이므로, 플레이북에서 사용하기 위한 첫 번째 단계가 바로 YAML 변환입니다.

가독성과 편집 편의성

YAML은 사람이 읽고 쓰기에 최적화된 형식입니다. 중괄호({}), 대괄호([]), 쉼표(,) 같은 문장 부호가 없어 시각적 노이즈가 적습니다.

JSON:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "workers": 4,
    "logging": {
      "level": "info",
      "format": "json"
    }
  }
}

YAML:

server:
  host: 0.0.0.0
  port: 8080
  workers: 4
  logging:
    level: info
    format: json

YAML 버전은 글자 수가 적고 계층 구조가 들여쓰기로 직관적으로 드러납니다. 엔지니어가 직접 자주 확인하고 수정하는 설정 파일에서는 이 가독성의 차이가 큰 효율을 만듭니다.

주석 추가

JSON 사양에는 주석 문법이 존재하지 않습니다. 반면 YAML은 #를 사용한 주석을 표준으로 지원합니다. 설정 파일에 특정 설정값의 의도나 주의사항을 남기고 싶다면 YAML로 변환한 뒤 주석을 추가합니다.

server:
  host: 0.0.0.0
  port: 8080
  # 프로덕션 환경에서는 workers 수를 늘림. 스테이징은 4개로 충분
  workers: 4

JSON → YAML 변환은 설정 파일에 설명을 덧붙이는 첫 단계로 자주 활용됩니다. JSON 자체에는 주석 문법이 없으므로 주석 내용은 JSON에서 가져올 수 없습니다(JSON에 주석을 남겨야 하는 특수한 상황이라면 주석 대체 패턴을 검토할 수 있습니다).

JSON → YAML 변환이 필요한 4가지 실무 시나리오

시나리오 1: Kubernetes API 응답 → Git 매니페스트 저장

Kubernetes API는 JSON을 반환합니다. Deployment 상태를 GitOps 저장소에 YAML 파일로 커밋하는 경우입니다.

kubectl get deployment web-app -o json | yq -P '.' > deployment.yaml
git add deployment.yaml && git commit -m "Capture web-app current state"

시나리오 2: Vault 시크릿 → Helm values

Vault는 시크릿을 JSON으로 반환하고 Helm은 values.yaml을 요구합니다.

vault read -format=json secret/prod/app | jq '.data.data' | yq -P '.' > values.yaml
helm upgrade --install app ./chart -f values.yaml

시나리오 3: 컨트롤 플레인 API → Docker Compose

서비스 메시 컨트롤 플레인이 JSON으로 서비스 정의를 반환하고, Docker Compose는 YAML 형식을 필요로 하는 경우입니다.

curl -s https://control-plane/services | jq '.' | yq -P '.' > docker-compose.yml
docker compose up -d

시나리오 4: CMDB → Ansible 인벤토리

많은 CMDB(Device42, ServiceNow, NetBox 등)는 REST API를 통해 JSON을 반환합니다. Ansible 인벤토리는 YAML입니다.

curl -s https://cmdb/hosts | jq '.hosts' | yq -P '.' > inventory.yaml
ansible-playbook -i inventory.yaml site.yaml

네 가지 시나리오 모두 1단계 파이프라인으로 간단히 처리할 수 있어 자동화 스크립트 작성이 용이합니다.

브라우저 완결 vs 클라우드 변환: 설정 파일 업로드의 보안 위험

시중의 많은 온라인 JSON → YAML 변환기가 "클라이언트 측 처리"라고 안내하지만, 실제로는 입력 데이터를 백엔드 서버로 POST 전송하는 경우가 적지 않습니다. 설정 파일의 경우 다음과 같은 민감 정보가 포함되어 있어 매우 위험합니다.

  • secret: 블록의 API 토큰 및 인증 자격 증명
  • 데이터베이스 비밀번호가 포함된 접속 문자열(Connection String)
  • 클라우드 액세스 키(AWS IAM, GCP 서비스 계정 키 JSON)
  • 내부 호스트 이름 및 인프라 네트워크 구조
  • 암호화 키 및 TLS 인증서

"로그를 남기지 않는다"고 주장하더라도 서버 측의 사소한 설정 오류 하나로 시크릿이 외부에 노출될 수 있습니다. 브라우저 내부에서만 완결되어 데이터를 서버로 전송하지 않는 도구를 사용하는 것이 안전합니다.

이는 단순한 기우가 아닙니다. 2025년 11월, 보안 기업 watchTowr는 대형 온라인 포맷터·변환 사이트인 JSONFormatter와 CodeBeautify에서 사용자가 저장한 데이터가 'Recent Links' 기능을 통해 누구나 열람할 수 있는 상태로 노출되었다고 보고했습니다. 수집된 제출물은 8만 건 이상(5GB 초과)에 달했으며, Active Directory 자격 증명, 데이터베이스 및 클라우드 액세스 키, 개인 키, CI/CD 시크릿, JWT 및 API 토큰, 결제 게이트웨이 인증 정보, AWS Secrets Manager 전체 내보내기 데이터까지 포함되어 정부, 금융, 의료, 항공우주 등 다양한 조직이 영향을 받았습니다(watchTowr 조사 보고서). 입력을 저장하거나 서버로 전송하는 변환기에 붙여넣은 데이터는 동일하게 노출될 위험이 있습니다.

확인 방법: 변환기 웹페이지를 열고 개발자 도구(F12)의 Network 탭에서 "Offline(네트워크 비활성화)"을 체크한 뒤 JSON을 붙여넣어 봅니다. 도구가 정상 작동한다면 브라우저 내 처리 도구입니다. 멈추거나 네트워크 오류가 발생한다면 클라우드 전송 방식입니다.

FormatArc JSON to YAML 변환기는 오프라인 상태에서도 완벽하게 동작합니다. 로컬 CLI 도구인 yq나 로컬 Python/Node.js/Go 스크립트도 동일하게 안전합니다.

Kubernetes Secret, API 토큰이 포함된 Helm values 등 자격 증명이 담긴 설정 파일은 반드시 브라우저 완결형 도구나 로컬 환경에서 변환하세요. 온라인 변환 도구의 안전성을 직접 확인하는 방법은 온라인 변환 사이트 보안 검증을 참조하세요.

방법 1: FormatArc 브라우저 도구 (설치·업로드 불필요)

JSON to YAML 변환기는 JSON을 정돈된 YAML로 변환해 줍니다. 모든 처리는 브라우저 안에서 완결됩니다.

  1. JSON to YAML 변환기를 엽니다.
  2. 왼쪽 에디터 창에 JSON을 붙여넣습니다.
  3. "변환" 버튼을 클릭합니다.

FormatArc JSON to YAML 변환 결과FormatArc JSON to YAML 변환 결과

이 도구는 변환 전에 JSON 유효성을 검증합니다. 쉼표 누락, 불필요한 닫는 괄호(}), 따옴표가 없는 키 등의 문법 오류를 줄 번호와 함께 즉시 표시합니다. YAML 변환이 목적이 아니더라도 빠른 JSON 검증기로 유용하게 쓸 수 있습니다. 자주 발생하는 JSON 문법 오류 해결 방법은 JSON 파싱 오류 해결을 참조하세요.

브라우저 내에서만 실행되므로 인증 정보나 내부 인프라 설정 같은 민감한 데이터를 다룰 때도 안심하고 사용할 수 있습니다.

출력 결과는 Kubernetes 표준인 2칸 들여쓰기(2-space)를 적용하며, 입력 JSON의 키 순서를 보존하고, 기본적으로 블록 스타일(중괄호 없는 표준 YAML 외형)로 깔끔하게 정렬됩니다.

방법 2: yq (DevOps 표준 CLI 도구)

yq는 터미널 환경에서 JSON → YAML 변환을 가장 매끄럽게 처리할 수 있는 도구입니다.

# 기본 변환
yq -P '.' input.json > output.yaml

# 표준 입력(stdin)에서 파이프로 받기
cat config.json | yq -P '.' > output.yaml

# 블록 형식(가독성 높은 표준 YAML); -P 옵션이 없으면 플로우 형식으로 출력될 수 있음
yq -P '.' input.json

# 들여쓰기 너비 지정 (기본값 2)
yq -P -I=4 '.' input.json

# 특정 하위 트리만 추출하여 변환
yq -P '.spec.template' deployment.json

# JSON 배열을 멀티 도큐먼트 YAML로 분할 출력
yq -P '.[]' --split-exp 'true' kubernetes-list.json

-P 옵션은 --prettyPrint의 축약형으로, YAML을 블록 형식으로 강제 출력합니다. -P가 없으면 중첩 구조에서 플로우 형식(JSON과 유사한 형태)으로 출력될 수 있습니다.

설치 방법:

# macOS (Homebrew)
brew install yq

# Linux (바이너리 직접 설치)
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# Docker
docker run --rm -i mikefarah/yq -P '.' < input.json > output.yaml

yq + jq 조합으로 필터링하며 변환하기

# Deployment에서 spec.template만 추출하여 YAML로 변환
jq '.spec.template' deployment.json | yq -P '.'

# yq 단독으로도 처리 가능
yq -P '.spec.template' deployment.json

방법 3: Python (PyYAML과 ruamel.yaml)

PyYAML 기본 사용법

import json
import yaml

with open("config.json") as f:
    data = json.load(f)

with open("config.yaml", "w") as f:
    yaml.dump(
        data,
        f,
        default_flow_style=False,   # 블록 형식 (표준 YAML 스타일)
        allow_unicode=True,          # 유니코드 문자(한글 등)를 \uXXXX로 이스케이프하지 않고 출력
        sort_keys=False,             # 입력 JSON의 키 순서 유지
    )

반드시 지정해야 하는 핵심 옵션 3가지:

  • default_flow_style=False — {a: 1, b: 2} 같은 한 줄 플로우 형식이 아닌 일반 블록 YAML로 출력합니다.
  • allow_unicode=True — 한국어, 특수문자, 이모지 등이 \uXXXX로 변환되지 않고 사람이 읽을 수 있는 텍스트 그대로 유지됩니다.
  • sort_keys=False — JSON의 원래 키 순서를 유지합니다(Kubernetes에서 apiVersion이 kind 앞에 와야 하는 관례를 지키기 위해 필수).

터미널 원라이너

python3 -c 'import sys, json, yaml; yaml.dump(json.load(sys.stdin), sys.stdout, default_flow_style=False, allow_unicode=True, sort_keys=False)' < input.json > output.yaml

ruamel.yaml로 주석 유지 및 서식 보존하기

생성된 YAML에 프로그래밍 방식으로 주석을 추가하거나 세밀한 서식을 유지해야 하는 경우 ruamel.yaml을 사용합니다.

from ruamel.yaml import YAML
import json

yaml_writer = YAML()
yaml_writer.default_flow_style = False
yaml_writer.preserve_quotes = True
yaml_writer.indent(mapping=2, sequence=4, offset=2)

with open("config.json") as fin:
    data = json.load(fin)

# 프로그래밍 방식으로 주석 추가
data.yaml_set_comment_before_after_key("server", before="웹 서버 설정")

with open("config.yaml", "w") as fout:
    yaml_writer.dump(data, fout)

주석이나 인용 부호 서식을 정밀하게 제어해야 할 때는 ruamel.yaml이 최적의 선택입니다.

방법 4: Node.js (js-yaml)

const fs = require("fs");
const yaml = require("js-yaml");

const data = JSON.parse(fs.readFileSync("config.json", "utf8"));
const ymlText = yaml.dump(data, {
  lineWidth: -1,    // 긴 줄이 자동으로 줄바꿈되는 현상 방지
  noRefs: true,     // YAML 앵커 및 별칭(alias) 생성 비활성화
  sortKeys: false,  // 입력 순서 보존
  quotingType: '"', // 따옴표가 필요할 때 큰따옴표 우선 사용
});

fs.writeFileSync("config.yaml", ymlText);

lineWidth: -1은 js-yaml의 자동 줄바꿈 동작을 방지하여 긴 URL이나 설정 문자열이 중간에 끊어지는 것을 막아 줍니다. noRefs: true는 앵커 생성을 비활성화하여 kubectl 등 앵커를 지원하지 않는 하류 도구와의 호환성을 높입니다.

방법 5: Go (gopkg.in/yaml.v3)

package main

import (
    "encoding/json"
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
)

func main() {
    data, _ := os.ReadFile("config.json")
    var obj interface{}
    json.Unmarshal(data, &obj)
    out, _ := yaml.Marshal(obj)
    fmt.Print(string(out))
}

Go에서 키 순서를 확실히 보존하려면 interface{} 대신 yaml.Node를 사용해야 합니다. json.Unmarshal을 통해 map[string]interface{}로 파싱하면 Go 맵의 내부 특성상 순서가 무작위로 섞이게 됩니다. Kubernetes 매니페스트처럼 키 순서가 중요한 환경에서는 문제가 될 수 있습니다.

// 순서를 명시적으로 보존하려면 yaml.Node 사용
var node yaml.Node
yaml.Unmarshal(data, &node)
out, _ := yaml.Marshal(&node)

또는 삽입 순서를 유지해 주는 서드파티 라이브러리(github.com/iancoleman/orderedmap 등)를 활용할 수 있습니다.

Kubernetes Deployment 실전 예제: JSON ↔ YAML 왕복 변환

실제 업무 시나리오입니다. JSON 형식으로 작성된 Deployment 리소스 정의에서 시작합니다.

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "web-app",
    "labels": { "app": "web", "tier": "frontend" }
  },
  "spec": {
    "replicas": 3,
    "selector": { "matchLabels": { "app": "web" } },
    "template": {
      "metadata": { "labels": { "app": "web" } },
      "spec": {
        "containers": [{
          "name": "nginx",
          "image": "nginx:1.25",
          "ports": [{ "containerPort": 80 }],
          "env": [
            { "name": "LOG_LEVEL", "value": "info" }
          ]
        }]
      }
    }
  }
}

yq를 사용해 변환합니다.

yq -P '.' deployment.json

출력 결과:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web
    tier: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80
          env:
            - name: LOG_LEVEL
              value: info

apiVersion → kind → metadata → spec의 순서가 깔끔하게 유지되었습니다. PyYAML을 기본 설정(sort_keys=True)으로 실행하면 알파벳 순으로 정렬되어 kubectl apply 자체는 통과하지만, 업스트림 Kubernetes 예제와의 Git diff가 깨져 코드 리뷰가 어려워집니다.

클러스터 적용: kubectl apply -f deployment.yaml

YAML 문자열 따옴표 처리: "8080"이 숫자 8080으로 바뀌는 문제

YAML은 문자열에 따옴표가 필요한지 여부를 판단하는 규칙이 매우 복잡합니다. 변환기가 이를 처리하는 과정에서 예기치 않은 타입 변환이 일어날 수 있습니다.

숫자 형태의 문자열이 따옴표 해제되는 경우

JSON에서 포트 번호를 "8080"이라는 문자열로 보관하고 있었는데, 변환기가 YAML에서 따옴표를 임의로 제거해 숫자로 바꿔 버리는 경우가 있습니다.

JSON:

{ "port": "8080" }

올바른 변환 결과:

port: "8080"   # 문자열 타입 유지

잘못된 변환 결과:

port: 8080     # 숫자로 변경되어 버림

yq v4, PyYAML(기본 설정), js-yaml은 원래 문자열 타입을 정상적으로 유지합니다. 단순한 정규식이나 휴리스틱으로 직접 만든 변환 스크립트에서 이 문제가 발생하기 쉽습니다.

PyYAML에서 특정 문자열의 따옴표를 강제하려면 다음과 같이 래퍼를 정의합니다.

class QuotedString(str): pass

def represent_quoted(dumper, data):
    return dumper.represent_scalar("tag:yaml.org,2002:str", str(data), style='"')

yaml.add_representer(QuotedString, represent_quoted)

불리언(Boolean)처럼 보이는 문자열 (Norway 문제)

{ "active": "yes" }

YAML 1.1 스키마로 변환했을 때:

active: yes    # 다음 파싱 시점에 불리언 true로 해석됨

품질이 검증된 변환기는 이를 안전하게 따옴표로 감쌉니다.

active: "yes"

원본 JSON을 제어할 수 있다면 "yes" / "no" 같은 문자열 대신 JSON의 표준 타입인 true / false / null을 사용하는 것이 Norway 문제(국가 코드 NO가 false로 변환되는 버그 등)를 원천적으로 방지하는 방법입니다.

특수 문자로 시작하는 문자열

YAML의 특수 문자(*, &, !, {, [, >, |, #, @, \``, 맨 앞의 -`)로 시작하는 값은 반드시 따옴표로 감싸야 합니다.

{ "tag": "*production*" }

tag: "*production*"   # 맨 앞의 * 때문에 따옴표가 적용됨

주요 변환 도구들은 이를 자동으로 안전하게 감싸 줍니다.

블록 스칼라: 여러 줄 문자열을 위한 | vs > 표기법

JSON은 여러 줄 문자열을 \n 이스케이프 문자로 표현합니다. YAML 변환 시에는 가독성이 뛰어난 블록 스칼라(Block Scalar) 표기법을 사용하는 것이 일반적입니다.

JSON:

{
  "description": "Line one\nLine two\nLine three"
}

YAML에서는 세 가지 표현 방식이 가능합니다.

리터럴 블록 (|) — 줄바꿈 그대로 유지

description: |
  Line one
  Line two
  Line three

원본의 줄바꿈이 출력 문자열에 그대로 반영됩니다. 로그 메시지, 인증서 PEM 블록, 설정 파일 안에 포함된 쉘 스크립트에 가장 적합합니다.

폴디드 블록 (>) — 줄바꿈을 공백으로 변환

description: >
  Line one
  Line two
  Line three

이 방식은 Line one Line two Line three라는 단일 문장으로 해석됩니다(줄바꿈이 공백으로 대체되고, 빈 줄만 실제 줄바꿈으로 처리됨). 문단 형태의 긴 설명문에 적합합니다.

따옴표 단일 행 문자열

description: "Line one\nLine two\nLine three"

큰따옴표 안에 \n을 직접 표기하는 방식입니다. 동작은 하지만 2~3줄 이상 길어지면 가독성이 크게 떨어집니다.

yq -P는 줄바꿈을 포함하는 문자열에 기본적으로 |(리터럴) 방식을 적용합니다. PyYAML과 js-yaml도 기본적으로 |를 사용합니다.

PyYAML에서 특정 스타일을 강제하려면:

yaml.dump(data, default_style='|')   # 모든 문자열을 리터럴 블록으로
yaml.dump(data, default_style='"')   # 모든 문자열을 큰따옴표로

여러 줄의 스크립트나 PEM 인증서를 담는 Kubernetes ConfigMap에서는 | 방식을 써야 하며, kubectl create configmap --from-file 역시 | 형태로 매니페스트를 생성합니다.

키 순서 보존: apiVersion → kind → metadata 순서 유지하기

JSON 객체와 YAML 매핑은 사양상 둘 다 순서가 없는(unordered) 구조입니다. 그러나 실제 운영 환경에서는 의미 있는 순서 유지를 요구합니다. 특히 Kubernetes 리소스에서는 apiVersion → kind → metadata → spec의 관례적 순서가 확립되어 있습니다.

주요 도구의 순서 보존 현황:

  • yq (Go yaml.v3 기반): 내부 yaml.Node를 통해 순서 보존
  • PyYAML + sort_keys=False: 순서 보존 (기본값인 sort_keys=True는 알파벳순 정렬이므로 반드시 설정 필요)
  • js-yaml + sortKeys: false: 순서 보존
  • ruamel.yaml: 기본적으로 순서 보존

주의할 점:

  • PyYAML의 기본값 sort_keys=True — 모든 키를 알파벳순으로 정렬하여 apiVersion이 kind 뒤로 밀려남
  • Go의 interface{} 언마샬링 — 맵 순서가 무작위화됨 (yaml.Node 사용 필수)
  • 직접 작성한 스크립트에서 Go 맵(map[string]string)을 거쳐 출력할 때 — 순서가 임의로 뒤섞임

YAML을 Git에 커밋하는 GitOps 워크플로우에서 키 순서가 무작위로 바뀌면 데이터가 동일함에도 불필요한 대규모 Git diff가 발생합니다. 배포 파이프라인에 도구를 도입하기 전에 반드시 키 순서 보존 여부를 확인하세요.

JSON 배열을 멀티 도큐먼트 YAML로 분할 출력하기

Kubernetes 리소스가 담긴 JSON 배열을 ---로 구분된 하나의 멀티 도큐먼트 YAML 파일로 변환하는 패턴입니다.

yq 사용 시

yq -P '.[]' --split-exp 'true' kubernetes-list.json

출력 결과:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: v1
kind: Service
metadata:
  name: app-service

파일 저장: yq -P '.[]' --split-exp 'true' kubernetes-list.json > resources.yaml 명령으로 즉시 kubectl apply -f resources.yaml 가능한 파일이 생성됩니다.

Python 사용 시

import json
import yaml

with open("list.json") as f:
    items = json.load(f)["items"]   # 실제 배열 경로에 맞게 조정

with open("resources.yaml", "w") as f:
    yaml.dump_all(
        items,
        f,
        default_flow_style=False,
        allow_unicode=True,
        sort_keys=False,
    )

yaml.dump_all 함수가 각 항목을 ---로 구분해 여러 문서로 출력합니다.

Node.js 사용 시

const yaml = require("js-yaml");
const fs = require("fs");

const items = JSON.parse(fs.readFileSync("list.json", "utf8")).items;
const ymlText = items.map(item => yaml.dump(item, { lineWidth: -1 })).join("---\n");

fs.writeFileSync("resources.yaml", ymlText);

js-yaml에는 내장 dumpAll이 없으므로 ---\n으로 수동 결합합니다.

CI/CD 파이프라인 연동

GitHub Actions

name: Convert JSON config to YAML for deployment
on:
  push:
    paths: ["config/*.json"]

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yq
        run: |
          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
          sudo chmod +x /usr/local/bin/yq
      - name: Convert all configs
        run: |
          for f in config/*.json; do
            yq -P '.' "$f" > "${f%.json}.yaml"
          done
      - name: Validate against Kubernetes
        run: |
          for f in config/*.yaml; do
            kubectl apply --dry-run=client -f "$f"
          done
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "Auto-convert configs to YAML"

yq 대신 Node.js 환경이 갖춰진 파이프라인이라면 npx formatarc json-to-yaml과 같은 명령을 활용해 추가 바이너리 설치 없이 변환할 수도 있습니다. 자세한 사용법은 formatarc npm을 참조하세요.

GitLab CI

generate-yaml:
  image: mikefarah/yq:latest
  stage: build
  script:
    - for f in config/*.json; do yq -P "." "$f" > "${f%.json}.yaml"; done
  artifacts:
    paths:
      - config/*.yaml

Jenkins (Declarative)

pipeline {
  agent any
  stages {
    stage('Convert configs') {
      steps {
        sh 'for f in config/*.json; do yq -P "." "$f" > "${f%.json}.yaml"; done'
      }
    }
    stage('Validate') {
      steps {
        sh 'for f in config/*.yaml; do kubectl apply --dry-run=client -f "$f"; done'
      }
    }
  }
}

변환과 검증은 각각 명령어 1개로 끝납니다. CI에 얼마나 시간이 걸릴지는 매니페스트 크기와 러너 성능에 따라 달라집니다.

Kubernetes 실무 워크플로우

실무에서 가장 흔히 마주치는 시나리오입니다. kubectl로 기존 리소스를 JSON으로 가져와 수정하고, YAML로 변환해 Git 저장소에 커밋하는 과정입니다.

# 현재 Deployment 설정을 JSON으로 가져오기
kubectl get deployment web-app -o json > deployment.json

# 값 수정 (jq를 사용한 자동 변경 예시)
jq '.spec.replicas = 5' deployment.json > updated.json

# Git 저장소 관리를 위해 YAML로 변환
yq -P '.' updated.json > deployment.yaml

# 변경 사항 확인, 커밋, 푸시
git diff deployment.yaml
git add deployment.yaml && git commit -m "Scale web-app to 5 replicas"

파이프라인 한 줄로 결합:

kubectl get deployment web-app -o json | jq '.spec.replicas = 5' | yq -P '.' > deployment.yaml

스크립트 작성이 필요 없는 단발성 수정이라면 JSON to YAML 변환기에 JSON을 붙여넣고 출력된 YAML을 복사해 파일로 저장하는 것이 가장 빠릅니다.

자주 묻는 질문

YAML 출력에서 포트 번호 8080이 문자열로 바뀌나요?

그렇지 않습니다. YAML은 따옴표 없는 숫자를 숫자로 취급합니다. 실제로 문제가 되는 것은 정반대 상황입니다. JSON의 문자열 "8080"이 YAML에서 따옴표 없는 8080으로 출력되어 다음 변환 시점에 숫자로 변환되어 버리는 현상입니다. 원래의 문자열 타입을 유지하려면 모호한 값을 따옴표로 감싸 주는 변환기를 사용해야 합니다. yq v4와 최신 PyYAML은 이를 정상적으로 처리합니다.

JSON에서 YAML로 변환할 때 주석을 유지할 수 있나요?

불가능합니다. JSON에는 주석 문법 자체가 없기 때문에 JSON → YAML 변환 과정에서 주석을 보존할 수 없습니다. 주석이 중요한 설정 파일이라면 YAML을 원천 데이터로 관리하거나 JSON 환경에 맞는 주석 대안 패턴을 적용해야 합니다.

PyYAML이 키 순서를 알파벳순으로 정렬하는 이유는 무엇인가요?

PyYAML의 yaml.dump는 기본값이 sort_keys=True로 설정되어 있기 때문입니다. sort_keys=False를 지정하면 원본 JSON의 키 순서가 유지됩니다. Kubernetes 리소스에서 apiVersion을 맨 위에 두고 싶다면 필수 옵션입니다.

Helm values.json을 values.yaml로 변환할 수 있나요?

가능합니다. values 데이터 구조는 완전히 동일하며 파일 형식만 다릅니다. yq -P '.' values.json > values.yaml 명령으로 변환한 뒤 helm template ./chart -f values.yaml > rendered.yaml로 렌더링 결과를 검증해 보세요.

YAML의 null이 ~ 기호로 표시됩니다

YAML에서 null을 표현하는 방법은 null, Null, NULL, ~, 빈 값 등 여러 가지가 있습니다. 변환 도구마다 채택하는 기본 표현이 다릅니다. yq는 null, PyYAML은 기본적으로 빈 값, js-yaml은 null을 사용합니다. 모두 동일한 의미를 가지며 외형상의 차이일 뿐입니다. 특정 표현을 강제하려면 다음과 같이 설정합니다.

yaml.add_representer(type(None), lambda d, _: d.represent_scalar("tag:yaml.org,2002:null", "null"))

JSON의 앵커(Anchor)가 YAML 출력에 유지되나요?

JSON 사양에는 앵커 개념이 없습니다. YAML 출력에서 앵커(&anchor / *alias)를 활용하려면 변환 후 수동으로 추가하거나 YAML 전용 에디터를 사용해야 합니다. ruamel.yaml은 프로그래밍 방식의 앵커 생성을 지원합니다.

인터넷 연결 없이 JSON을 YAML로 변환하려면 어떻게 하나요?

로컬 환경에서 사용할 수 있는 3가지 방법이 있습니다. 첫째, 의존성이 없는 Go 단일 바이너리인 yq를 설치합니다. 둘째, pyyaml을 활용한 Python 스크립트를 실행합니다. 셋째, js-yaml을 활용한 Node.js 스크립트를 작성합니다. FormatArc JSON to YAML 변환기 역시 웹페이지를 한 번 로드해 두면 브라우저 내부에서 동작하므로 추가 네트워크 연결 없이 오프라인에서도 사용할 수 있습니다.

역방향 변환 (YAML → JSON)

YAML 파일을 API 전송, 디버깅, JSON 전용 도구 입력 등을 위해 다시 JSON으로 변환해야 한다면 FormatArc의 YAML to JSON 변환기를 동일한 방법으로 편리하게 이용할 수 있습니다. 자세한 변환 방법과 주의사항은 YAML JSON 변환 가이드를 참조하세요.

관련 글

정리

JSON → YAML 변환은 DevOps, IaC(Infrastructure as Code), 구성 관리 워크플로우에서 필수적으로 마주치는 작업입니다. 상황에 맞게 다음 5가지 방식을 선택할 수 있습니다.

  • 설치 불필요·보안이 중요한 설정 데이터: FormatArc JSON to YAML — 브라우저 내 완결, 키 순서 보존, 줄 번호가 포함된 JSON 문법 검증
  • CLI / 파이프라인 자동화: yq -P '.' — DevOps 표준 도구, 필터링 및 멀티 도큐먼트 출력 완벽 지원
  • Python 애플리케이션: yaml.dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True)
  • Node.js 애플리케이션: js-yaml의 yaml.dump + lineWidth: -1, sortKeys: false 옵션
  • Go 서비스: gopkg.in/yaml.v3의 Marshal 함수 및 순서 보존을 위한 yaml.Node 활용

프로덕션 환경에서 꼭 기억해야 할 4가지 주의사항: Kubernetes에서 필수적인 키 순서 보존, 여러 줄 문자열을 위한 블록 스칼라(|) 표기법 사용, 여러 리소스를 다룰 때 JSON 배열의 멀티 도큐먼트 분할, 그리고 Norway 문제와 따옴표 해제로 인한 의도치 않은 타입 변경 방지입니다.