설정 레퍼런스¶

cluster.yaml은 원하는 상태를 정의하고 감사 근거로 남습니다. 알 수 없는 필드는 조용히 무시하지 않고 오류로 보고합니다.

malmok plan -f cluster.yaml --validate-only

문서 식별자¶

apiVersion: malmok.dev/v1alpha1
kind: ClusterSpec

v1alpha1 스키마는 마이너 릴리스 사이에 변경될 수 있습니다. 업그레이드 전 변경 이력을 확인하십시오.

프로파일¶

프로파일은 생략한 값을 채우는 출발점입니다. malmok plan에서 확정된 값과 그 출처를 확인하십시오. 프로파일 이름이 모든 구성의 하드웨어 검증을 뜻하지는 않습니다.

프로파일	용도
`homelab`	온라인 Ubuntu, Cilium Gateway API와 local-path 기본값
`company-prod`	온라인 사내 클러스터용 기본값
`onprem-dmz`	프록시 또는 허용 목록을 사용하는 온프레미스
`airgap-ubuntu`	에어갭 Ubuntu
`airgap-rocky`	에어갭 Rocky
`airgap-conservative`	eBPF 데이터플레인을 사용하지 않는 에어갭 Rocky
`custom`	프로파일 기본값 없이 구성, 계획 승인 시 명시적 확인 필요

최상위 항목¶

항목	역할
`metadata`	클러스터 이름, 프로파일과 현장 주석
`network`	망 모드, Pod·Service 네트워크와 라우팅
`topology`	등록 주소, VIP, 서버·에이전트와 SSH 접근
`os`	OS 계열, NTP, swap과 보안 강화 사전 조건
`kubernetes`	RKE2 버전, 아티팩트 경로, 데이터플레인과 etcd
`pki`	인증서 공급원과 신뢰 배포
`registry`	이미지 레지스트리, 미러, 자격증명과 차트 공급원
`storage`	스토리지 드라이버. `local-path` 설치, `byo-csi` 는 현장 CSI 확인만. `longhorn` 과 `nfs` 는 이번 릴리스가 설치하지 않습니다 — 스키마에 있으나 문서가 지정하면 실행을 멈추고 그 사실을 말합니다
`gateway`	GatewayClass, 주소, 리스너, TLS와 DNS 리포트
`platform`	GitOps와 관측 구성 요소
`output`	감사 리포트, 실행 번들과 이벤트 경로

선언된 설정과 실제 적용¶

스키마 검증은 문서 형식을 검사하며, 모든 선언 기능의 구현이나 노드 적용까지 확인하지는 않습니다. 현재 main의 os.hardening.cisProfile과 prepareCISPrerequisites는 사전 점검·보고서에서 처리하지만 CIS 프로파일과 전체 전제조건을 적용하는 경로에는 연결되지 않았습니다. 이 필드만으로 실행 중인 클러스터 설정이 바뀐다고 가정하지 마시고, 실제 적용 설정을 별도로 확인하십시오.

kubernetes.etcd.snapshotSchedule, snapshotRetention, snapshotTarget은 모든 서버의 RKE2 설정(etcd-snapshot-schedule-cron, etcd-snapshot-retention, etcd-snapshot-dir)에 기록됩니다. 비워 두면 RKE2 기본값(12시간마다, 5개 보관, 각 노드의 로컬 디스크)이 적용됩니다. 저장 위치는 각 서버의 디렉터리이며, 마운트한 백업 디렉터리라면 서버가 시작되기 전에 마운트돼 있어야 합니다. kubernetes.etcd.s3는 예약된 미구현 필드라 문서 검증에서 거부합니다. 이 변경 이전 릴리스는 이 필드들을 선언만 하고 설정에 쓰지 않았습니다.

topology[].gpu는 성격이 다릅니다. 무시하는 것이 아니라 거절합니다. 말목은 device plugin도, RuntimeClass도, GPU 컨테이너 런타임도 설치하지 않으므로, 이 필드를 설정한 문서는 검증 단계에서 거부됩니다. 문서가 지목한 하드웨어를 파드가 보지 못하는 클러스터를 만들어 놓는 대신입니다. 클러스터를 세운 뒤 NVIDIA GPU Operator나 AMD의 해당 도구를 직접 설치하십시오.

시크릿 참조¶

자격증명을 평문으로 넣지 않고 환경변수나 파일을 참조합니다.

registry:
  username: env://REGISTRY_USER
  password: file://./secrets/registry-password

문서에는 시크릿 값 대신 공급원을 기록합니다.

적용될 설정 확인¶

# 네트워크 접근 없이 문법과 스키마 검증
malmok plan -f cluster.yaml --validate-only

# 프로파일을 해석하고 실제 노드를 실측
malmok plan -f cluster.yaml

추가 예제는 examples/에 있습니다. 전체 필드 레퍼런스가 준비되기 전까지 스키마 기준은 api/v1alpha1의 Go 타입입니다.