Helm values.schema.json 완벽 정리

Container Orchestration/Kubernetes

Helm values.schema.json 완벽 정리

Somaz 2025. 5. 29. 15:29

728x90

Overview

오늘은 Helm Chart 개발에서 유용한 기능인 `values.schema.json` 에 대해 알아보겠다.

Helm은 기본적으로 `values.yaml` 파일을 통해 사용자 정의 값을 설정하게 되는데, 이 값의 유효성 검사를 자동화하고 싶을 때 `values.schema.json` 을 사용할 수 있다.

Helm `values.schema.json` 은 Helm Chart에서 제공하는 값(`values.yaml`)의 스키마를 정의하는 표준 JSON Schema 파일이다.

이 스키마를 통해, 사용자가 제공하는 값이 올바른 형식과 타입을 가지고 있는지 사전에 검증할 수 있다.

📅 관련 글

Helm에 대한 내용들은 이전 포스팅을 참고하길 바란다.

2022.09.06 - [Container Orchestration/Kubernetes] - Helm 이란? (Kubernetes Package manager)

2023.05.16 - [Container Orchestration/Kubernetes] - Helm Chart 작성방법

2024.11.15 - [Container Orchestration/Kubernetes] - Helm Chart Template 문법

2024.12.20 - [Container Orchestration/Kubernetes] - Helm Chart 생성 및 패키징 (gh-pages)

2025.01.06 - [Container Orchestration/Kubernetes] - Helm Base App Chart 생성(With ArgoCD)

왜 필요한가?

Helm Chart가 점점 커지고 복잡해지면서,
잘못된 값이나 누락된 값으로 인해 배포 시 오류가 발생하는 경우가 많다.
이를 사전에 방지하고, 값의 타입, 필수 여부, 기본 값 등을 강제할 수 있게 해주는 기능이 바로 `values.schema.json` 이다.
특히, CI/CD 파이프라인에서 자동으로 유효성 검사를 수행할 때 매우 유용하다.

기본 구조

파일명은 고정이다.

charts/mychart/values.schema.json

예시

{
    "$schema": "https://json-schema.org/draft-07/schema",
    "type": "object",
    "properties": {
        "replicaCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "배포할 파드의 개수"
        },
        "image": {
            "type": "object",
            "properties": {
                "repository": {
                    "type": "string",
                    "description": "이미지 저장소"
                },
                "tag": {
                    "type": "string",
                    "description": "이미지 태그"
                }
            },
            "required": ["repository", "tag"]
        },
        "service": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": ["ClusterIP", "NodePort", "LoadBalancer"],
                    "description": "서비스 타입"
                },
                "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535,
                    "description": "서비스 포트"
                }
            },
            "required": ["type", "port"]
        }
    },
    "required": ["replicaCount", "image", "service"]
}

주요 기능 정리

기능	설명	예시
타입 지정	값의 타입 강제	`"type": "string"`
기본값 지정	기본값 설정	`"default": 1`
설명 추가	설명 제공	`"description": "배포할 파드 수"`
값 범위 제한	최소, 최대값 설정	`"minimum": 1, "maximum": 10`
필수값 지정	반드시 입력해야 하는 값 정의	`"required": ["replicaCount"]`
열거형 값 지정	특정 값만 허용	`"enum": ["ClusterIP", "NodePort", "LoadBalancer"]`

Helm에서 스키마 검증 동작 방식

Helm 3.7 이상부터, `helm install, helm upgrade` 시 자동으로 `values.schema.json` 을 참조해 유효성 검사를 진행한다.

예시

`values.yaml` 에 아래처럼 잘못된 값을 넣으면

replicaCount: "three"

helm install 시 다음과 같은 오류 발생 한다.

Error: values don't meet the schema requirements:
- (root): replicaCount must be of type integer

장점

유효성 검사를 통해 잘못된 설정을 사전에 방지
필수 값 누락을 방지
값의 타입과 범위를 명확히 정의
자동화된 CI/CD 파이프라인에서 조기 검출 가능
Helm Chart 문서화 효과 (description 활용 가능)

실무 적용 예시

예시: 기본 서비스 설정 검증

`values.schema.json`

{
    "type": "object",
    "properties": {
        "service": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": ["ClusterIP", "NodePort", "LoadBalancer"]
                },
                "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                }
            },
            "required": ["type", "port"]
        }
    }
}

