Helm Provider
helm 프로바이더는 GitOps 소비자(ArgoCD, Flux)를 위해 평면적으로 렌더링된 Kubernetes YAML을 생성합니다. 이 프로바이더는 (path, provider) 단위로 조립합니다. helm을 대상으로 하는 모든 노드의 렌더링된 YAML은 경계의 평가된 directory:와 컴포넌트별 subDirectory:를 결합한 값을 키로 하는 어셈블러로 라우팅되며, 이 어셈블러는 Kubernetes 리소스마다 YAML 파일 하나를 내보냅니다. 다운스트림 도구는 Helm 설치 단계 없이 이 파일들을 직접 비교하고 적용합니다.
경계의 syncWave: <integer>가 0이 아닌 경우, 내보내지는 각 Kubernetes 리소스는 그 값을 argocd.argoproj.io/sync-wave: "<N>" 어노테이션으로 가집니다. Helm 훅은 추가로 helm.sh/hook-weight: "<N>"를 가집니다. ArgoCD는 sync-wave 어노테이션을, Helm은 훅의 가중치를 읽고 각각 그에 따라 리소스 순서를 정합니다. 기본 웨이브 0인 경계는 둘 다 가지지 않으며, 두 도구 모두 이를 웨이브 0으로 읽습니다.
이 페이지는 helm 프로바이더의 작성 레퍼런스입니다. 프로바이더 전반의 입력 구성 모델은 architecture/16-recipe-input-composition.md를 참조하십시오. 각 프로바이더의 준비 상태는 언어의 상태 → Providers를 참조하십시오.
지원되는 입력 종류
helm provider는 세 가지 Recipe 입력 종류를 모두 받아들이며, 각각 다른 역할을 합니다.
- 소스 모드.
source: <chart-path>가 있는 Recipe는 디스크에 있는 Helm 차트 디렉터리를 가리킵니다. Helm Go SDK가 차트를 로드하고, 기본 렌더링 values 딕셔너리가 차트의 기본값과 병합되며, 차트의 템플릿이 평탄한 Kubernetes YAML로 렌더링됩니다. - Workload(합성) 모드.
workload:(인라인 또는$import:로 로드)가 있는 Recipe는 Workload 문서를 선언합니다. provider는 Workload 명세로부터 직접 노드마다 하나 이상의 Kubernetes 리소스, 즉 Workload의form에 따라 선택되는 컨트롤러 객체와 서비스별 Service, 영구 볼륨별 PVC를 합성합니다. Workload(합성) 모드를 참조하십시오. - 아티팩트 전용 모드.
artifacts:가 있고source:와workload:가 모두 없는 Recipe는 작성자가 작성한 매니페스트를 내보내며, 빌드의 출처 레이블과 어노테이션을 각 리소스 자체의 메타데이터에 삽입합니다.
세 가지는 함께 사용할 수 있습니다. Recipe는 차트, Workload, artifacts:를 함께 선언할 수 있으며, 각각은 노드의 출력에서 나란히 독립적으로 렌더링되고 내보내집니다. 각 provider가 받아들이는 것 전체를 참조하십시오.
source: 키 집합
helm provider의 source:는 차트를 지정하며, source: 필드가 취하는 두 가지 형태를 모두 받습니다. 하나는 파일 시스템 경로 문자열 그대로이고, 다른 하나는 url:에 위치를 담는 구조화된 객체입니다. 그 위치가 파일 시스템 경로인 경우, 경로는 빌드를 호출한 디렉터리가 아니라 그것을 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 반드시 그 디렉터리 안에 머물러야 합니다. 디렉터리 밖으로 올라가는 경로나 절대 경로는 거부됩니다. Recipe의 게시물이 담는 모든 파일은 그 디렉터리에서 가져오기 때문입니다. entities/recipe.md의 “Content paths stay inside the Recipe’s own directory”를 참고하십시오. 이렇게 지정된 차트는 Recipe와 함께 게시되며, 그 아래의 파일 중 Recipe를 고정할 때 기록된 무시 규칙이 유지하는 모든 파일이 포함됩니다. helm provider는 버전 관리 디렉터리와 차트의 templates/ 아래 숨김 파일을 제외하고, 차트 자체의 .helmignore를 따르며, 최종 결정은 작성자의 .aggregaignore가 내립니다. 이는 엔티티와 함께 배포되는 파일에서 설명합니다. 반면 Recipe 옆에 있더라도 Recipe가 선언하는 어떤 것도 지정하지 않는 파일은 포함되지 않습니다. 렌더링은 게시물이 담는 것과 같은 파일을 읽으므로, 차트는 로컬 디렉터리에서든 레지스트리에서든 동일하게 렌더링됩니다. 작성한 형태는 이를 바꾸지 않습니다. url:이 ./charts/api-server인 구조화된 source:는 문자열 ./charts/api-server와 정확히 같은 방식으로 기준이 정해집니다.
spec: capability: helm source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicas: {{ optional .infra `replicas` 2 }}구조화된 source:는 같은 내용을 이름 있는 필드로 표현하며, url:에 담긴 내용이 가져오기 여부를 결정합니다. url:에 전송 스킴이 있는 경우, 즉 OCI 차트의 oci://…, 직접 차트 아카이브의 https://….tgz, 또는 chart:와 짝을 이루는 https:// 저장소 루트인 경우 차트를 가져옵니다. 종류는 URL 스킴이나 명시적인 kind:에서 정해지고, aggrega pull이 차트를 가져와 lockfile에 고정하며, 빌드는 캐시에서 차트를 추출합니다. url:이 파일 시스템 경로를 지정하는 경우에는 아무것도 가져오거나 고정하지 않습니다. 차트는 디스크에서 읽으며, 위의 문자열 형태와 정확히 같은 방식으로 기준이 정해집니다.
spec: capability: helm source: kind: helm-oci-chart url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned version: "1.0.0"차트를 어디서 읽을지는 url:만 결정합니다. 다른 필드는 가져올 대상을 선택하므로 경로에 대해서는 아무것도 선택하지 않습니다. 다만 이 필드들은 여전히 .source.*로 Recipe 자체 템플릿에 전달됩니다.
차트를 로컬에 벤더링하는 것은 가져오기의 대안으로 지원되며, 필수는 아닙니다. 스키마는 열린 구조화 객체를 받습니다.
소스 경로의 차트에는 유효한 Chart.yaml이 있어야 합니다. 차트를 로드하지 못한 sourced 렌더는 기반 Helm SDK 오류를 그대로 표시합니다. 빈 source: ""는 helm 고유의 문제가 아닙니다. 이는 sourceless 모드도 sourced 모드도 지정하지 않으므로, 이에 따른 거부는 Recipe가 어떤 provider를 대상으로 하든 동일하며, Recipe를 읽는 시점, 즉 차트가 로드되기 전이자 이 provider가 디스패치되기 전에 발생합니다. 어떤 명령이 이를 보고하는지는 entities/recipe.md의 “Source field scheme inventory”와 errors/fatal-halts.md의 “Recipe source: is an empty string (Recipe의 source 필드가 빈 문자열임)”에 설명되어 있습니다.
소스 모드
source: <chart-path>와 valuesMapping:을 가진 Recipe는 기본 렌더링 시 다음 파이프라인을 실행합니다.
<chart-path>의 차트를 Helm Go SDK로 로드합니다.valuesMapping템플릿이 Recipe의 템플릿 컨텍스트에 대해 평가됩니다. 그 YAML 출력은 차트에 대한 values 오버레이로 취급됩니다.- 오버레이는 차트의
values.yaml기본값과 한 번 병합되며, 키가 충돌하면 오버레이 키가 우선합니다(Helm의 표준helm install --values의미론). 오버레이가null로 설정한 키는 최상위, 테이블 내부, 의존성의 values 어디에서든helm install --values와 마찬가지로 해당 키에 대한 차트의 기본값을 제거하므로, 차트의 템플릿은 그 키를 없는 것으로 읽습니다. 차트가 기본값을 주지 않는 키의null은 템플릿에null로 전달됩니다. - Helm SDK가 병합된 values에 대해 차트의 템플릿을 렌더링합니다.
- Aggrega는 렌더링 후 YAML 재작성을 통해 렌더링된 매니페스트에 출처 메타데이터를 주입하여, 소스 기반 출력이 Workload 모드 출력과 동일한 레이블을 갖도록 합니다. 식별 값은 레이블이 되며(
app.kubernetes.io/name,aggrega.ai/component-id,aggrega.ai/provider,aggrega.ai/provider-version,aggrega.ai/environment, 그리고 설정된 경우aggrega.ai/aggregate-name,aggrega.ai/compiler-version), 각각 Kubernetes가 레이블 값으로 허용하는 형식으로 작성됩니다. Kubernetes 레이블로 표현할 수 없는 값은 어노테이션이 됩니다(aggrega.ai/recipe-uri,aggrega.ai/boundary-path, 웨이브가0이 아닌 경우의aggrega.ai/sync-wave, 그리고 값을 다시 작성해야 했던 모든 레이블의 원래 값 — 예를 들어imported/flow라는 이름의 Aggregate는 같은 키 아래 레이블imported-flow와 어노테이션imported/flow를 받습니다). 재작성 규칙은 well-known-annotations.md의 “제공자가 내보내는 출처 레이블”에 명시되어 있습니다. - 출력 파일은 Recipe의 출력 디렉터리에 평평하게, 렌더링된 리소스마다 하나씩 놓이며 이름은
<name-basis>-<kind>[-<namespace>]-<name>.yaml입니다. 이는 아래의 릴리스 이름이 파생되는 것과 같은 기준에 리소스 자체의 kind, 네임스페이스가 있는 경우 네임스페이스, 그리고 이름을 붙인 것으로, 각각 소문자로 바꾸고 다른 문자가 연속된 부분은 하이픈 하나로 줄입니다. 일반 컴포넌트의 경우 그 기준은 컴포넌트 자신의 식별자이며, 이는 리소스의aggrega.ai/component-id레이블이 담는 값이기도 합니다. Feature 첨부의 작성자가 제공한 차트의 경우 기준은 호스트 컴포넌트의 것으로 유지되고, 레이블은 첨부 자신의 식별자를 담습니다. kind나 name이 없는 문서는 대신 템플릿 경로를 따라 이름이 붙습니다. 차트의 디렉터리 구조는 평탄화됩니다. 렌더링된 출력에는templates/하위 디렉터리가 없으며, 이름이 리소스에서 오고 템플릿에서 오지 않으므로 서로 다른 하위 디렉터리에서 파일명이 같은 두 템플릿도 두 개의 파일로 유지됩니다. Recipe의artifacts:블록이 지정하는 파일은 여기에 놓이지 않습니다. 그 파일은 한 단계 아래, 그것을 선언한 컴포넌트의 이름을 딴 디렉터리에 놓입니다. 그러한 파일은 담고 있는 리소스가 아니라 작성자가 쓴 키로 이름이 붙기 때문에, 그 디렉터리가 없으면 하나의 Recipe에 바인딩된 두 컴포넌트가 같은 경로에 쓰게 되고 어느 작성자도 이를 분리할 수 없기 때문입니다.
차트가 렌더링되는 네임스페이스는 경계에서 캐스케이드되는 aggrega.ai/namespace 어노테이션에서 읽혀 차트에 릴리스 네임스페이스로 전달됩니다. 어떤 경계도 이를 선언하지 않으면 차트는 default에 대해 렌더링됩니다. 경계가 네임스페이스를 선언한 경우, 차트가 네임스페이스 없이 렌더링하는 모든 네임스페이스 범위 리소스(metadata.namespace가 없거나 비어 있거나 null로 작성된 경우)는 선언된 네임스페이스에 출력됩니다. 이는 해당 릴리스 네임스페이스로 Helm을 사용해 차트를 설치할 때 그 리소스가 놓이는 곳이며, 그 파일은 템플릿이 해당 필드를 쓰는 리소스와 똑같이 네임스페이스 세그먼트를 포함한 이름을 갖습니다. 템플릿이 네임스페이스를 쓰는 리소스는 그것이 어떤 네임스페이스든 그대로 유지합니다. 클러스터 범위 리소스는 네임스페이스 없이 유지됩니다. kind가 네임스페이스 범위인지는 API가 직접 제공하는 kind의 경우 Kubernetes API 자체의 범위이고, 커스텀 kind의 경우 같은 렌더링에서 차트의 템플릿이나 crds/ 디렉터리에 있는 CustomResourceDefinition이 그 kind에 대해 선언하는 scope입니다. 이 둘 중 어느 것으로도 분류되지 않는 kind의 리소스는 차트가 작성한 그대로 두며, 빌드는 kind마다 한 번씩 kind와 그 API 그룹을 명시하여 이를 보고합니다. 항목이 배치되지 않는 kind: List 문서도 마찬가지입니다. 어떤 경계도 네임스페이스를 선언하지 않으면 아무것도 배치되지 않고 아무것도 보고되지 않습니다. 차트가 네임스페이스 없이 작성한 리소스는 네임스페이스 없이 출력되며, 적용하는 도구가 선택하는 곳에 배치됩니다.
이 보고는 빌드의 경고이며, 빌드는 그대로 완료됩니다.
warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them차트에 해당 kind의 CustomResourceDefinition을 렌더링하는 값이나 네임스페이스 자체를 쓰는 값이 있으면, Recipe의 valuesMapping으로 그 값을 설정하여 그러한 리소스를 배치할 수 있습니다.
차트를 렌더링하는 대상 Kubernetes 버전
차트의 템플릿은 렌더링 대상 Kubernetes 버전을 .Capabilities.KubeVersion으로 읽으며, 많은 차트가 이를 기준으로 API 버전, 필드 또는 메커니즘 전체를 선택합니다. 예를 들어 1.21 이상에서는 프로젝션된 서비스 계정 토큰을, 그 미만에서는 자체 토큰을 사용하는 식입니다. 빌드에는 질의할 클러스터가 없으므로, 버전은 Release가 component의 배포 위치를 지정하는 곳에서 직접 명시합니다. 바운더리에 aggrega.ai/kubernetes-version 어노테이션을 지정하거나, component에 지정하면 바운더리의 값보다 우선하며, aggrega.ai/namespace와 똑같이 하위로 전파됩니다.
spec: boundaries: production: annotations: aggrega.ai/kubernetes-version: "1.31" components: api: {} legacy: annotations: aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster이 값은 helm template --kube-version이 플래그를 읽는 방식으로 읽히므로, 해당 플래그가 받아들이는 형식을 받아들이고 차트는 그 플래그가 제공할 값과 정확히 같은 값을 읽습니다. "1.31"은 v1.31로, "v1.31.2"는 v1.31.2로 읽히며, 숫자 뒤의 텍스트는 .Capabilities.KubeVersion.Version에 작성된 그대로 남습니다. "1.29.3-gke.100"은 v1.29.3-gke.100으로 읽히지만, .Capabilities.KubeVersion을 통째로 출력하면 그 텍스트가 빠진 버전이 읽힙니다. semverCompare로 .Capabilities.KubeVersion.Version을 비교하는 차트는 이러한 접미사를 프리릴리스로 읽으므로, ">=1.21"처럼 -0 하한이 없는 제약 조건은 이와 일치하지 않습니다. 또한 앞뒤 공백이 포함된 값은 그 공백과 함께 읽혀 " 1.30 "이 "v 1.30 "으로 읽히고 그러한 비교에서 즉시 실패합니다. 차트가 버전을 비교하는 경우에는 공백 없는 버전만 작성하십시오. "one.two", "latest", 단일 숫자처럼 버전이 아닌 값은 플러그인이 표현할 수 없는 값에 대한 조건으로 빌드를 중단시키며, 값, component 및 해당 바운더리를 명시합니다. 차트가 대신 다른 버전으로 렌더링되는 일은 없습니다. A Kubernetes version the helm provider cannot render a chart for (helm provider가 차트를 렌더링할 수 없는 Kubernetes 버전)를 참조하십시오. 빈 값은 설정되지 않은 것으로 처리됩니다.
어떤 어노테이션도 버전을 지정하지 않으면, 차트는 동일한 helm 릴리스의 기본 helm template이 렌더링하는 버전, 즉 provider가 빌드될 때 사용된 Kubernetes 클라이언트 라이브러리의 버전으로 렌더링됩니다. 클라이언트 라이브러리 v0.37로 빌드된 provider는 Kubernetes v1.37.0으로 렌더링합니다. 따라서 Aggrega에서 차트는 차트 작성자의 helm template이 렌더링하는 것과 같이 렌더링되며, 기본값은 provider가 빌드되는 클라이언트 라이브러리가 바뀔 때만 바뀝니다. 배포 대상 클러스터의 버전이 이와 다르면 항상 그 버전을 지정하십시오. 클러스터가 실행하는 버전보다 최신 버전으로 렌더링된 차트는 해당 클러스터가 제공하지 않는 API 버전을 출력할 수 있습니다.
이 방식으로 설정되는 것은 버전뿐입니다. 차트가 읽는 다른 모든 기능 정보인 .Capabilities.APIVersions와 .Capabilities.HelmVersion은 helm 라이브러리에 내장된 값이므로, 클러스터가 설치된 CustomResourceDefinition을 통해 제공하는 API는 차트에 보고되지 않습니다. 차트의 Chart.yaml에 있는 자체 kubeVersion 범위는 버전과 비교되지 않습니다. helm template은 범위가 렌더링 대상 버전을 제외하는 차트를 거부하지만, 빌드는 이를 렌더링합니다. 이 어노테이션은 소스에서 렌더링되는 차트에만 영향을 미칩니다. 합성된 Workload와 artifacts: 본문은 .Capabilities를 읽지 않으며, helm-chart provider는 차트를 렌더링하지 않은 채 전달하여 설치될 때 렌더링되도록 합니다.
렌더링된 문서 제외하기. 이 provider는 Recipe 또는 FeatureRecipe가 선언한 omits: 항목을 이 모드에서만 따르며, 다른 모드에서는 따르지 않습니다. 합성된 Workload와 artifacts: 본문은 이 항목 없이 렌더링됩니다. 차트가 렌더링하는 모든 문서는 템플릿에서 왔든 crds/ 디렉터리의 파일에서 왔든 빌드에 적용되는 각 항목과 대조되며, 어느 항목이든 지정한 문서는 제외됩니다. 항목은 문서 자체가 지닌 값, 즉 출력 파일 이름과 렌더 팩트를 구성하는 값과 동일한 값으로 문서를 지정합니다. 이는 kind, metadata.name, 그리고 항목이 지정하는 경우에만 문서가 속한 네임스페이스로, 템플릿이 작성한 네임스페이스이거나 이 provider가 위에서 설명한 대로 문서를 배치하는 경우 바운더리가 선언한 네임스페이스입니다. 차트가 단지 렌더링 기준으로 삼는 네임스페이스는 결코 해당되지 않습니다. 네임스페이스가 선언되지 않으면 차트는 default를 기준으로 렌더링되지만, 템플릿이 네임스페이스를 작성하지 않은 문서는 어떤 네임스페이스에도 속하지 않으므로 default를 지정하는 항목은 이와 일치하지 않습니다. kind나 name이 없는 문서는 어떤 항목과도 일치하지 않습니다. 제외되는 문서는 렌더링된 후 모든 파일의 이름이 확정되면 삭제되므로, 유지되는 각 문서는 항목이 없을 때와 정확히 같은 이름으로 작성되며, 제외된 문서는 빌드가 이후에 수행하는 어떤 작업에도 도달하지 않습니다. 파일도, 두 기여자가 하나의 경로에 도달하는 것을 거부하는 비교 속의 이름도, Feature가 읽는 렌더 팩트도, 파이프라인 단계에 전달되는 어떤 것도 없습니다. provider는 각 항목이 일치한 문서 수를 보고하며, 아무것도 일치하지 않은 항목은 빌드를 중단시킵니다. An omits entry left out nothing the source rendered (omits 항목이 소스가 렌더링한 것을 아무것도 제외하지 않음)를 참조하십시오.
차트가 렌더링되는 Helm 릴리스
이 provider는 Helm 4 SDK v4.3으로 렌더링하므로, 차트는 Helm 4 자체의 helm template이 제공하는 것을 읽으며 같은 차트와 값은 모든 빌드에서 같은 바이트로 렌더링됩니다. Helm 3을 기준으로 작성하고 검증한 차트에서는 다음과 같은 Helm 4 동작이 나타날 수 있습니다.
- **
.Capabilities.HelmVersion**은 Helm 4의 버전인v4.3을 보고합니다. - 기본 Kubernetes 버전은 v1.37.0입니다. v4.3의 Helm 4가 클라이언트 라이브러리 v0.37을 기준으로 빌드되기 때문이며,
.Capabilities.APIVersions는 그 클라이언트 라이브러리의 API 버전 집합입니다. 차트가 렌더링되는 Kubernetes 버전에서 설명하는 대로 클러스터가 실행하는 버전을 지정하십시오. null인 차트 기본값은 제거됩니다. 차트의values.yaml이 최상위 수준 또는 테이블 안에서null로 설정한 키는 Recipe가 제공하는 값이 설정하지 않는 한.Values에 없습니다. 따라서hasKey는 해당 키가 없다고 보고하고,toYaml은 이를 생략하며, 차트의values.schema.json은 그 키가 없는 값을 기준으로 검사됩니다.- 블록 스칼라는
---앞의 마지막 줄바꿈을 유지합니다. 블록 스칼라로 끝나고 같은 템플릿의 다른 문서가 뒤따르는 문서는 그 스칼라의 마지막 줄바꿈을 유지하므로|-가 아니라|로 작성됩니다. .Chart는 필드 이름을 키로 하는 맵입니다..Chart.Name,.Chart.Version,.Chart.AppVersion및 기타 필드는 이전과 같이 읽히지만,toYaml .Chart나toJson .Chart.Maintainers는 키를Name,AppVersion등으로 출력하고 빈 필드도 포함합니다. 차트 메타데이터에 없는 필드는 렌더링을 실패시키지 않고 빈 값으로 읽힙니다..Capabilities.KubeVersion.Version은 버전의 텍스트를 작성된 그대로 유지합니다. 이는 위에서aggrega.ai/kubernetes-version어노테이션에 대해 설명한 것과 같습니다.- **여러 YAML 문서를 담은
values.yaml**은 전체가 읽히며, 뒤의 문서가 앞의 문서 위에 병합됩니다. - **빈 파일의
.Files.Lines**는 렌더링을 실패시키지 않고 아무 줄도 반환하지 않습니다. - Helm 4에서 추가된 템플릿 함수인
mustToYaml,mustToJson,mustToToml,mustToDuration및duration…변환을 차트 템플릿에서 사용할 수 있습니다. - 두 번 별칭이 지정된 의존성은 각 별칭에 그 의존성 자체의 의존성 사본을 별도로 제공합니다.
- 값 스키마 검증은 경계 사례에서만 다르게 수락하거나 거부합니다. 따옴표로 묶인 이메일 로컬 파트,
NaN과 무한대 숫자,enum과const에서 숫자와 숫자가 아닌 값의 비교, 그리고 실패한propertyNames,contentSchema또는 뒤쪽 배열 항목에 대해 보고되는 위치가 이에 해당합니다.
엔진 자체가 실행하지 못한 템플릿(예를 들어 존재하지 않는 테이블을 통해 읽은 값)은 Helm 4의 형식으로 보고됩니다. 템플릿의 파일, 줄, 열이 별도의 줄에 표시되고, 그다음 실패가 거쳐 간 각 템플릿에 대해 실행 중이던 내용과 메시지가 들여쓰기되어 표시됩니다. 차트 자체의 fail이나 required는 한 줄짜리 execution error at (<file>:<line>:<col>): <message> 형식을 유지하며, 템플릿 함수가 반환하는 오류도 마찬가지입니다.
릴리스 이름이 도출되는 방식
소스 차트는 릴리스 이름을 기준으로 렌더링되며, 이 이름은 모든 템플릿에 .Release.Name으로 전달됩니다. 차트는 흔히 리소스 이름을 이 이름에 따라 짓기 때문에, 릴리스 이름은 빌드에 붙는 레이블이 아니라 클러스터 안에서의 식별자입니다.
릴리스 이름은 렌더링된 리소스의 출력 파일 이름 앞에 붙는 것과 동일한 기준을 인코딩한 형태이므로, 두 이름은 같은 이름을 두 번 쓴 것입니다. 그 기준은 일반 컴포넌트의 경우 instance_id이고, **경계(boundary)**에 연결된 Feature의 경우 그 Feature가 지닌 합성된 식별자입니다. Feature 연결의 작성자가 제공한 차트의 경우에는 호스트 컴포넌트의 이름입니다. 차트 자체의 템플릿은 릴리스 이름을 기준으로 렌더링되므로, 이를 연결에서 도출하면 이미 리소스가 배포된 클러스터에서 차트가 선언한 리소스의 이름이 바뀌게 됩니다. 그 리소스들은 여전히 aggrega.ai/component-id 레이블에 연결 자체의 식별자를 지닙니다. 여기서 리소스의 이름과 리소스의 소속은 별개의 문제이며, 일반 컴포넌트에서만 두 답이 같습니다. Helm 릴리스 이름은 식별자가 지닐 수 있는 것보다 좁은 범위의 문자만 허용합니다. 즉 소문자, 숫자, 하이픈, 점으로 구성되고, 소문자나 숫자로 시작하고 끝나며, 최대 53자입니다. 도출 과정은 대상이 허용하지 않는 문자를 다른 문자로 대체하는 대신 풀어 쓰므로, 구두점이나 대소문자만 다른 두 컴포넌트 식별자는 항상 서로 다른 두 릴리스 이름이 됩니다.
- 소문자와 숫자는 작성된 그대로 유지됩니다.
- 하이픈은 그 뒤의 문자가 그대로 전달되고 소문자
z가 아닌 경우 작성된 그대로 유지됩니다. 소문자z가 뒤따르는 하이픈은 이스케이프를 시작하므로, 그 위치에 작성된 하이픈은 그 자체가 풀어서 기록됩니다.api-zone은api-zhzone이 되며, 덕분에 어떤 이름이든 추측 없이 다시 읽어 낼 수 있습니다. 뒤에 아무것도 없는 하이픈도 같은 이유로 풀어서 기록되므로db-는db-zh가 됩니다. - 그 밖의 모든 문자는
-z뒤에 그 문자를 나타내는 글자를 붙여 씁니다. 점은d, 밑줄은u, 경로 구분자는s, 위 규칙이 유지하지 않는 하이픈은h입니다. 그 외의 문자는 대문자를 포함하여x와 해당 문자의 여섯 자리 16진수 코드 포인트로 쓰고, 어떤 문자의 시작도 아닌 바이트는b와 그 바이트 자체의 두 자리 값으로 씁니다. - 빈 값은
-ze로 기록되며, 비어 있지 않은 값은 이를 만들어 낼 수 없습니다.
Helm은 릴리스 이름에 점을 허용하지만, 점은 그대로 유지되지 않고 풀어 쓰입니다. Helm은 점의 양쪽에 소문자나 숫자를 요구하는데, 도출 과정이 자체적으로 하이픈을 배치하기 때문입니다.
한 컴포넌트에 연결된 두 Features는 모두 그 컴포넌트의 릴리스 이름을 기준으로 렌더링되므로, 각각 .Release.Name에 따라 리소스 이름을 짓는 두 차트는 같은 이름의 리소스 두 개를 내보냅니다. 이 프로바이더는 자체 렌더링이 생성하는 모든 리소스의 이름을 해당 리소스의 kind로, 그리고 클러스터가 네임스페이스 안에 두는 kind라면 그 네임스페이스로 범위를 한정하여 보고합니다. 빌드는 두 기여자가 그중 하나에 겹치면, 둘 다 적용했을 때 마지막 것만 남는 출력을 내보내는 대신 거부합니다. ../errors/fatal-halts.md의 “The same name is derived more than once inside the output(출력 안에서 같은 이름이 두 번 이상 도출됨)”을 참조하십시오. 클러스터가 모든 네임스페이스 밖에 두는 kind, 즉 ClusterRole, CustomResourceDefinition, 또는 같은 렌더링의 CustomResourceDefinition이 범위 Cluster로 선언하는 사용자 정의 kind는 kind만으로 범위가 한정되며, 위의 네임스페이스 배치가 분류하는 방식 그대로 분류됩니다. 따라서 한 출력의 두 컴포넌트가 각각 같은 이름으로 그러한 객체를 하나씩 쓰면, Release가 이들을 서로 다른 네임스페이스에 배치하더라도 거부됩니다. 해결 방법은 이름을 합성하는 것이며, 어떤 좌표가 필요한지는 배치에 따라 다릅니다. 한 컴포넌트의 두 연결은 이미 호스트를 공유하므로, 템플릿에 전달되어야 하는 것은 연결입니다. FeatureRecipe의 valuesMapping:을 통해 .attachment_name을 차트에 전달하고, 차트의 리소스 이름을 구성하는 차트 자체의 값에 설정하십시오. 두 컴포넌트에 연결된 하나의 차트는 그 반대입니다. 릴리스 이름은 이미 호스트마다 다르므로, .Release.Name에 따라 이름 지은 리소스는 각 호스트에서 고유한 이름을 지니지만 리터럴 이름은 그렇지 않습니다. artifacts:를 통해 리소스를 전달하는 FeatureRecipe도 같은 조건으로 보고됩니다. 이 프로바이더는 내보낸 각 문서가 지닌 이름을 그 문서가 차트 템플릿에서 왔는지 artifacts 본문에서 왔는지와 관계없이 읽으므로, 두 컴포넌트에 연결된 그러한 본문의 리터럴 이름도 중단됩니다. artifacts 본문은 템플릿이므로, 호스트마다 달라야 하는 경우 .context.rendered_name(호스트마다 다르고 Kubernetes 이름이 허용하는 문자로 쓰인 호스트의 릴리스 이름)과 .attachment_name으로 이름을 합성하십시오. 아티팩트 세트만 배치하여 릴리스 이름을 보고하지 않는 호스트에서는 대신 .context.instance_id로 합성하십시오. 모든 이름이 보고되는 것은 아니므로, 중단되지 않은 빌드가 출력이 결국 지니게 될 모든 것을 비교한 것은 아닙니다. 차트를 작성하면서 가장 마주치기 쉬운 경우는 generateName을 선언하는 리소스로, 이는 클러스터가 완성하도록 남겨지므로 아직 비교할 것이 없습니다. 전체 목록은 위에 링크된 페이지에 있습니다.
따라서 instance_id가 api이면 릴리스 이름은 api, data.main-db이면 data-zdmain-db, db_host이면 db-zuhost가 됩니다. 소문자, 숫자, 그리고 도출 과정이 유지하는 하이픈만으로 구성된 식별자는 작성된 그대로 나타납니다. 동일한 입력은 항상 동일한 이름을 생성합니다.
Helm의 조건 중 두 가지는 도출 과정이 아니라 기준의 속성입니다. 릴리스 이름은 소문자나 숫자로 시작해야 하고, 최대 53자여야 합니다. 첫 문자가 풀어 쓰이는 기준은 모든 이스케이프가 시작하는 하이픈으로 이름이 시작되고, 풀어 쓰이는 문자를 지닌 기준은 작성된 것보다 길게 인코딩됩니다. 빌드는 이 프로바이더에 두 가지를 모두 질의하고, 그 답에 따라 빌드 시점에 조치합니다. 적용 시점에 클러스터가 거부하도록 남겨 두지 않습니다. ../errors/fatal-halts.md의 “The target will not accept a name derived from an authored identity(대상이 작성된 식별자에서 도출된 이름을 허용하지 않음)”을 참조하십시오. 답에 따른 조치는 기준을 누가 작성했는지에 따라 다릅니다. 직접 작성한 이름은 변경되지 않고 거부되며, 거부 메시지는 작성한 필드와 허용 범위를 알려 줍니다. Aggrega가 합성한 이름은 이 프로바이더가 허용할 때까지 줄여집니다.
클러스터는 컴포넌트에 따라 이름 지어진 리소스에 Helm보다 엄격한 규칙 하나를 적용합니다. Service 이름은 문자로 시작해야 하지만 릴리스 이름은 숫자로 시작할 수 있습니다. 차트는 흔히 Service 이름을 릴리스 이름에 따라 짓고, 합성된 워크로드의 Service도 릴리스 이름으로 시작하므로, 이 프로바이더는 숫자로 시작하는 컴포넌트 이름도 거부하며 이를 대상이 사용할 수 없는 Service name으로 보고합니다. 길이로는 첫 문자를 바로잡을 수 없으므로 이 거부는 길이를 명시하지 않습니다. 따라서 instance_id는 소문자로 시작하고, 인코딩된 형태가 여전히 들어맞을 만큼 짧게 유지하십시오.
릴리스 이름이 도출되는 기준을 변경하면, 차트가 .Release.Name에 따라 이름 지은 클러스터 리소스와 이 프로바이더가 해당 컴포넌트에 대해 합성하는 모든 리소스의 이름이 바뀌며, Kubernetes는 리소스의 이름을 제자리에서 바꾸지 않습니다. 적용 도구는 새 이름으로 리소스를 생성하고 이전 이름의 리소스를 제거하므로, 상태 저장 리소스의 경우 이전 이름에 바인딩된 스토리지가 해제됩니다. 이러한 변경은 롤아웃할 업데이트가 아니라 드레인, 마이그레이션 또는 일정 수립 등으로 계획해야 하는 교체로 취급하십시오.
Workload(합성) 모드
workload:(인라인 또는 $import:로 로드)가 있는 Recipe는 Workload의 추상적 의도로부터 Kubernetes 리소스를 합성합니다. Workload 스키마는 entities/workload.md에 설명되어 있으며, 이 섹션은 helm provider가 내보내는 내용을 다룹니다.
각 노드마다:
- Workload의
form에 따라 선택되는 컨트롤러 객체 하나:stateless(및 기본값)는 Deployment를,stateful은 StatefulSet을,daemon은 DaemonSet을,task는 Job을,scheduled는spec.schedule이 Workload의schedule필드(5필드 cron 표현식 또는@매크로)인 CronJob을 내보냅니다. 스케줄이 없거나 잘못된 스케줄을 가진scheduled워크로드는 명시적으로 중단됩니다.suspend: true를 선언한scheduled워크로드는spec.suspend: true가 있는 CronJob을 내보내므로, 재개될 때까지 스케줄에 따른 실행은 시작되지 않지만 CronJob에서 수동으로 Job을 만드는 것은 여전히 가능합니다. 이를 선언하지 않은 워크로드는suspend키를 전혀 내보내지 않습니다. Deployment와 StatefulSet은 레플리카 수를 가지며, DaemonSet, Job, CronJob은 가지지 않습니다.statefulWorkload는 StatefulSet을 관리하기 위해 Workload에 선언된type: HeadlessService가 정확히 하나 필요합니다. provider는 StatefulSet의serviceName을 해당 Service의 렌더링된 이름에 연결하며, headless Service가 선언되지 않았거나 둘 이상 선언된 경우 빌드가 중단됩니다.persistentTemplate볼륨은form: stateful의 동반 요소이며, 다른 form에 선언하면 해결 방법을 명시하는 메시지와 함께 중단됩니다. - Workload에 선언된
services:항목마다 Service 하나가 생성되며, 서비스 명세가 나열하는 이름 있는 포트를 노출합니다. 항목의type은 Service의 타입이 됩니다.ClusterIP,NodePort,LoadBalancer는 그대로,Headless는clusterIP: None을 가진ClusterIPService가 됩니다.Loopback항목은 대신 노드와 서비스를 명시하며 빌드를 중단합니다. Kubernetes Service에는 호스트의 루프백 주소에 바인딩하는 타입이 없고,NodePortService가 어떤 노드 주소에서 수신 대기하는지는 클러스터 전체의 설정이므로, 요청하지 않은 도달 범위로 렌더링하는 대신 해당 항목을 거부합니다. A service type the helm provider cannot render (helm provider가 렌더링할 수 없는 서비스 타입)를 참조하십시오. persistent볼륨마다 PersistentVolumeClaim 하나가 생성되며, 볼륨 명세에 따라 크기와 형태가 정해집니다.persistentTemplate볼륨은 독립된 클레임을 내보내지 않고 StatefulSet 자체 명세 안의volumeClaimTemplates항목이 됩니다. 이것이form: stateful의 동반 요소인 이유입니다.
리소스 이름. 이 모드가 컴포넌트에 대해 내보내는 모든 리소스는 컴포넌트의 release 이름을 따라 이름이 지어집니다. 이는 sourced 차트가 렌더링 기준으로 삼는 것과 같은 이름으로, How the release name is derived에서 설명한 대로 도출되며, provider는 이 이름을 {{ .context.rendered_name }}으로 빌드에 보고합니다. 컨트롤러 객체는 release 이름 자체를 가지고, 각 Service는 <release name>-<service key>, 각 독립 클레임은 <release name>-<volume>이며 파드의 볼륨은 정확히 그 클레임을 참조합니다. 파일로 전달되는 시크릿은 <release name>-secret-<slot>이라는 파드 볼륨에서 마운트되며, 슬롯은 release 이름과 마찬가지로 클러스터가 허용하는 문자로 쓰입니다. 따라서 슬롯 server_certificate는 <release name>-secret-server-zucertificate에서 마운트되고, 연결을 통해 읽는 슬롯은 연결 이름 뒤의 점이 같은 방식으로 쓰입니다. StatefulSet의 serviceName은 그것이 내보내는 headless Service의 이름이며, 외부 이름으로만 노출되는 Workload는 release 이름을 가진 Service 하나를 내보냅니다. 따라서 컴포넌트 api는 Deployment api와 default Service api-default를 내보내고, 컴포넌트 my_api는 my-zuapi와 my-zuapi-default를 내보냅니다. 작성된 그대로의 식별자로는 클러스터가 받아들이지 않을 곳에서 받아들이는 이름입니다. 이러한 Service 중 하나의 주소를 게시하는 Recipe는 ../templates/rendered-resource-names.md에서 보여 주듯 {{ .context.rendered_name }}으로 주소를 구성합니다. 이름에 밑줄과 대문자가 없는 컴포넌트는 release 이름이 instance_id와 같으므로, 이름이 식별자와 정확히 같게 읽힙니다. Feature 첨부가 합성하는 워크로드는 유일한 예외입니다. 이 워크로드는 첨부 자체의 합성된 식별자, 즉 aggrega.ai/component-id 레이블이 가지는 값을 따라 이름이 지어집니다. 첨부는 호스트 컴포넌트를 기준으로 렌더링되므로, 거기서 도출된 release 이름은 첨부의 워크로드를 호스트의 이름으로 짓게 되어 호스트 자체의 워크로드와 충돌하기 때문입니다. 그 식별자에는 대문자가 결코 포함되지 않습니다. 호스트 이름이나 첨부 이름의 대문자는 리소스 이름이 거부하는 다른 모든 문자와 마찬가지로 이스케이프로 쓰이므로, 컴포넌트 myApi의 첨부 worker는 Deployment cfr--my-zx000041pi--worker와 default Service cfr--my-zx000041pi--worker-default를 내보내며, 워크로드가 가지는 각 이름은 모두 클러스터가 받아들이는 이름입니다.
Workload에 따라 달라지는 이름 길이. 이 이름들 중 두 가지는 클러스터가 각각 고유한 한도를 적용하며, 빌드는 거부를 적용 시점의 클러스터에 맡기지 않고 Workload가 해석되면 두 가지를 모두 검사합니다. CronJob 이름은 최대 52자입니다. 컨트롤러가 각 실행의 Job 이름을 CronJob 이름에 접미사를 붙여 정하므로 클러스터의 다른 이름보다 짧습니다. 이는 scheduled Workload에 대해서만 검사됩니다. 각 Service 이름 <release name>-<service key>는 최대 63자입니다. 어느 한도든 넘으면, 릴리스 이름의 경우와 똑같이 이름을 누가 작성했는지에 따라 결과가 달라집니다. 직접 작성한 컴포넌트 이름은 거부되며, 빌드는 직접 작성한 spec.components 키에서 이름의 종류, 길이, 이름에 허용된 길이 예산과 함께 중단됩니다. ../errors/fatal-halts.md의 “The target will not accept a name derived from an authored identity (대상은 작성된 식별자에서 도출된 이름을 허용하지 않음)”를 참조하십시오. Feature 부착의 워크로드 이름의 기반이 되는 식별자처럼 조합된 식별자는 모든 이름이 맞을 때까지 줄어듭니다. Service 이름은 직접 작성한 컴포넌트 이름과 워크로드가 (Recipe 또는 FeatureRecipe에서) 선언하는 키로 구성되므로, 거부는 그 키와 워크로드가 그 키를 선언한 위치인 spec.workload.services.<key>를 명시합니다. 어떤 컴포넌트 이름도 들어갈 여유를 남기지 않는 키는 키 자체를 줄여야 합니다. 따라서 scheduled Workload를 가진 컴포넌트는 인코딩된 이름이 최대 52자일 수 있고, 컴포넌트 web은 최대 59자의 Service 키를 가질 수 있습니다. 경계 전체에 부착된 Feature는 출력이 어디에서 어셈블되는지가 그 식별자에 따라 달라질 수 있으므로 Workload가 해석되기 전에 식별자가 확정되며, 따라서 그것이 합성하는 리소스에 대해서는 두 한도 모두 검사되지 않습니다.
내보낸 각 리소스는 Aggrega의 전체 출처 레이블과 어노테이션, 그리고 Deployment/StatefulSet과 그 Service 사이에 연결되는 셀렉터 쌍(app: <instance_id>)을 가집니다. 레이블 값은 작성된 그대로의 식별자를 허용하므로, 위의 이름들이 release 이름을 사용하는 반면 셀렉터는 식별자를 그대로 유지합니다. 렌더링된 Deployment의 컨테이너 이름은 Workload의 컨테이너 키에서 .과 _ 문자를 -로 바꾼 것입니다(Kubernetes 이름 정제).
포트 전송 프로토콜. 전송 프로토콜을 선언한 컨테이너 포트는 렌더링된 containerPort에 이를 protocol:로 그대로 내보내며, 해당 컨테이너 포트를 지정하는 모든 Service 포트도 같은 값을 가집니다. 전송 프로토콜은 컨테이너 포트에서 한 번만 선언되므로 노출이 이와 어긋날 수 없습니다. 전송 프로토콜을 선언하지 않은 포트는 어느 리소스에도 protocol 키를 내보내지 않으며, 클러스터의 기본값이 적용됩니다. Workload가 허용하는 세 값(TCP, UDP, SCTP)은 모두 그대로 내보내집니다. Kubernetes가 각각을 직접 표현하므로 helm에서는 기능 축소가 필요 없습니다.
노드의 네트워크에서 실행. hostNetwork: true를 선언한 Workload는 렌더링된 파드 명세에 hostNetwork: true를 내보내므로, 파드는 노드 자체의 네트워크 네임스페이스에서 실행되고 컨테이너가 여는 포트는 노드의 주소에서 도달할 수 있습니다. Kubernetes가 이 선택을 직접 표현하므로 축소되는 것은 없습니다. 이 선언은 파드 명세에만 반영됩니다. 포트를 추가, 제거, 재작성하지 않으며, 내보내는 Service는 선언 유무와 관계없이 동일합니다. 이를 선언하지 않은 Workload는 hostNetwork 키를 전혀 내보내지 않습니다.
리소스 수량. provider가 매니페스트에 복사하는 모든 수량은 그대로 내보내지며, 각각은 먼저 Workload → Resource quantities에 설명된 수량 형식에 대해 검사됩니다. 대상은 각 컨테이너와 init 컨테이너의 resources.requests 및 resources.limits 값(cpu, memory 그리고 nvidia.com/gpu 같은 모든 확장 리소스)과 각 볼륨의 ephemeral.sizeLimit, persistent.size, persistentTemplate.size입니다. 검사는 Recipe의 템플릿이 평가한 Workload에 대해 실행되므로, infra나 Release 파라미터를 통해 들어온 값은 렌더링된 결과로 판단됩니다. 형식을 벗어난 값은 노드, Workload 내 필드 경로, 값을 명시하는 TRANSLATION_ERROR로 빌드를 중단합니다. 예를 들어 containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number와 같습니다. 그렇지 않으면 차트는 문제없이 빌드되고 설치 시 클러스터에서 거부될 것입니다. 비어 있는 cpu, memory, sizeLimit는 매니페스트에서 생략되므로 검사되지 않습니다. 비어 있는 확장 리소스 값이나 영구 크기는 여전히 내보내지므로 거부됩니다. 검사는 형식만 판단합니다. 클러스터가 그 양을 스케줄링할 수 있는지는 provider가 빌드 시점에 알 수 없습니다.
출력 파일 이름은 두 가지 형태입니다. 컨트롤러 객체는 release 이름과 종류를 따라 이름이 지어집니다: <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. 리소스별 파일은 담고 있는 리소스를 따라 종류를 마지막에 두어 이름이 지어집니다: <release name>-<svcName>-service.yaml 및 <release name>-<volName>-pvc.yaml이며, 각각 entities/workload.md의 합성 이름 관례에 따라 해당 리소스 자체의 metadata.name에서 가져옵니다. 외부 이름으로만 노출되는 Workload는 담을 서비스 키가 없으므로 <release name>-service.yaml을 내보냅니다.
렌더 팩트
이 provider는 렌더링하는 파일과 함께 모든 노드에 대해 네 가지 렌더 팩트를 보고합니다. 즉, 출력한 Kubernetes 문서가 그 파드, 셀렉터, 포트, 그리고 각 문서가 출력된 네임스페이스에 대해 말하는 내용입니다. 컴포넌트에 연결된 FeatureRecipe는 .context.render_facts에서 컴포넌트 자신의 팩트를 읽습니다. readsCallerRenderFacts: true를 설정한 FeatureRecipe는 .context.used_by의 각 항목에서 호스트에 연결하는 컴포넌트의 팩트도 읽고, readsTargetRenderFacts: true를 설정한 FeatureRecipe는 .context.uses의 각 항목에서 호스트가 연결된 컴포넌트의 팩트를 읽습니다. 이렇게 해서 Feature는 호스트를 호출하는 컴포넌트나 호스트가 도달하는 컴포넌트의 파드를, 누구도 레이블을 손으로 다시 적지 않고 그 렌더가 실제로 출력한 내용으로부터 지정할 수 있습니다. 예를 들어 정확히 그 파드만 허용하는 네트워크 정책이 그렇습니다. 아래의 이름과 항목은 이 provider의 계약입니다.
| 팩트 | 항목 하나의 단위 | 각 항목의 내용 |
|---|---|---|
pod_template_labels | 출력된 파드 템플릿: Deployment, StatefulSet, DaemonSet, ReplicaSet 또는 Job의 spec.template, CronJob의 job 템플릿, 그리고 그 자체가 템플릿인 단독 Pod | 템플릿을 가진 리소스의 kind, name, namespace; 템플릿의 레이블인 labels |
controller_selectors | 출력된 Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, CronJob | kind, name, namespace; 셀렉터의 matchLabels인 match_labels |
service_selectors | 출력된 Service | name, namespace; 트래픽을 보내는 대상 레이블인 selector |
container_ports | ports 목록을 선언한 파드 템플릿의 컨테이너(init 컨테이너 포함) | 템플릿을 가진 리소스의 kind, name, namespace; 컨테이너 이름인 container; 포트마다 name, container_port, protocol을 가진 항목 하나씩인 ports |
팩트를 읽는 방법:
- 모든 팩트는 목록입니다. 템플릿은 항목이 하나뿐이라도 항상 팩트를 range로 순회합니다. 따로 읽을 단일 값은 없습니다.
- 모든 렌더에서 네 가지 모두. 이 provider가 노드를 렌더링할 때마다 각 팩트가 보고되며, 렌더가 해당하는 것을 아무것도 출력하지 않았으면 빈 목록으로 보고됩니다. ConfigMap만 출력하는 차트를 가진 컴포넌트는 빈 목록 네 개를 보고합니다. 다른 provider의 렌더는 이 이름들을 보고하지 않으며, 아무도 보고하지 않은 이름은 아무것도 아닌 것으로 읽힙니다.
- 모든 경로에서, 출력된 것으로부터 읽습니다. 팩트는 어떤 모드가 생성했든 렌더가 출력한 문서에서 나옵니다. 차트의 렌더링된 매니페스트, 합성된 Workload의 매니페스트, 그리고 작성자가
artifacts:로 배치한 매니페스트가 그 대상이며, 마지막 경우에는 그 매니페스트가 담은 그대로를 보고합니다. 팩트는 이 provider가 빌드의 중복 이름 검사를 위해 보고하는 리소스 이름과 같은 패스에서 같은 문서를 대상으로 읽힙니다. 리소스 자신의 출처 레이블도 그 리소스가 담은 내용의 일부이므로 단독 Pod의labels에는 이 레이블이 포함됩니다. 차트나 아티팩트의 파드 템플릿은 작성자가 쓴 레이블을 그대로 유지합니다. - 항목은 컴포넌트 자신의 렌더와 그 Features의 렌더에서 올 수 있습니다. 하나의 컴포넌트가 둘 이상의 호출로 렌더링될 수 있으며(예: 차트와
artifacts:배치), 한 이름이 그 호출들에서 얻는 목록은 호출이 실행된 순서대로 하나로 합쳐집니다..context.used_by와.context.uses에서는 연결의 반대쪽 끝에 있는 컴포넌트의 팩트에, 그 컴포넌트 자신의 것 뒤로 그것에 연결된 Features가 렌더링한 내용도 합쳐집니다..context.render_facts는 컴포넌트 자신의 렌더만 담습니다. - 출력된 순서대로. 항목은 렌더가 리소스를 출력한 순서를 따릅니다. 레이블 맵은 컨텍스트의 다른 모든 맵과 마찬가지로 키 맵이므로, 이를 순회하는 템플릿은 키 순서로 키를 만납니다.
- 문서가 생략한 것은 항목도 생략합니다.
generateName으로 이름이 지정된 리소스에는name이 없습니다.metadata.namespace를 쓰지 않은 리소스에는namespace가 없으며, 이를 비어 있거나 null로 쓴 리소스도 마찬가지로 네임스페이스를 지정하지 않으므로 없습니다.matchLabels없이 작성된 컨트롤러(클러스터가 생성하는 셀렉터에 의존하는 Job)에는match_labels가 없습니다. 셀렉터가 없는 Service에는selector가 없습니다. 이름이나 프로토콜이 없는 포트에는 둘 다 없습니다. 그 밖에 비어 있게 쓴 부분은 비어 있는 것으로 보고됩니다.protocol은 문서가 쓴 경우에만 보고되므로, 이것이 필요한 템플릿은 클러스터 자체의 기본값인TCP를 직접 씁니다.container_port는 문서가 쓴 곳에서는 항상 숫자입니다. namespace는 문서가 쓴 것이며, 추측이 아닙니다. 이는 리소스 자신의metadata.namespace입니다. 파드 템플릿의 경우 그것을 가진 리소스의 값이며, 이곳이 그 파드가 실행되는 위치입니다. 파드 템플릿 안에 쓴 네임스페이스는 읽지 않습니다. 합성된 Workload는 경계가 선언한 네임스페이스를 출력하는 모든 리소스에 쓰므로, 그 항목은 그 네임스페이스를 담습니다. 차트의 항목은 출력된 문서가 쓴 것을 담습니다. 경계가 네임스페이스를 선언한 경우에는 그 네임스페이스를 담는데, 차트의 템플릿이 이를 투영하든 provider가 리소스를 거기에 배치하든 마찬가지입니다(Sourced mode 참조). 단, 템플릿이 자체 네임스페이스를 고정하면 항목은 대신 그것을 담습니다. 선언된 것이 없으면 템플릿이 투영하는 곳에서는 릴리스 네임스페이스인default를, 아무것도 쓰지 않는 곳에서는 아무것도 담지 않습니다. 아무것도 쓰지 않은 경우 항목은 경계나 클러스터의 기본값 대신namespace를 담지 않는데, 그런 리소스는 출력을 적용하는 도구가 배치하는 곳에 놓이며 이는 빌드 실행 시점에 알 수 없기 때문입니다. 템플릿은optional로 두 경우를 구별합니다.{{ optional . "namespace" "" }}는 문서가 아무것도 쓰지 않은 경우에만 정확히 비어 있으므로, 컴포넌트의 파드 옆에 무언가를 배치하는 Feature는 파드의 네임스페이스가 알려진 컴포넌트와 그렇지 않은 컴포넌트를 구별할 수 있습니다.- kind와 API 그룹으로 인식합니다.
Pod와Service는 core 그룹에서, 네 가지 컨트롤러는apps에서,Job과CronJob은batch에서 그룹의 모든 버전에 대해 읽습니다. 다른 그룹의 커스텀 리소스가 우연히 이 kind 이름 중 하나를 가지더라도 그것으로 읽지 않습니다. 셀렉터의matchExpressions는 보고되지 않으며,kind: List문서 안에 감싸인 리소스나 YAML 병합 키를 통해 쓴 값도 보고되지 않습니다.
팩트가 볼 수 없는 것. 팩트는 빌드가 출력하는 문서를 설명하며, 클러스터가 나중에 생성하는 것은 설명하지 않습니다. 컨트롤러가 런타임에 커스텀 리소스로부터 생성하는 파드(예: 오퍼레이터의 데이터베이스 클러스터)는 출력된 어떤 문서에도 나타나지 않으므로 구조상 없습니다. 매니페스트가 적용될 때 변경 어드미션 컨트롤러가 추가하는 레이블도 마찬가지입니다. 그런 파드를 허용해야 하는 Feature는 이 팩트 없이 작성자가 하듯이 커스텀 리소스 자체 문서에서 레이블을 가져옵니다.
호스트의 컨트롤러 셀렉터로 호스트 자신의 파드를 선택하여, 호스트를 호출하는 컴포넌트의 파드만 정확히 호스트의 파드로 허용하는 FeatureRecipe:
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: admit-callers version: 1.0.0spec: capability: helm implements: example/admit-callers:1.0.0 readsCallerRenderFacts: true artifacts: allow-callers.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: {{ .context.rendered_name }}-allow-callers spec: podSelector: matchLabels: {{- range .context.render_facts.controller_selectors }} {{- range $k, $v := .match_labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} policyTypes: - Ingress ingress: - from: {{- range .context.used_by }} {{- range .render_facts.pod_template_labels }} - podSelector: matchLabels: {{- range $k, $v := .labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} {{- end }}이 provider가 Workload를 합성한 컴포넌트 web이 호출하는 호스트 api의 경우, 정책은 app: "api"를 선택하고 web의 파드 템플릿의 모든 레이블을 담은 podSelector를 허용합니다. 이는 출력된 Deployment의 spec.template.metadata.labels가 담은 것과 같은 레이블입니다. FeatureRecipe가 이 키를 설정하므로 그 연결은 모든 컴포넌트가 렌더링된 뒤에 렌더링되며, 따라서 빌드가 api와 web 중 어느 것에 먼저 도달하든 팩트가 존재합니다. 이 키가 없으면 .context.used_by에서 render_facts를 읽는 템플릿은 아무것도 렌더링되기 전에 빌드를 중단합니다.
정책의 from에 있는 podSelector는 정책 자신의 네임스페이스에 있는 파드와 일치하므로, 위 정책은 정책이 적용되는 네임스페이스에 출력된 호출자를 허용합니다. 항목이 다른 namespace를 담은 호출자는, 그 podSelector를 해당 네임스페이스의 kubernetes.io/metadata.name 레이블에 대한 namespaceSelector와 짝지어 허용합니다. 이 레이블은 Kubernetes가 모든 네임스페이스에 설정합니다.
Provider별 특이 사항
-
차트 다운로드에는 Helm의 내장 핸들러만 사용합니다. Helm 리포지토리에서 가져오는 차트는 Helm 자체의 내장
http및https핸들러로 다운로드됩니다. Helm 다운로더 플러그인은helm명령용으로 설치된 것이든 빌드가 실행되는 디렉터리에 있는 것이든 절대 참조되지 않으므로, 그 디렉터리에 있는 내용이 차트를 가져오는 방식을 바꿀 수 없습니다. -
출처 정보 주입. sourced 경로와 synthesized 경로는 동일한 레이블 및 어노테이션 집합으로 수렴합니다. sourced 렌더는 (Helm SDK가 렌더링을 마친 뒤) 후처리 YAML 재작성을 통해 이를 주입하므로, 차트 작성자가 자신의 템플릿에 Aggrega 레이블을 직접 전달할 필요가 없습니다.
-
환경 변수 순서 — Secret에서 읽는 항목이 먼저. 합성된 컨테이너의
env목록에는 두 종류의 항목이 들어갑니다.as: env로 전달되는 각attachments항목은valueFrom.secretKeyRef를 통해 Secret에서 값을 읽고, 각variables항목은 일반value를 가집니다. provider는 Secret에서 읽는 항목을 모두 먼저 쓰고 일반 변수를 그 뒤에 쓰며, 각 종류 안에서는 작성된 순서를 따르고,envFrom소스는envFrom아래에 별도로 나열합니다. Kubernetes는env값 안의$(NAME)참조를 같은 컨테이너에서 그보다 앞에 나열된 항목으로부터 확장하며, 뒤에 나열된 항목으로부터는 절대 확장하지 않습니다. 따라서 이 순서 덕분에 일반 변수가 참조를 통해 Secret에서 읽은 값을 조합할 수 있고, 비밀 자체는 Secret 안에 그대로 남습니다.containers:api:image: "api:1.0"variables:DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"attachments:DB_PASSWORD: { from: db-credentials, as: env }렌더링된 컨테이너는
DB_PASSWORD를DATABASE_URL보다 앞에 나열하므로, 프로세스는 비밀번호가 채워진 URL을 받습니다. 변수는 자신보다 앞에 작성된 어떤 변수든 참조할 수도 있으므로,variables안에서 작성 순서가 의미를 가집니다. init 컨테이너도 같은 순서를 따릅니다. 하나의 이름을variables항목으로도,as: env로 전달되는attachments항목으로도 지정한 컨테이너는 두 항목을 모두 쓰는 대신 빌드를 중단합니다. 그렇지 않으면 이 순서만으로 프로세스가 보는 값이 결정되기 때문입니다(A container gives one environment variable two values (컨테이너가 하나의 환경 변수에 두 값을 지정함) 참조). -
네임스페이스 캐스케이드 — 두 모드는 리소스에 서로 다르게 도달합니다. 두 모드 모두 경계 어노테이션 캐스케이드에서
aggrega.ai/namespace를 읽으며, 어떤 경계도 네임스페이스를 선언하지 않으면 어느 쪽도 네임스페이스를 만들어 내지 않습니다. synthesized 모드에서 provider는metadata.namespace를 직접 쓰고, 캐스케이드가 값을 내지 않으면 필드를 완전히 생략합니다. sourced 모드에서 provider는 이 값을 차트의 릴리스 네임스페이스로 제공하며(캐스케이드가 값을 내지 않으면default), 이를 투영할지는 차트 자체 템플릿이 결정합니다. 네임스페이스가 선언된 경우 provider는 이어서 차트가 네임스페이스 없이 렌더링한 모든 네임스페이스 범위 리소스에 그 네임스페이스를 씁니다(Sourced mode 참조). 따라서 네임스페이스가 선언되면 두 모드 모두 모든 네임스페이스 범위 리소스를 그 안에 배치합니다. 단, 차트가 직접 고정한 네임스페이스와 provider가 분류할 수 없는 kind는 예외입니다. 선언이 없으면 두 모드는 갈라집니다. 릴리스 네임스페이스를 투영하는 차트는 synthesized 출력이 아무것도 쓰지 않는 곳에서 리소스를default에 배치하고, 네임스페이스를 쓰지 않는 차트는 어떤 네임스페이스에도 배치하지 않으므로, 리소스는 매니페스트를 적용하는 도구가 두는 곳에 놓입니다. 표준 라이브러리 FeatureRecipes가 포함하는 로컬 차트는 대신valuesMapping을 통해 캐스케이드 값을 직접 읽습니다. 이렇게 하면 어떤 경계도 네임스페이스를 선언하지 않을 때 필드를 생략하여 synthesized 출력과 일치시킬 수 있는데, 릴리스 네임스페이스는 절대 비어 있지 않으므로 그것만으로는 이를 표현할 수 없습니다.
실습 예제
Sourced 모드 — 벤더링된 차트를 가리키는 Recipe:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helm version: 1.0.0spec: capability: helm implements: core/api-server source: ./vendor/charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }} service: type: ClusterIP port: {{ .values.port }} env: LOG_LEVEL: "{{ optional .values `log_level` "info" }}"Workload 모드 — 인라인 Workload를 선언하는 Recipe:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-workload version: 1.0.0spec: capability: helm implements: core/api-server workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: api: image: "{{ .values.image }}" ports: web: {{ .values.port }} services: svc: type: ClusterIP ports: web: {{ .values.port }}상호 참조
entities/recipe.md— Recipe 작성 인터페이스와 세 가지 입력 종류.entities/workload.md— 합성 모드용 Workload 스키마.providers/helm-chart.md— 평면 매니페스트 대신 Helm 차트 스캐폴드를 출력하는 자매 프로바이더.providers/well-known-annotations.md— helm 프로바이더가 적용하는 잘 알려진 어노테이션(aggrega.ai/namespace등).architecture/16-recipe-input-composition.md— provider 전반의 Provider Capability Matrix(Provider 기능 매트릭스).10-status.md#providers— 현재 준비 상태 분류.