Helm-Chart Provider
helm-chart provider는 어셈블리 경로마다 패키징된 Helm 엄브렐라 차트를 하나씩 생성합니다. helm provider가 GitOps에서 바로 사용할 수 있는 평탄한 Kubernetes YAML을 내보내는 반면, helm-chart는 차트 스캐폴드, 즉 엄브렐라 Chart.yaml + values.yaml과 기여하는 노드마다 하나씩의 서브 차트를 내보냅니다. 다운스트림 도구는 이를 helm install로 설치하거나, 환경별로 추가 커스터마이징하기 위해 벤더링할 수 있습니다. 이 provider는 (path, provider) 단위로 어셈블합니다. helm-chart Recipe에 바인딩된 모든 노드는 경계의 평가된 directory:에 컴포넌트별 subDirectory:를 결합한 위치의 엄브렐라에 기여합니다. 같은 경로로 평가되는 두 경계는 하나의 병합된 엄브렐라 차트로 합쳐지며, 이 차트는 모든 기여자를 서브 차트 의존성으로 나열합니다.
소스 차트에서 복사된 하위 차트의 템플릿은 작성자가 작성한 내용을 그대로 담습니다. 경계의 syncWave: <integer> 값, 훅의 helm.sh/hook-weight, Aggrega 출처 레이블은 차트가 직접 작성한 경우에만 템플릿에 들어갑니다. 렌더링하는 모든 리소스에 argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>", 출처 레이블을 붙이는 것은 helm provider입니다. 이 provider가 하위 차트에 추가하는, $import:로 로드한 artifact는 출처 레이블과 argocd.argoproj.io/sync-wave 어노테이션을 가지며 helm.sh/hook-weight는 가지지 않습니다(아래 “artifacts: 주입 규칙” 참조). ArgoCD는 sync-wave 어노테이션을 읽고, Helm은 훅의 가중치를 읽습니다.
이 페이지는 helm-chart provider의 작성 레퍼런스입니다. helm과 helm-chart의 구분은 Status 페이지의 Providers 섹션을, provider 전반의 입력 구성 모델은 architecture/16-recipe-input-composition.md를 참조하십시오.
지원되는 입력 종류
helm-chart provider는 두 가지 입력 종류를 받습니다.
- 소스 모드.
source: <chart-path>를 가진 Recipe는 디스크上의 Helm 차트 디렉터리를 가리킵니다. 차트는 차트 자체의name을 제외하고 그대로 umbrella 구조에 하위 차트로 복사됩니다. “umbrella가 소유하는 차트 이름”을 참조하십시오. 노드 단위에서는 렌더링이나 템플릿 처리가 수행되지 않습니다. Aggrega의 역할은 템플릿 평가가 아니라 구성(경계의 노드들에 걸친 umbrella 조립)입니다. $import:로 로드한artifacts:모드. 항목별로$import:로 작성한artifacts:항목을 가진 Recipe는 추가 템플릿 파일을 선언하며, helm-chart provider는 소스 차트를 복사한 뒤 이 파일들을 하위 차트의templates/디렉터리에 주입합니다. 각 파일은[[ ]]구분자를 사용하여 Aggrega의 템플릿 컨텍스트에 대해 사전 템플릿 처리되므로(아래 “artifacts:주입 규칙” 참조), 같은 파일 안의{{ }}Helm 템플릿은 이후helm install렌더링까지 그대로 유지됩니다.
helm-chart를 대상으로 하면서 workload:를 선언한 Recipe는 렌더링 전에 거부되며, 이때의 거부는 선언하지 않은 입력 종류에 대해 어떤 provider든 내놓는 것과 같습니다. 즉 이 provider가 지원하는 종류를 명시하고 작성자에게 합성을 수행하는 provider를 안내합니다:
provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (provider가 노드의 입력 종류를 지원하지 않습니다(노드 “api”). provider “helm-chart”는 합성된 recipe를 지원하지 않습니다(이 provider가 지원하는 것: sourced). 지원되는 입력 종류 중 하나를 선언하거나, 합성을 지원하는 provider를 대상으로 지정하십시오)
이 분리는 의도된 것입니다. 워크로드 합성(추상 Workload를 Kubernetes 리소스로 변환하는 일)은 helm provider만의 관심사입니다. helm-chart의 역할은 작성자가 이미 만든 차트에 대한 umbrella + 하위 차트 구성입니다.
helm-chart를 대상으로 하는 Recipe는 인라인 콘텐츠 artifacts: 항목(값이 $import:로 로드한 참조가 아니라 파일 본문을 Recipe 안에 인라인으로 담은 블록 스칼라인 항목)도 선언할 수 있습니다. 인라인 콘텐츠 항목은 작성된 키 그대로 하위 차트 루트에 배치되며, templates/ 접두사도, 출처 정보 삽입도 없습니다. 차트 자체의 템플릿은 Helm의 .Files.Get / .Files.Glob(파일로부터 ConfigMap을 만드는 표준 패턴)을 통해 이런 개별 파일을 읽으므로, 차트 루트의 파일은 오류가 아니라 정당한 일급 형태입니다.
두 형태 모두 배치 전에 [[ ]] Aggrega 구분자로 평가되므로, 어느 형태의 본문이든 Recipe의 기둥 컨텍스트를 읽을 수 있습니다. 어느 본문의 {{ }}이든 건드리지 않고 남겨지며, 이후 helm install 시점에 Helm 지시문이 됩니다. 두 형태의 차이는 파일이 놓이는 위치와 출처 정보가 병합되는지 여부입니다.
$import:로 로드한 항목은 템플릿 파일입니다. 평가 후(아래 “artifacts:주입 규칙” 참조) 출처 정보가 병합된 채로 하위 차트의templates/디렉터리에 주입되므로, Helm은 이를 차트 자체의 템플릿과 함께 매니페스트로 렌더링합니다.- 인라인 콘텐츠 항목은 개별 데이터 파일입니다. 평가 후 차트 루트에 놓이며, 평가 결과에서 변경되지 않고 병합된 출처 정보도 담지 않은 채
.Files기반으로 사용됩니다.
artifacts: 주입 규칙
helm-chart Recipe가 항목별 $import:를 통해 artifacts: 항목을 선언하면, 각 $import: 값은 Recipe 자체 디렉터리를 기준으로(디스크에서 Recipe YAML이 들어 있는 디렉터리) 해석되는 템플릿 파일 경로입니다. provider는 다음을 수행합니다.
- 각 파일의 내용을 읽습니다.
- Recipe의 템플릿 컨텍스트(Recipe의
valuesMapping:이 평가되는 것과 같은 컨텍스트)를 대상으로 Aggrega 구분자[[ ]]를 사용해 내용을 사전 템플릿 처리합니다. 파일 내용 안의{{ }}는 그대로 남으며,helm install시점에 Helm 템플릿 지시문이 됩니다. - 각 파일을 umbrella의 어셈블리 경로 아래
charts/<instance-id>/templates/<authored-key>에 기록하며, 번들의 파일은 그 키 아래에 중첩됩니다. 항목이 작성된 키가 파일 이름을 정하고,$import:경로는 내용을 선택할 뿐 이름에는 아무것도 기여하지 않으므로, 그 경로 안의 디렉터리 구조는 출력에 반영되지 않습니다.
[[ ]] / {{ }} 이중 구분자 규율이 핵심이 되는 세부 사항입니다. 일반적인 $import:로 로드된 아티팩트 파일에는 Aggrega 시점 보간(예: [[ .values.image ]])과 Helm 시점 보간(예: {{ .Release.Namespace }})이 섞여 있을 수 있습니다. 각 구분자 쌍은 자신의 단계에서 동작합니다. Aggrega는 파일이 배치되기 전 컴파일 시점에 [[ ]]를 해석하고, Helm은 umbrella가 배포된 후 설치 시점에 {{ }}를 해석합니다.
소스 차트의 템플릿과 $import:로 로드된 아티팩트 주입 사이에 파일 이름이 충돌하면 CATALOG_ERROR가 발생하며, 진단에는 충돌하는 출력 경로(예: templates/cm.yaml)와 그것을 생성한 두 입력 종류가 표시됩니다. 작성자는 아티팩트의 키나 차트 자체 템플릿의 이름을 바꿔 충돌을 해결합니다.
source: 키 집합
helm-chart provider의 source:는 차트를 지정하며, source: 필드가 취하는 두 가지 형태를 모두 받아들이고 helm provider의 source: 키 집합이 설명하는 그대로 읽습니다. 즉 파일 시스템 경로 문자열 그 자체와, url:에 위치를 담는 구조화된 객체입니다. url:이 파일 시스템 경로를 지정하면 아무것도 가져오지 않고 디스크에서 차트를 읽습니다. 전송 스킴을 담고 있으면(예: kind: helm-oci-chart와 함께 쓰는 oci://…) aggrega pull이 차트를 가져와 고정하고, 빌드는 디스크에서 읽은 차트와 같은 조건으로 캐시에서 차트를 꺼내 umbrella에 하위 차트로 복사합니다.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}소스 경로의 차트는 루트에 유효한 Chart.yaml을 반드시 포함해야 합니다. 이 파일이 없으면 복사가 실행되기 전에 명확한 오류가 발생합니다. 차트의 디렉터리 구조는 복사 시 그대로 유지되므로, 구성 후 하위 차트 디렉터리에는 templates/, values.yaml, Chart.yaml 및 기타 모든 파일이 존재합니다. 모든 파일은 주석, 키 순서, 따옴표 처리까지 작성한 바이트 그대로 도착합니다. 유일한 예외는 차트 자체 Chart.yaml의 name 필드로, 이 값은 umbrella가 설정합니다. “umbrella가 소유하는 차트 이름”을 참조하십시오.
차트를 지정하지 못하는 두 가지 경우는 모두 거부되며, 두 거부는
서로 다른 곳에서 나옵니다. capability를 바꾸면 그중 하나만 달라지므로
알아 둘 가치가 있습니다. 존재하지만 아무것도 선언하지 않는 source:는
어떤 provider도 실행되기 전에 컴파일러가 거부하므로, Recipe가 어떤
capability를 지정하든 결과는 같습니다. 진단은 sourceless 모드를 원하면
필드를 생략하거나 비어 있지 않은 경로를 지정하라고 안내합니다. source:를 아예 생략하는 것은
올바른 작성 방식이며(Recipe가 sourceless 모드를 요청하는 방법입니다), 여기서 거부되는
이유는 helm-chart가 sourced 입력 종류만 선언하기 때문입니다. 따라서 컴파일러는
capability가 선언하지 않은 입력 종류를 요청받았을 때와 같은 메시지로 이 조합을 거부합니다. helm-chart 고유의 것은 거부가 아니라
선언입니다. workload: 블록에서 생성하는 Kubernetes 리소스에는
대신 helm capability를 사용하십시오.
omits:를 선언한 Recipe는 거부됩니다. omits:
키는 소스가 렌더링하는 문서를 빌드에서 제외하는데, 이 provider는 빌드 시점에
문서를 렌더링하지 않습니다. 차트를 umbrella에 복사하고, 차트의 템플릿은
umbrella가 설치될 때 렌더링됩니다. 렌더링되는 것이 없으니 제외할 것도
없으므로, 이 provider는 이 키를 지원한다고 선언하지 않으며,
이 키를 선언한 Recipe나 FeatureRecipe는 아무것도 복사되기 전에 거부됩니다.
The provider does not support omits (provider가 omits를 지원하지 않음)을 참조하십시오.
Recipe 옆에 두는 차트라면 그곳의 .aggregaignore에 한 줄을 추가하여 대신
차트의 파일을 제외할 수 있으며, 이는 다음에 Recipe를 고정할 때부터 적용됩니다. 가져온
차트의 출력에서 문서를 빼야 한다면 이 키를 지원하는 helm provider로
렌더링하십시오.
경로 키 기반 구성 — 엄브렐라 형태
이 provider는 어셈블리 경로마다 두 단계로 실행됩니다.
- 기여자별 복사. helm-chart Recipe에 바인딩된 각 노드에 대해 provider는 소스 차트의 전체 디렉터리 트리를 서브 차트 슬롯에 복사합니다. 파일은 기여자별 출력 맵에 평탄하게 놓입니다. 어셈블러는 기여자가 놓일 하위 디렉터리로
charts를 지정하고, 오케스트레이터는 엄브렐라를 조립할 때 그 안에 기여자마다 고유한 디렉터리를 부여합니다. component의 경우charts/<instance_id>/입니다. Feature 첨부도 기여자이며(차트를 벤더링하든 helm provider를 통해 매니페스트를 렌더링하든 마찬가지입니다), component의 디렉터리 안이 아니라 그 옆에 디렉터리를 받습니다. “첨부의 차트가 놓이는 위치”를 참고하십시오. (path, provider)별 엄브렐라 조립. 해당 경로의 노드별 복사가 모두 끝나면 어셈블러는 어셈블리 경로의 루트에 엄브렐라Chart.yaml+values.yaml을 출력합니다. 엄브렐라는 기여하는 노드마다 의존성 하나를 선언하고, 노드별 값을 instance-id를 키로 하는 하위 블록 아래로 라우팅합니다. 어셈블리 경로가 둘 이상의 경계로부터 기여자를 받는 경우(directory:를 공유하는 경계), 모든 기여자가 같은 엄브렐라의 의존성으로 놓입니다.
엄브렐라 Chart.yaml의 형태는 다음과 같습니다.
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: Aggrega umbrella chart for boundary "<assembly-path>"dependencies: - name: <encoded-instance-id> # the name the placed sub-chart carries version: <user-chart-version> # from the source chart's Chart.yaml alias: <encoded-instance-id> # see "How a name is derived" below repository: file://charts/<instance_id> # the sub-chart's own directory차트 이름 결정
엄브렐라의 차트 name은 경계 어노테이션 캐스케이드를 통해 결정됩니다. 기여하는 각 경계의 유효한 aggrega.ai/chart-name 어노테이션(경계 트리를 거슬러 올라가며 캐스케이드로 결정된 값)이 엄브렐라 이름을 정합니다. 결정된 값은 다른 모든 식별자와 똑같이 차트 이름 위치에 맞게 인코딩되므로, 아래 규칙이 유지하는 문자, 숫자, 밑줄, 하이픈만 담은 값은 그대로 차트에 도달합니다. 어셈블리 경로가 둘 이상의 경계로부터 기여자를 받는 경우, 모든 기여자의 유효한 aggrega.ai/chart-name은 반드시 같은 값으로 결정되어야 합니다. 불일치하면 충돌하는 값과 기여하는 경계를 명시하는 진단과 함께 빌드가 중단됩니다.
캐스케이드는 DRY 문제를 자연스럽게 해결합니다. 부모 경계에 aggrega.ai/chart-name을 한 번 선언하면 자식 경계는 캐스케이드를 통해 이를 상속합니다. 공통 부모가 없는 형제 경계는 일치하는 값을 명시적으로 선언해야 합니다. 캐스케이드 어디에도 aggrega.ai/chart-name이 선언되지 않은 경계는 aggregate 이름과 어셈블리 경로(dist/ 아래 엄브렐라의 출력 디렉터리, 예: boundaries/data/helm-chart)로 대체되며, 각각 아래에 설명한 대로 인코딩되어 결합됩니다.
각 의존성 항목의 name은 배치된 서브 차트가 지니는 이름, 즉 component 인스턴스 고유의 인코딩된 식별자이며 alias와 같은 값입니다. 그 이유는 “엄브렐라가 소유하는 차트 이름”에 있습니다. version은 여전히 소스 차트 자체의 Chart.yaml에 있는 버전입니다. alias는 서브 차트의 값을 values.yaml.<alias>.* 아래로 범위 지정하며, 이는 Helm의 엄브렐라 값 관례에 맞추어 엄브렐라를 설치할 때 인스턴스별 값이 올바르게 전파되도록 합니다.
component의 서브 차트 디렉터리는 instance_id를 작성된 그대로 유지하므로, charts/<instance_id>/가 그 파일이 놓이는 곳이자 의존성의 repository가 가리키는 곳입니다. 따라서 같은 소스 차트의 두 인스턴스가 파일 시스템 충돌 없이 공존하며, 각각 자신의 alias 아래에 고유한 값 블록을 유지합니다.
의존성의 name과 repository는 서로 다른 문자열이며, 이는 의도된 설계입니다. name은 해당 위치의 차트가 선언하는 이름입니다. Helm은 자식 차트가 스스로 선언한 이름으로 의존성을 자식 차트에 바인딩하기 때문입니다. repository는 그 차트가 놓인 위치입니다. component의 경우 둘 다 같은 instance id에서 파생되므로 우연히 같게 보입니다. Feature 첨부의 경우 둘은 다릅니다. 선언된 이름은 첨부의 합성된 식별자를 담고, 디렉터리는 두 좌표를 결합한 값을 담습니다. 따라서 어느 하나를 다른 하나로 읽으면 존재하지 않는 대상을 가리키게 됩니다.
첨부의 차트가 놓이는 위치
차트를 벤더링하는 Feature 첨부는 자신이 첨부된 component의 옆, 즉 charts/ 바로 한 단계 아래에 고유한 디렉터리를 받습니다.
charts/├── api/ # the component's own chart├── api--guardrail/ # a Feature attached to `api` under `guardrail`└── api--audit/ # a second Feature attached to the same componentcomponent가 아니라 경계에 첨부된 Feature는 이름을 붙일 호스트 component가 없으므로, 디렉터리는 인스턴스 이름만으로 정해집니다: charts/aux/.
안이 아니라 옆에 두는 이유. Helm은 charts/*에서 자식 차트를 찾습니다. 재귀적으로 탐색하지 않고 한 단계만 봅니다. 그보다 깊이 놓인 차트는 어떤 것의 자식도 아니며, 다른 자식의 디렉터리 안에 있는 데이터일 뿐이어서 .Files를 통해서만 접근할 수 있습니다. 따라서 component 자체의 차트 디렉터리 안에 놓인 차트는 출력에 복사되고 빌드도 성공하지만, 배포하는 대상에 어떤 리소스도 기여하지 않으며 이를 알려 주는 것도 없습니다. 각 기여자를 고유한 최상위 디렉터리에 두어야 첨부의 리소스가 렌더링됩니다.
엄브렐라는 첨부도 자신의 의존성 중 하나로 선언합니다. 두 가지 모두 필요합니다. charts/ 아래에 있지만 dependencies:에 없는 차트는 lint 오류이며, dependencies:에 선언되었지만 일치하는 자식 차트가 없으면 엄브렐라가 로드를 거부합니다.
두 좌표는 단순히 이어 붙이는 것이 아니라 결합됩니다. 디렉터리 이름은 호스트와 인스턴스로부터 합성되며, 아래에 설명하는 것과 같은 이스케이프 규칙을 각 좌표에 적용한 다음 --로 결합합니다. --로 그대로 이어 붙이면 모호해집니다. 이름이 a--b인 호스트와 인스턴스 c, 그리고 호스트 a와 인스턴스 b--c가 같은 디렉터리에 도달하게 됩니다. 각 좌표를 먼저 인코딩하면 둘이 구분되므로, 좌표 안에 작성된 --는 -zh-로 나타납니다.
디렉터리 이름이 허용하는 문자. 대소문자 ASCII 문자, 숫자, 마침표, 밑줄은 작성한 그대로 통과하므로 API--aux와 web.api--aux는 예상한 대로 읽힙니다. 작성한 하이픈은 그 뒤의 문자가 이들 중 하나이면 유지되므로 web-api--aux는 바뀌지 않습니다. 두 개 연속된 하이픈은 이스케이프됩니다. 그 쌍이 결합 기호이기 때문입니다. 그 밖의 문자는 차트 이름과 같은 규칙으로 이스케이프됩니다. 이 집합의 경계가 이렇게 정해진 이유는, 이 디렉터리 이름이 디스크상의 경로이자 의존성의 file:// 포인터가 가리키는 위치이기 때문이며, 파일 이름에는 문제없는 문자도 URL을 잘라 내거나 다시 디코딩되게 할 수 있습니다.
값은 디렉터리가 아니라 선언된 이름을 따릅니다. 자식 차트의 값은 그 차트가 선언하는 이름 아래로 범위가 지정되므로, 위 차트의 값은 디렉터리가 아니라 api--guardrail의 선언된 이름인 cfr-zh-api-zh-guardrail로 지정됩니다.
그 키를 직접 작성할 일은 없습니다. 값은 첨부에 작성하며, 엄브렐라의 values.yaml은 배치된 차트가 지정되는 주소에 블록이 이미 놓인 상태로 자동 구성됩니다. component에 첨부된 Feature의 경우 그것은 첨부에 선언하는 values:이며 FeatureRecipe 자체의 valuesMapping:이 이를 읽습니다. 경계에 첨부된 Feature의 경우 그곳에 선언하는 infra:입니다. 경계에 첨부된 Feature에는 component 값 기둥이 없기 때문입니다. 어느 쪽이든 valuesMapping:이 결정하는 맵이 엄브렐라 안에서 첨부 고유의 블록이 됩니다.
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"이것이 그 값들이 전달되는 유일한 경로입니다. Feature가 가져오는 차트는 “엄브렐라가 소유하는 차트 이름”에 설명된 단 하나의 매니페스트 필드를 제외하면 작성자가 작성한 그대로의 파일로 도착합니다. 따라서 그 차트에 값을 써 넣는 것은 없으며, 값을 공급하는 것은 엄브렐라의 블록입니다. 블록이 도착하지 않은 차트는 망가진 차트가 아닙니다. 자체 values.yaml이 제공하는 기본값으로 렌더링하고 성공을 보고합니다. 그러므로 작성 중에 차이를 확인하고 싶다면 기본값에 눈에 띄는 값을 지정하십시오.
FeatureRecipe가 helm provider를 통해 렌더링하는 첨부
이 대상의 컴포넌트에 첨부된 helm capability의 FeatureRecipe는 차트가 아니라 완성된 Kubernetes 매니페스트를 가져옵니다. 이 매니페스트는 helm provider가 렌더링한 그대로 첨부 자체의 디렉터리에 놓이며, provider는 그 디렉터리를 Helm이 설치하는 차트로 만드는 두 가지를 제공합니다. 하나는 첨부 자체의 이름을 버전 0.1.0으로 선언하는 최소한의 Chart.yaml이고, 다른 하나는 렌더링된 각 YAML 파일을 이름으로 Helm의 .Files.Get을 통해 내보내는 템플릿 templates/rendered.yaml입니다:
charts/api--guardrail/├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0├── guardrail-config.yaml # the manifest the helm provider rendered└── templates/ └── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}선언되는 이름은 같은 첨부가 차트를 벤더링했다면 그 차트가 선언했을 이름과 같으므로, 엄브렐라의 의존성 항목과 values 블록은 위에서 설명한 방식 그대로 주소가 지정됩니다. .Files.Get은 파일의 바이트를 다시 평가하지 않고 그대로 반환하므로, 리터럴 템플릿 중괄호를 담은 매니페스트(경고 규칙의 {{ $labels.instance }}, 대시보드의 쿼리 등)는 그것을 온전히 유지한 채 설치됩니다. 그 값은 helm provider가 매니페스트를 렌더링할 때 이미 매니페스트에 해석되어 들어갔으므로, 엄브렐라의 values.yaml이 그 이름 아래 담는 블록은 아무것도 읽지 않습니다.
umbrella가 소유하는 차트 이름
Aggrega가 벤더링한 차트 안에서 변경하는 유일한 것은 그 차트 자체의 name 필드입니다. 배치된 차트의 Chart.yaml에서 name은 해당 차트를 기여한 대상의 인코딩된 식별자로 설정됩니다.
component의 경우 이는 component 인스턴스 자체의 식별자, 즉 dependency의 alias와 같은 값이며, umbrella의 dependency 항목도 그 값을 지정하므로 양쪽은 항상 일치합니다.
Feature attachment가 가져오는 차트는 그 자체로 하나의 기여자이며, 연결된 component의 식별자를 반복하지 않고 자체 식별자를 선언합니다. 이 식별자는 작성한 두 가지, 즉 attachment를 호스팅하는 component와 Feature가 연결된 이름으로 구성되며, 그 앞에 component가 아닌 attachment의 식별자임을 표시하는 짧은 접두부가 붙습니다. 구성된 값은 이후 다른 모든 식별자와 똑같이 아래의 파생 방식을 통해 차트 이름 위치에 맞게 기록됩니다.
따라서 차트를 벤더링하는 Feature를 api라는 component에 guardrail이라는 이름으로 연결하면 cfr-zh-api-zh-guardrail을 선언하는 차트가 배치되고, 그 component 자체의 차트는 여전히 api를 선언합니다. 두 차트는 별개의 기여자이며, 둘 다 호스트의 이름을 선언하는 대신 각자 고유한 이름을 선언합니다.
차트의 다른 부분은 전혀 건드리지 않습니다. 다른 모든 파일은 작성한 그대로 바이트 단위로 도착하며, Chart.yaml 안에서도 다른 모든 필드, 모든 주석, 키 순서와 따옴표 처리는 작성된 그대로입니다. 매니페스트의 다른 곳에 중첩되어 있으면서 우연히 name이라는 이름을 가진 키(예: 메인테이너의 이름)는 그대로 둡니다.
umbrella에 그 필드가 필요한 이유. 차트의 name은 Helm이 umbrella의 dependency를 바인딩하는 대상입니다. 이 값은 차트를 작성한 사람이 기록하며, upstream에서 가져온 차트라면 그 사람은 배포하는 사람이 아닙니다. 따라서 하나의 assembly 경로에 있는 두 component가 매니페스트에 같은 이름을 선언한 차트를 벤더링하는 일은 충분히 있을 수 있습니다. 두 하위 차트가 모두 그 공유된 이름을 유지하면 umbrella의 두 dependency는 모두 Helm이 먼저 로드한 쪽으로 해석됩니다. 즉 한 component의 차트는 두 번 렌더링되고 다른 component의 차트는 전혀 렌더링되지 않는데, 각 component의 값은 여전히 도착하므로 출력은 완전해 보이지만 잘못된 결과가 됩니다. 배치된 이름을 component 인스턴스에서 파생하면 공유된 이름 자체가 사라지므로 아무것도 거부할 필요가 없습니다. 여기에는 다른 해결책이 없는 두 경우, 즉 이름이 구조적으로 공유되는 같은 차트를 두 component 아래에 벤더링하는 경우와 이름을 바꿀 수 없는 직접 작성하지 않은 차트를 벤더링하는 경우도 포함됩니다.
관찰할 수 있는 유일한 차이. 자기 차트의 이름을 읽는 템플릿, 즉 {{ .Chart.Name }} 및 흔히 쓰이는 {{ .Chart.Name }}-{{ .Release.Name }} 리소스 명명 관용구처럼 그로부터 파생된 모든 것은 원본 차트의 Chart.yaml에 적힌 이름이 아니라 인코딩된 인스턴스 식별자를 읽습니다. 이는 필드가 설정되기 전에도 그런 템플릿이 이미 읽던 값입니다. Helm은 하위 차트를 부모가 바인딩하는 alias로 보고하기 때문입니다. 필드를 설정하면 디스크의 파일이 렌더링이 이미 생성하던 결과와 일치하게 될 뿐입니다. 따라서 아래 예제에서 api-east 하위 차트의 템플릿은 api-east를 읽습니다.
리소스 이름에 차트에 작성된 원래 이름이 들어가야 한다면 그 이름을 차트의 values.yaml에 넣고 거기서 읽으십시오. 값은 작성자의 것이며 Aggrega는 이를 건드리지 않습니다.
이름이 파생되는 방식
Helm 차트 이름과 Helm dependency alias는 각각 aggregate 이름, boundary 경로 또는 instance_id가 가질 수 있는 것보다 좁은 문자 집합만 허용합니다. 파생 방식은 대상이 허용하지 않는 문자를 다른 문자로 대체하지 않고 풀어서 기록하므로, 구두점만 다른 두 식별자는 항상 서로 다른 두 이름이 되며, 한 alias 아래에 기록된 값은 그 alias가 지정하는 하위 차트에만 도달할 수 있습니다.
- 문자, 숫자, 밑줄은 작성된 그대로 전달됩니다.
- 하이픈은 그 뒤의 문자가 그대로 전달되는 문자이고 소문자
z가 아닌 경우 작성된 그대로 유지됩니다. 소문자z가 뒤따르는 하이픈은 이스케이프를 시작하므로, 그 위치에 작성된 하이픈은 그 자체가 풀어서 기록됩니다.api-zone은api-zhzone이 되며, 이 덕분에 어떤 이름이든 추측 없이 원래대로 읽어 낼 수 있습니다. - 그 밖의 모든 문자는
-z뒤에 해당 문자를 나타내는 글자를 붙여 기록합니다. 점은d, 경로 구분자는s, 위 규칙이 유지하지 않는 하이픈은h입니다. 나머지는x와 그 문자의 6자리 16진수 코드 포인트로 기록하고, 어떤 문자의 시작도 아닌 바이트는b와 그 바이트의 2자리 값으로 기록합니다. 따라서 유효한 텍스트가 아닌 이름도 뭉개지지 않고 구별되게 기록됩니다. - 빈 값은
-ze로 기록되며, 비어 있지 않은 값은 이를 만들어 낼 수 없습니다. - 두 식별자가 하나의 차트 이름을 구성하는 경우(aggregate 이름이 어셈블리 경로를 한정하는 경우) 두 식별자는
--로 연결됩니다. 인코딩된 단일 식별자에는 이 쌍이 절대 포함되지 않으므로, 연결된 이름에서 어느 식별자가 어느 것인지 모호함 없이 알 수 있습니다.
따라서 instance_id data.main-db는 alias data-zdmain-db가 되고, aggregate fullstack-app과 어셈블리 경로 boundaries/data/helm-chart는 차트 이름 fullstack-app--boundaries-zsdata-zshelm-chart가 됩니다. 동일한 입력은 항상 동일한 이름을 생성합니다.
umbrella values.yaml은 alias를 키로 사용합니다.
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2하위 차트의 valuesMapping:이 해당 템플릿 컨텍스트에 대해 평가되면, 결과 값 맵이 alias를 키로 하는 이 하위 블록을 자동으로 채웁니다. 이는 component에만 해당하는 것이 아니라 umbrella의 모든 기여자에 해당합니다. 차트를 벤더링하는 Feature attachment는 그 자체로 하나의 기여자이므로, 그 FeatureRecipe의 valuesMapping:은 배치된 차트가 선언하는 이름을 키로 하는 자체 블록을 채웁니다. “attachment의 차트가 배치되는 위치”를 참조하십시오.
valuesMapping:이 null로 설정한 키는 해당 블록에 null로 기록됩니다. Helm 4로 설치할 때, umbrella 자체의 values.yaml에 있는 null은 설치 시 해당 하위 차트에 대한 값도 함께 제공되는 경우에만 그 키에 대한 하위 차트의 기본값을 제거합니다. 해당 하위 차트에 대한 값을 제공하지 않는 설치에서는 null이 버려지고 하위 차트의 기본값이 유지됩니다. helm install에 전달된 값에 있는 null은 어느 경우든 기본값을 제거합니다.
Provider별 특이 사항
- 하위 차트의
Chart.yaml은 필수입니다. 복사 작업은 소스 경로 루트에Chart.yaml이 있는지 확인합니다. 이 파일이 없으면 umbrella 단계가 실행되기 전에 빌드가 중단됩니다. - 배치된 차트의
name은 umbrella의 것입니다. 이 값은 해당 차트를 기여한 대상의 인코딩된 식별자로 설정됩니다. 즉 component 인스턴스 자체의 식별자이거나, Feature 연결이 가져오는 차트의 경우 해당 연결 자체의 식별자입니다. 그리고 이것은 벤더링된 차트 안에서 Aggrega가 변경하는 유일한 것입니다. “The chart name the umbrella owns(umbrella가 소유하는 차트 이름)”를 참조하십시오. - 소스 차트는 버전과 이름을 선언해야 합니다. 의존성 항목의 버전은 소스 차트 자체의
Chart.yaml이 선언하는 버전이므로, 버전을 선언하지 않은 차트는 버전을 부여받는 대신 빌드를 중단시킵니다. 하위 차트가 갖고 있지 않은 버전에 고정된 의존성은 umbrella의 인스턴스별 값이 그 하위 차트에 도달하지 못하게 만들기 때문입니다.Chart.yaml이 이름을 선언하지 않거나, 둘 이상의 YAML 문서를 담고 있거나, 파싱되지 않는 차트도 같은 이유로 중단됩니다. umbrella는 읽을 수 없는 하위 차트를 구성할 수 없습니다. - 인코딩된 별칭과 차트 이름. Helm 차트 이름이나 의존성 별칭이 허용하지 않는 문자를 포함한 instance_id, aggregate 이름 또는 경계 경로는 위의 “How a name is derived(이름이 도출되는 방식)”에 따라 렌더링된 umbrella에 인코딩되어 나타납니다. 문자, 숫자, 밑줄, 그리고 도출 규칙이 유지하는 하이픈만으로 이루어진 식별자는 작성한 그대로 나타납니다.
file://리포지토리 포인터. umbrella의 의존성 항목은 하위 차트 자체의 디렉터리를 가리키는file://리포지토리 포인터를 사용합니다. component의 경우file://charts/<instance_id>이고, Feature가 가져오는 차트의 경우 해당 연결 자체의 디렉터리입니다. 이는 트리 내 하위 차트를 위한 로컬 파일 시스템 관례이며,helm dependency build가 외부 레지스트리 호출 없이 umbrella를 해석할 수 있게 합니다. 포인터는 위치를 가리킬 뿐 차트가 선언한 이름을 가리키지 않습니다. 연결의 경우 이 둘은 서로 다르며, 존재하지 않는 디렉터리를 가리키는 포인터를 거부하는 단계는helm dependency build입니다.- helm-chart 수준에서는 템플릿을 렌더링하지 않습니다. 이 provider는 Helm SDK의 렌더 파이프라인을 호출하지 않으며, 복사하고 구성할 뿐입니다. 미리 렌더링된 평면 매니페스트가 필요한 작성자는 대신 helm provider의 sourced 모드를 사용해야 합니다.
작업 예제
두 노드로 이루어진 경계이며, 각 노드는 같은 소스 차트를 가리키는 helm-chart Recipe에 바인딩됩니다:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}구성이 끝나면 경계의 평가된 어셈블리 경로(subDirectory:의 기본값이 {{ .capability }}이므로 기본값은 dist/<boundary-directory>/<capability>/)에는 다음이 포함됩니다:
dist/<boundary-directory>/helm-chart/├── Chart.yaml # umbrella; lists api-east and api-west as dependencies├── values.yaml # alias-keyed: api-east + api-west values blocks└── charts/ ├── api-east/ # ./charts/api-server, name: api-east │ ├── Chart.yaml │ ├── values.yaml │ └── templates/ │ └── deployment.yaml └── api-west/ # ./charts/api-server, name: api-west ├── Chart.yaml ├── values.yaml └── templates/ └── deployment.yaml두 하위 차트는 모두 하나의 소스 차트를 복사한 것이며, 각각 자신의 인스턴스 이름을 Chart.yaml에 담고 있습니다. 이것이 하나의 차트를 단일 엄브렐라 안에 두 번 벤더링할 수 있게 해 줍니다. 두 복사본의 나머지 내용은 모두 소스와 동일합니다.
이 레이아웃에 대해 helm install <release-name> dist/<boundary-directory>/helm-chart를 실행하면 두 인스턴스가 하나의 Helm 릴리스로 설치되며, 엄브렐라의 별칭 키 기반 값이 각 하위 차트의 템플릿을 구동합니다.
상호 참조
providers/helm.md— 차트 스캐폴드 대신 평탄하게 렌더링된 Kubernetes YAML을 출력하는 자매 provider이며, workload 합성을 수행합니다.entities/recipe.md— Recipe 작성 인터페이스와 세 가지 입력 종류.entities/release.md— Release 경계 의미론과 경계별 출력 디렉터리.architecture/16-recipe-input-composition.md— provider 전반의 Provider Capability Matrix(Provider 기능 매트릭스).10-status.md#providers— 현재 준비 상태 분류.