`values.yaml`

service:
  type: ClusterIP
  port: 80

실수 방지 체크리스트

체크포인트	설명
스키마 누락	`values.schema.json` 없으면 검증 안됨
스키마 버전	반드시 Draft 7 또는 4로 작성
설명 작성	가능한한 description 추가
필수 값 명확화	필수값 누락 방지 설정
enum 적극 활용	잘못된 값 입력 방지

FAQ

Q. `values.schema.json` 필수인가요?

아닙니다. 선택사항이다.
다만, 공식 Helm Best Practice에서는 권장하고 있다.

Q. JSON 대신 YAML로 작성할 수는 없나요?

안됩니다. 현재 Helm은 JSON Schema만 지원한다.

Q. Helm 2에서는 동작하나요?

아니요. Helm 3부터 지원한다.

Q. IDE에서 자동완성 지원되나요?

스키마가 정확하게 작성되어 있다면, 일부 IDE (VSCode 등)는 자동완성을 지원할 수 있다.

helm lint로 검증 자동화

Helm은 helm lint 명령을 통해 `values.schema.json` 기반 유효성 검사를 수행한다.

이 명령은 CI/CD에서 Pre-Check로 활용하면 효과적이다.

# chart lint
helm lint ./mychart

# overide value lint
helm lint -f dev.values.yaml

# overide chart value lint
helm lint ../../../charts/base -f ../../../charts/base/base.values.yaml -f dev.values.yaml

values.schema.json 활용 팁

팁	설명
IDE 플러그인 활용	VSCode에 JSON Schema 플러그리를 설치하면, 작성할 때 자동완성과 문법 검사 지원
GitHub Actions과 연동	PR 생성 시 `helm lint` 를 실행하고, schema 검증까지 체크하면 실수 방지 가능
Helm Unit Test와 병행	`helm-unittest` 와 함께 쓰면, 값 검증 + 템플릿 동작까지 테스트하는 강력한 조합 완성
팀 컨벤션 정하기	필수적으로 스키마를 작성하는 규칙을 정하고, 코드리뷰 때 체크리스트에 추가하면 품질 향상

실수 사례 모음

실수 사례	원인	예시
타입 불일치	정수여야 하는데 문자열 입력	`replicaCount: "3"`
누락된 필수 값	필수 값 안 넣음	`image.repository` 빠짐
오타난 필드명	`values.yaml` 과 스키마 필드명이 다름	ingresss (`ingress` 오타)
잘못된 enum 값	허용되지 않는 값 입력	`service.type: ClusterIps`

실무 Tip

✅ Chart Template 개발 시 초기에 스키마부터 작성
✅ 필드 설명 (description)은 내부 문서화 효과까지 노리기
✅ required 설정 적극 사용하여, 실수로 중요한 값 누락 방지
✅ 필드 이름은 팀 내 Naming Rule 정해서 통일
✅ enum 적극 활용해서 의도치 않은 값 입력 방지
✅ Review Culture에 `schema.json` 검증 포함

마무리

values.schema.json은 Helm Chart를 보다 안전하고, 신뢰성 있는 패키지로 만들기 위한 강력한 도구이다.
특히 여러 팀이 함께 사용하는 Helm Chart라면, 스키마 정의는 사실상 필수이다.
Helm Chart를 배포 전에 유효성 검사하고, 사용자가 실수로 잘못된 설정을 입력하는 것을 방지하는 가장 쉬운 방법이 바로 values.schema.json 이다.

Reference

공식 문서: https://helm.sh/docs/topics/charts/#schema-files
JSON Schema Spec: https://json-schema.org/
JSON Schema Draft7: https://json-schema.org/specification-links.html#draft-7

728x90

'Container Orchestration > Kubernetes' 카테고리의 다른 글

Helmfile 완전 정복: 실무에서 Helm을 선언적으로 관리하는 방법 (0)	2025.06.16
배포하다 서비스 터진 적 있다면? 꼭 알아야 할 Kubernetes 전략 가이드 (2)	2025.05.28
Kubernetes Endpoint와 EndpointSlice 완벽 정리 (0)	2025.05.22
Kubernetes에서 Source IP를 보존하는 방법 (0)	2025.05.19
Kubernetes Gateway API 완전 정복 (0)	2025.04.04

현재글Helm values.schema.json 완벽 정리

Somaz의 IT 공부 일지