잘 알려진 어노테이션
Providers는 플랫폼별 컨텍스트를 구성하기 위해 특정 어노테이션을 읽습니다. 이 어노테이션은 Release 경계나 Release 컴포넌트 항목에 설정되거나, Aggregate에서 서브시스템 또는 컴포넌트 인스턴스에 선언됩니다. 컴파일러 자체는 이러한 어노테이션의 값에 구애받지 않으며, 값을 불투명한 문자열로 그대로 전달합니다. 각 provider는 자신이 읽는 어노테이션, 그 범위, 그리고 어노테이션이 없을 때 적용되는 기본값을 선언합니다. 이 선언은 provider 렌더링 Plugin의 spec.provider.wellKnownAnnotations에 있으며, 의도적으로 범위가 좁습니다. provider는 자신이 읽는 키만 나열합니다. 이 중 어느 것도 읽지 않는 provider는 대신 spec.provider.readsNoWellKnownAnnotations: true를 선언합니다.
이 장의 지원 매트릭스는 선언이 담고 있는 단위, 즉 provider별 입력 종류별로 이러한 선언에서 생성됩니다. provider는 배포 단위를 합성할 때는 키를 읽을 수 있지만 벤더링된 아티팩트를 렌더링할 때는 그 키를 읽을 방법이 없을 수 있기 때문입니다. 작성할 때는 여기의 매트릭스를 기준으로 하십시오. 각 셀은 해당 provider가 해당 경로에서 무엇을 읽는지를 나타내며, provider가 선언하지 않은 내용은 셀에 나타날 수 없습니다. provider 자신의 렌더링 동작 계약이 렌더링하지 않는 입력 종류를 명시한 선언은 Plugin 엔터티를 읽을 때 거부되므로, 두 주장이 서로 어긋날 수 없습니다.
예약된 어휘는 더 넓은 집합이며, 대신 두 곳에 있습니다. 하나는 어떤 provider도 읽지 않는 키를 포함하여 모든 예약 키를 명시하는 이 장이고, 다른 하나는 게시 린트가 검사하는 예약 접두사 집합입니다.
불변 조건
- 컴파일러는 provider 잘 알려진 어노테이션의 값을 결코 해석하거나 검증하지 않습니다. 키와 그 값을 캐스케이드를 통해 전달하고, 대상이 그 키에 따라 동작하지 않는 경우 경고합니다.
- 각 provider는 자신이 읽는 어노테이션과 적용하는 기본값을 문서화합니다.
- 어노테이션은 경계 안에서 균일하게 적용됩니다. 값이 컴포넌트마다 달라진다면, 그 값은 컴포넌트 수준 어노테이션(경계 어노테이션을 재정의함)이나 컴포넌트의
infra에 두어야 합니다. - Provider 잘 알려진 어노테이션은 컴포넌트 레이블과 절대 중복되지 않습니다. Component 레이블은 컴포넌트가 무엇인지를 기술합니다. 경계 어노테이션은 컴포넌트가 어디에 배포되는지를 기술합니다.
- Recipes는 provider의 잘 알려진 어노테이션을 다루지 않습니다. provider는 Recipe가 콘텐츠를 생성한 뒤 배치 컨텍스트(네임스페이스, 레지스트리 접두사, 서비스 계정)를 자동으로 적용합니다.
aggrega.ai/접두사는 표준 라이브러리용으로 예약되어 있습니다. 기업 고유의 사용자 정의 어노테이션은 자체 접두사를 사용합니다.- Release의 Component 수준 어노테이션은 경계 수준 어노테이션을 재정의합니다(딥 머지, 컴포넌트 우선). 프로바이더가 여러 경계의 출력을 하나의 아티팩트로 조립하는 경우, 어노테이션이 그 경계들 전체에서 동일하게 해석되도록 요구할 수 있습니다.
helm-chart프로바이더는 엄브렐라 차트의 이름을aggrega.ai/chart-name에서 가져오며, 둘 이상의 경계가 같은 차트에 기여하면서 그 어노테이션을 서로 다른 값으로 해석하면 하나의 차트가 두 개의 이름을 가질 수 없으므로 빌드는 불일치하는 경계를 명시하며 중단됩니다. - Aggregate가 선언하는 어노테이션은 Release의 어노테이션보다 낮은 우선순위로 같은 키에 도달합니다. 서브시스템이나 컴포넌트 인스턴스에 선언된 키는 — Aggregate 자체에 선언되었든, Aggregate가 가져오는 모듈에 선언되어 그 모듈 자체의 컴포넌트에 도달하든 — Release가 그 키에 값을 설정하지 않은 곳이라면 어디서나 해당 컴포넌트에 적용됩니다. Release가 경계나 컴포넌트 항목에 값을 설정한 경우에는 Release의 값이 적용됩니다. 카탈로그 엔터티 자체의 어노테이션은 이 값을 설정하지 않습니다.
aggrega.ai/chart-name은 Aggregate의 도달 범위에서 예외입니다. 이 키는 컴포넌트가 아니라 어셈블리를 명명하며, 그 어셈블리에 기여하는 Release 경계에서 읽힙니다.
전체 어노테이션 매트릭스
이 매트릭스를 읽는 방법
아래의 여섯 가지 범주 표는 예약된 aggrega.ai/ 어휘의 모든 어노테이션과 각 어노테이션이 제어하는 대상, 그리고 어노테이션이 없을 때 provider가 하는 동작을 나열합니다. 특정 provider가 특정 키를 적용하는지는 더 세밀한 질문입니다. provider는 둘 이상의 입력 종류를 렌더링하기 때문입니다. 벤더링된 아티팩트(sourced), provider가 직접 합성하는 Workload(synthesized), 또는 노드의 전체 출력으로서의 Recipe의 artifacts:(artifacts-only)가 그것이며, 하나의 키는 이 경로 중 하나에서는 읽히면서 다른 경로에서는 도달할 수 없을 수 있습니다. 어떤 provider가 어떤 입력 종류를 렌더링하는지는 ../../architecture/16-recipe-input-composition.md에 있으며, 각 provider가 무엇을 적용하는지는 아래의 provider 및 입력 종류별 지원에 있고, 이것이 이 페이지의 권위 있는 설명입니다.
이 그리드의 모든 셀은 세 가지 등급 중 하나를 가집니다.
- 적용됨 — provider가 이 입력 종류에서 키를 적용하며, 그 결과 렌더링된 출력이 결정적으로 바뀝니다.
- 조건부 적용 — 컴파일러가 대상 아티팩트를 편집하는 대신 그 옆에 추가적인 오버라이드를 내보내므로, 값이 효력을 갖는지는 해당 아티팩트가 자체적으로 일치하는 키를 노출하는지에 달려 있습니다. 실제로는 효과가 있지만 결코 보장은 아닙니다. 조건부 셀을 구현하는 provider는 없으며, 선언 표면에도 이를 표현할 방법이 없으므로 아래에 생성된 그리드는 나머지 두 등급만 내보냅니다. 이 등급을 명시하는 이유는 벤더링된 아티팩트에 대해 이 경로가 실제로 존재하며, 두 등급만의 어휘로는 매트릭스가 할 수 없는 보장을 주장하거나 경로의 존재 자체를 부정해야 하기 때문입니다.
- 적용되지 않음 — 이 경로에서 키를 적용하는 provider가 없습니다. 대상에 그 키를 위한 렌더 슬롯이 없으므로 배치 메커니즘은 렌더링되는 내용에 아무것도 기여하지 않으며, 대신 무엇을 얻는지는 범주 표의 기본값 열이 알려 줍니다. 값은 여전히 불투명한 문자열로 변경 없이 빌드를 통과합니다. 이 등급은 값의 운명이 아니라 메커니즘을 기준으로 이름 붙여졌습니다. 둘은 서로 다른 질문이고 셀이 답할 수 있는 것은 앞의 질문뿐이기 때문입니다. provider가 무엇을 적용하는지는 해당 대상의 렌더 슬롯의 속성이며, 이것이 바로 각 셀 뒤의 선언이 명시하는 내용입니다.
두 가지 범위가 있으며, 그중 하나에서만 입력 종류가 의미 있는 축이 됩니다.
- 노드 범위 —
aggrega.ai/namespace,aggrega.ai/image-registry,aggrega.ai/image-pull-secret,aggrega.ai/service-account,aggrega.ai/kubernetes-version은 하나의 component 자체의 렌더링된 출력을 형성하며, 이 출력은 해당 입력 종류가 선택하는 경로가 생성합니다. 이것들이 그리드의 열입니다. - 어셈블리 및 참조 범위 —
aggrega.ai/chart-name은 umbrella chart가 어셈블될 때 한 번 해석되고, 세 개의aggrega.ai/aws-*키는 참조가 경계를 넘을 때 해석됩니다. 어느 쪽에서도 입력 종류는 축이 아닙니다. 기여하는 각 노드가 어떻게 렌더링되었든 값은 어셈블리 또는 참조 시점에 읽힙니다. 이 키들은 어셈블리별 및 참조별로 해석되는 키에 별도의 표가 있습니다.
범주 1 — 배치
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/namespace | helm (sourced, synthesized); compose (sourced, synthesized) | Kubernetes 네임스페이스(helm); Docker 네트워크 이름(compose) | 없으면 주입되지 않음(helm); compose 파일의 경로를 따라 이름 붙인 네트워크로, 해당 파일에서 어노테이션이 없는 모든 노드가 공유함(compose) |
aggrega.ai/project-name | 예약됨; 어떤 provider도 읽지 않음 | Docker Compose 프로젝트 이름용으로 예약됨 | — |
aggrega.ai/region | 예약됨; 어떤 provider도 읽지 않음 | 배치 범위의 클라우드 리전용으로 예약됨 | — |
aggrega.ai/account-id | 예약됨; 어떤 provider도 읽지 않음 | 배치 범위의 클라우드 계정 식별자용으로 예약됨 | — |
aggrega.ai/kubernetes-version | helm (sourced) | component가 배포되는 클러스터의 Kubernetes 버전으로, 소스에서 렌더링된 chart는 이를 .Capabilities.KubeVersion으로 읽습니다 | 같은 helm 릴리스의 기본 helm template이 렌더링 대상으로 삼는 버전, 즉 provider가 빌드될 때 사용된 Kubernetes 클라이언트 라이브러리의 버전 |
aggrega.ai/namespace는 설계상 이중 목적을 가집니다. 이 어노테이션은 *“이 경계의 리소스는 고유하게 주소 지정 가능한 범위에 존재한다”*라는 동일한 논리적 격리 의도를 각 대상의 고유한 형태로 표현합니다. helm에서는 Kubernetes metadata.namespace, compose에서는 Docker 네트워크 이름입니다. Recipe 작성자는 어노테이션 하나를 설정하고, 각 provider가 대상에 맞게 이를 구체화합니다. compose의 경우 네트워크 이름은 노드별로 해당 노드의 어노테이션에서 해석되며, 노드에 어노테이션이 없으면 compose 파일의 경로로 대체됩니다. 따라서 하나의 compose 파일을 공유하는, 어노테이션이 없는 경계들은 하나의 네트워크를 공유하며, 이들을 분리하는 것이 aggrega.ai/namespace입니다. 둘 중 어느 쪽이 식별자를 제공하든, 그 식별자는 compose 네트워크 이름이 허용하는 문자로 기록됩니다. 그 밖의 모든 문자는 다른 문자로 치환되지 않고 이스케이프로 기록되므로, 조금이라도 다른 두 식별자는 서로 다른 두 네트워크에 남고, 식별자의 대소문자는 작성된 그대로 유지됩니다. compose provider 레퍼런스에 인코딩된 이름을 읽는 방법과 이름 변경의 비용을 포함한 파생 과정 전체가 설명되어 있습니다.
aggrega.ai/kubernetes-version은 component가 클러스터 안의 어디에 놓이는지가 아니라 component가 배포되는 클러스터의 속성을 명시합니다. chart 템플릿은 렌더링 대상 버전에 따라 API 버전, 필드 또는 메커니즘 전체를 선택하며, 빌드에는 물어볼 클러스터가 없습니다. helm provider는 helm template --kube-version이 플래그를 읽는 방식으로 이 값을 읽으며, 버전이 아닌 값이면 빌드를 중단합니다. 값이 지정되지 않으면 chart는 같은 helm 릴리스의 helm template이 렌더링 대상으로 삼는 버전으로 렌더링됩니다. helm provider 레퍼런스에 허용되는 형식과 기본값이 설명되어 있습니다.
범주 2 — 레지스트리
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — synthesized에만 해당 | 컨테이너 이미지의 레지스트리 접두사로, 합성된 모든 컨테이너 이미지 참조에 적용됨 | 접두사 없음 |
aggrega.ai/image-pull-secret | helm — synthesized에만 해당 | Kubernetes imagePullSecrets 이름으로, 합성된 pod의 기존 항목과 합쳐짐 | 없음 |
범주 3 — 네트워킹
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/cluster-domain | 예약됨; 어떤 provider도 읽지 않음 | 네임스페이스 간 서비스 디스커버리를 위한 DNS 접미사용으로 예약됨 | — |
aggrega.ai/ingress-class | 예약됨; 어떤 provider도 읽지 않음 | Ingress 리소스의 Kubernetes IngressClass용으로 예약됨 | — |
aggrega.ai/service-mesh | 예약됨; 어떤 provider도 읽지 않음 | 메시 사이드카 주입 어노테이션용으로 예약됨 | — |
범주 4 — 보안
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/service-account | helm — synthesized에만 해당 | 합성된 Pod의 Kubernetes ServiceAccount; 둘 다 설정된 경우 Recipe의 workload.serviceAccount를 오버라이드함 | Recipe의 workload.serviceAccount, 또는 Recipe가 선언하지 않으면 설정되지 않음 |
aggrega.ai/pod-security-standard | 예약됨; 어떤 provider도 읽지 않음 | Pod Security Standards 수준용으로 예약됨 | — |
aggrega.ai/iam-role | 예약됨; 어떤 provider도 읽지 않음 | 워크로드에 바인딩된 클라우드 ID 역할용으로 예약됨 | — |
범주 5 — 패키징
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — 어셈블리별 | umbrella chart 이름 | Aggregate 이름과 엄브렐라의 어셈블리 경로를 결합한 값 — 차트 이름 해석 참조 |
aggrega.ai/chart-version | 예약됨; 어떤 provider도 읽지 않음 | Helm chart 버전용으로 예약됨 | — |
aggrega.ai/stack-name | 예약됨; 어떤 provider도 읽지 않음 | 명시적으로 이름이 지정된 스택용으로 예약됨 | — |
aggrega.ai/tf-backend | 예약됨; 어떤 provider도 읽지 않음 | Terraform 상태 백엔드 식별자용으로 예약됨 | — |
범주 6 — 클라우드 대상
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — 경계 간 참조별 | 스택(경계)이 배포되는 AWS 계정 | 동일 계정 — 스택 간 참조는 동일 계정 스택 내보내기 가져오기를 통해 해석됨 |
aggrega.ai/aws-region | cloudformation — 경계 간 참조별 | 스택(경계)이 배포되는 AWS 리전 | 동일 리전 — 스택 간 참조는 동일 리전 스택 내보내기 가져오기를 통해 해석됨 |
aggrega.ai/aws-assume-role-arn | cloudformation — 경계 간 참조별 | 계정 간 스택 읽기가 피어 스택의 내보낸 값에 접근하기 위해 수임하는 IAM 역할 ARN | 계정 간 참조에 역할이 제공되지 않음 |
각 CloudFormation 경계는 하나의 스택으로 렌더링됩니다. uses 엣지가 한 경계에서 다른 경계로 넘어갈 때, cloudformation provider는 참조를 형성하기 위해 피어 스택이 어디에 있는지 알아야 합니다. 같은 계정과 리전에 있는 두 스택은 스택 내보내기와 가져오기를 통해 값을 교환하고, 다른 계정이나 리전에 있는 피어는 계정 간 스택 출력 읽기가 필요하며, 선택적으로 수임한 역할 아래에서 수행됩니다. 이 어노테이션들이 그 배치 컨텍스트를 전달합니다. 각 어노테이션은 provider가 그러한 참조를 형성하는 시점에 읽히며, 그 시점에 일반적인 어노테이션 캐스케이드를 통해 해석됩니다. component에 설정된 값이 경계에 설정된 값보다 우선하고, Release가 설정한 값이 Aggregate가 선언한 값보다 우선합니다. 따라서 경계 수준의 값은 이를 표현하는 일반적인 방법이지만 유일한 방법은 아닙니다. 이 값들은 불투명한 스칼라 포인터 문자열입니다. provider는 이를 자신이 만드는 참조에 전달할 뿐 실제 AWS 상태에 대해 해석하지 않습니다. 계정, 리전, 역할은 Release가 제공하거나 Aggregate에 선언되며, 최종 물리적 읽기는 런타임 환경이 해석합니다. 모든 어노테이션이 없으면 provider는 피어를 동일 계정 및 동일 리전으로 취급하고 역할을 제공하지 않습니다.
provider 및 입력 종류별 지원
provider별, 입력 종류별 노드 범위 키입니다. 열 머리글에서는 모든 키에 붙는 aggrega.ai/ 접두사를 생략합니다. applied와 —는 위에서 정의한 등급을 나타내며, —는 적용되지 않음입니다. n/a는 provider가 해당 입력 종류를 전혀 렌더링하지 않으므로 그곳에는 키가 적용되거나 누락될 경로 자체가 없음을 뜻합니다.
| Provider | 입력 종류 | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
컴파일러와 함께 배포되는 모든 provider는 배치 어노테이션을 전혀 읽지 않는 provider를 포함하여 여기에 행이 있습니다. 행이 비어 있으면 아직 아무도 설명하지 않은 provider와 구별할 수 없기 때문입니다. 별도로 제공되는 provider는 자신이 읽는 것을 같은 방식으로 선언하지만 여기에 나열되지 않습니다. 게시된 페이지는 본 적 없는 provider를 열거할 수 없기 때문입니다.
Recipe는 한 번에 둘 이상의 입력 종류를 선언할 수 있습니다. 예를 들어 workload:와 함께 artifacts:를 선언할 수 있습니다. 그리드는 종류별로 읽으십시오. 그러한 노드의 합성된 출력은 synthesized 행이고, 아티팩트 파일은 artifacts 경우에 해당합니다. artifacts-only 행은 Recipe가 artifacts:만 선언하고 다른 것은 선언하지 않는 입력 종류입니다.
이를 알아내기 위해 그리드를 참조할 필요는 없습니다. 렌더 중 하나의 대상이 그 렌더의 어떤 입력 종류에서도 읽지 않는 키를 설정하면 해당 키, 대상, 그리고 그 렌더가 선언하는 모든 입력 종류를 명시하는 경고가 발생합니다. 따라서 실수로 해당하게 된 셀은 여기를 확인할 생각이 들 때까지 기다리지 않고 빌드하는 순간 스스로 드러납니다.
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it둘 이상의 입력 종류를 선언하는 렌더에서 경고는 그 절반 중 하나가 아니라 렌더 전체에 관한 것입니다. 종류들은 덧셈으로 합성되므로, 그중 어느 하나에서라도 키를 읽는 대상은 실제로 키를 적용하며, 그 렌더의 출력에 결과가 반영됩니다. 따라서 경고가 발생하지 않습니다. 경고는 그 렌더가 선언하는 모든 종류가 키를 놓칠 때에만 나타나며, 그 종류를 모두 명시합니다.
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it따라서 source:와 함께 workload:가 있으면 해당 노드에서 aggrega.ai/service-account가 효력을 갖기에 충분하며, 빌드는 이에 대해 아무 말도 하지 않습니다. 이는 정직한 보고입니다. 값이 합성된 절반에 도달하여 내보낸 매니페스트에 나타나기 때문입니다.
그리드는 component별이 아니라 렌더별로 읽으십시오. 노드에 연결된 feature는 자체 FeatureRecipe가 지정하는 대상을 통해, 그 FeatureRecipe가 선언하는 입력 종류로 리소스를 생성합니다. 따라서 feature는 이 그리드에서 자신의 행에 해당하며, 이는 호스트 component가 해당하는 행과 같을 필요가 없습니다. Workload를 합성하는 component에 연결된 feature가 그 옆에 artifacts:를 제공하는 경우, component 자체의 매니페스트는 synthesized 행을, 연결된 feature의 파일은 artifacts-only 행을 읽으며, 앞의 경우에 적용되는 키가 뒤의 경우에는 누락될 수 있습니다. 경고도 같은 방식으로 나뉘어 각각을 따로 알려 줍니다. 서로 다른 파일이기 때문입니다. 이름이 지정된 component가 아니라 경계에 연결된 feature도 같은 방식으로 그리드를 읽습니다.
값은 여전히 변경 없이 통과하며 빌드는 중단되지 않습니다. 이질적인 대상의 component들에 걸친 경계에는 특정 키에 따라 동작할 수 없는 렌더가 항상 있기 마련이며, 이는 실수가 아니라 일반적인 Release이기 때문입니다. 경계 어노테이션은 캐스케이드되므로, 작성된 한 줄은 그에 따라 동작할 수 없는 렌더마다 경고 하나를 발생시키며, 이를 통해 출력의 어느 부분이 영향을 받는지 확인할 수 있습니다. 이 경고는 unsupported-field 클래스에 속하며 해당 클래스의 플래그로 억제할 수 있습니다. 자세한 내용은 경고를 참조하십시오. 알아 둘 만한 두 가지 제한이 있습니다. 하위 접두사가 붙은 키는 사용자 자신의 어휘이므로 순수한 aggrega.ai/ 키만 검사되며, 지원 선언을 전혀 하지 않는 provider는 작성된 내용과 비교할 대상이 없으므로 경고를 발생시키지 않습니다. 이러한 키를 하나도 읽지 않는다고 선언하는 provider는 그런 식으로 침묵하지 않습니다. 해당 Plugin 엔터티의 readsNoWellKnownAnnotations: true는 어떤 키도 포함하지 않는 지원 선언이므로, 그 렌더 중 하나에 도달하는 모든 순수한 키는 경고를 발생시킵니다. terraform provider가 이를 선언합니다.
벤더링된 아티팩트가 더 적은 키를 적용하는 이유. 노드 범위 어노테이션은 provider가 그것을 위한 렌더 슬롯을 가진 곳에서 적용됩니다. provider가 배포 단위를 직접 합성할 때는 결과의 모든 필드를 소유하므로 레지스트리 접두사, pull secret, 서비스 계정이 모두 들어갈 자리가 있습니다. 반면 Helm chart, compose 파일, Terraform 모듈 같은 벤더링된 아티팩트는 자체 구성 인터페이스를 가지며, 컴파일러는 그 인터페이스를 읽지 않으므로 레지스트리 접두사나 서비스 계정이 아티팩트의 어떤 자체 키에 해당하는지 알 수 없습니다. 주변 렌더 호출이 제어하는 배치는 여전히 적용되며, 이 때문에 소스에서 렌더링된 chart에 aggrega.ai/namespace가 적용됩니다. 다른 사람의 아티팩트 내부 어디에 값이 속하는지 결정해야 하는 배치는 적용되지 않으며, 작성자는 해당 아티팩트 자체의 값을 통해 이를 제공합니다. 이것이 synthesized 행은 채워져 있는데 sourced 행은 드문드문한 이유이며, 나중에 추가되는 키에도 예상되는 형태입니다.
어셈블리별 및 참조별로 해석되는 키
제공되는 키 중 네 개는 노드 범위가 아니므로 위 그리드에 포함되지 않고 그 바깥에 놓입니다. 이 키들에는 입력 종류가 의미 있는 축이 아니며, 각 키에 입력 종류별 행을 두면 하나의 셀을 세 번 반복하게 되고 존재하지 않는 구분을 암시하게 됩니다. 각 키는 boundary 범위를 선언하며, 아래 표는 그 선언에서 생성됩니다.
| 어노테이션 | 적용 주체 | 목적 | 기본값 |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | 어셈블된 umbrella Helm chart의 이름입니다. | Aggregate 이름과 umbrella chart의 조립 경로(dist/ 아래의 출력 디렉터리, 예: boundaries/data/helm-chart)가 사용되며, 각각 인코딩된 뒤 결합됩니다. |
aggrega.ai/aws-account | cloudformation | 스택(boundary)이 배포되는 AWS 계정입니다. boundary 간 참조는 이 값을 읽어 피어 스택이 같은 계정에 있는지 판단합니다. | 피어를 같은 계정으로 간주하며, 스택 간 참조는 교차 계정 스택 출력 읽기가 아니라 같은 계정의 스택 export import를 통해 해석됩니다. |
aggrega.ai/aws-region | cloudformation | 스택(boundary)이 배포되는 AWS 리전입니다. boundary 간 참조는 이 값을 읽어 피어 스택이 같은 리전에 있는지 판단합니다. | 피어를 같은 리전으로 간주하며, 스택 간 참조는 같은 리전의 스택 export import를 통해 해석됩니다. |
aggrega.ai/aws-assume-role-arn | cloudformation | 교차 계정 스택 읽기가 피어 스택의 export 값에 접근하기 위해 맡는 IAM 역할 ARN입니다. | 역할이 제공되지 않으며, 교차 계정 참조는 assume-role을 포함하지 않습니다. |
각 키가 해석되는 시점은 선언 자체에 담겨 있지 않습니다. aggrega.ai/chart-name은 umbrella chart 어셈블리마다 한 번, boundary 어노테이션 캐스케이드에서 해석됩니다. 하나의 어셈블리에 기여하는 모든 요소는 이 값을 같은 값으로 해석해야 하며, 값이 일치하지 않으면 해당 boundary들을 명시하며 빌드가 중단됩니다. 세 개의 aggrega.ai/aws-* 키는 component가 boundary보다 우선하는 규칙에 따라 boundary 간 참조마다 해석되므로, component 값이 boundary 값보다 우선합니다. 각 키가 구성하는 참조는 위의 Category 6에서 설명합니다.
어떤 provider도 읽지 않는 예약된 이름
위 매트릭스의 키 중 열한 개는 예약됨, 어떤 provider도 읽지 않음으로 표시되어 있습니다. aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name, aggrega.ai/tf-backend.
Release나 Aggregate에 이 키 중 하나를 설정해도 렌더링 출력에는 아무 영향이 없습니다. 이 키를 읽는 provider는 없으며, 이 키를 대신하여 적용되는 기본값도 없습니다. 특히 aggrega.ai/cluster-domain에 대해서는 DNS 접미사가 적용되지 않으므로, 클러스터 도메인이 필요한 Recipe는 이 어노테이션에 의존하지 말고 일반 값으로 제공해야 합니다. 이러한 동작 중 하나가 필요한 Recipe 작성자는 이를 Recipe 값 또는 component의 infra 필드로 표현합니다.
이 열한 개를 선언하는 provider는 없습니다. provider의 wellKnownAnnotations에는
그 provider가 읽는 것만 나열되므로, 열한 개 중 어느 것도 거기에 나타나지 않습니다.
helm, helm-chart, compose 또는 cloudformation Plugin을 여는 독자는 동작하는 키만 보게 되며
그 외에는 보이지 않습니다. 이것이 좁은 선언의 목적입니다. 선언된 키는
동작하는 키이며, 그 옆의 범위는 어느 경로에서 동작하는지 알려 줍니다.
예약된 이름 중 두 개는 실제 동작하는 키와 비슷하지만 서로 바꿔 쓸 수 없습니다. aggrega.ai/region과 aggrega.ai/account-id는 배치 범위에서 리전과 계정을 지정하며 어떤 provider에도 전달되지 않습니다. cloudformation provider가 읽는 키는 Category 6의 클라우드 네임스페이스 키인 aggrega.ai/aws-region 및 aggrega.ai/aws-account입니다. CloudFormation 스택 간 배치 컨텍스트를 의도한다면 aws- 형태로 작성하십시오. 접두사가 없는 쌍은 충돌 방지를 위해 예약되어 있을 뿐 어디에도 연결되어 있지 않습니다. 또 다른 예약된 이름 두 개는 어노테이션이 아닌 다른 수단으로 다루어집니다. aggrega.ai/stack-name은 예약되어 있으며, cloudformation boundary가 렌더링되는 스택 이름은 release와 boundary 식별자로부터 결정적으로 도출됩니다. 또한 workload의 클라우드 ID 역할은 aggrega.ai/iam-role이 아니라 바인딩을 내보내는 Feature의 운영자 설정 일반 필드로 제공됩니다.
이 이름들은 aggrega.ai/ 접두사가 예약되어 있기 때문에 계속 예약되며 여기에 계속 나열됩니다. 엔터프라이즈 카탈로그는 이 키 중 하나를 자체 의미로 재사용해서는 안 됩니다. 플랫폼이 그 키를 자체 의미를 위해 보유하고 있기 때문입니다. 이 매트릭스와 게시 lint가 검사하는 예약 접두사 집합이 함께 예약 등록부를 이루며, 두 가지는 양쪽을 모두 읽고 서로 어긋나면 실패하는 검사에 의해 같은 이름 집합으로 유지됩니다. 따라서 열한 개 중 하나를 작성해도 검증에 실패하지 않으며 “bare aggrega.ai/ 접두사를 사용하지 말 것” 규칙에도 걸리지 않습니다. 단지 아무 효과가 없을 뿐입니다.
helm-chart boundary가 내보내는 umbrella chart 버전은 항상 0.1.0입니다. 이는 aggrega.ai/chart-version의 기본값이 아니라 고정 값입니다.
참고:
aggrega.ai/접두사를 사용하는 Manifestfeatures.annotations바인딩은 로드 시점에 거부됩니다. 이 접두사는 이 장에서 설명하는 provider 공통 어노테이션 전용으로 예약되어 있습니다. 어노테이션 기반 Feature 바인딩 작성자는 표준 라이브러리 단축 키에는feature.aggrega.ai/를, 엔터프라이즈 단축 키에는 사용자 정의 도메인을 사용합니다.참고: Release 어노테이션에 명시적인
null을 지정하면 재정의하는 boundary 또는 component에서 상속된 바인딩이 제거됩니다(어노테이션 기반 Feature 옵트아웃). 같은 boundary 안에서 옵트아웃하지 않은 형제 component는 상속된 바인딩을 유지하며, 지정되지 않은 키는 평소처럼 상위 캐스케이드에서 계속 상속됩니다.
컴파일러가 읽는 카탈로그 작성 어노테이션
위의 모든 것은 provider 어노테이션입니다. 즉 Release에 작성되거나 Aggregate에 선언되고, 컴파일러가 불투명한 문자열로 그대로 전달하며, provider가 읽습니다. 이보다 훨씬 작은 두 번째 어휘는 반대 방향으로 동작합니다. Architect가 카탈로그 엔터티 자체의 metadata.annotations에 작성하고, 컴파일러가 읽으며, provider에게는 전혀 보이지 않습니다. 위의 불변 조건 1은 provider 어휘에 관한 것이며 이 키들에는 적용되지 않습니다. 컴파일러는 여기에 나열된 키만 정확히 읽고 그 외의 키는 읽지 않습니다.
이 키들은 접두사만 있는 aggrega.ai/가 아니라 <scope>.aggrega.ai/ 하위 접두사 아래에 있으므로, 위의 매트릭스가 담고 있는 예약 등록부의 범위 밖에 있으며, 게시 린트가 접두사만 있는 키에 적용하는 예약 접두사 규칙의 범위 밖에도 있습니다.
| 어노테이션 | 작성 위치 | 읽는 주체 | 목적 |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | Component metadata.annotations | 컴파일러, 최종 그래프에 대해 | 존재 의무를 선언합니다. 이 Component의 모든 인스턴스는 어노테이션 값과 같은 타입의 attachment를 하나 이상 가져야 합니다. <label>은 진단에서 해당 요구 사항의 이름이 되는, 작성자가 정하는 접미사입니다. 슬롯 이름이 아니며 이를 역참조하는 것은 없습니다. 여러 의무를 선언하려면 서로 다른 레이블로 키를 반복합니다. |
의무는 어느 범위의 attachment로든 충족됩니다. 컴포넌트 수준 또는 서브시스템 수준의 features: 블록, Release의 경계 수준 또는 컴포넌트 수준 블록, 또는 어노테이션 기반 확장이 모두 해당합니다. 이는 각 attachment가 어디에서 왔는지가 아니라 인스턴스의 최종 attachment 집합을 검사하기 때문입니다. 충족되지 않은 의무는 레이블과 요구되는 타입을 명시하며 빌드를 중단합니다. Feature 타입 URI가 아닌 값이나 접두사 뒤에 레이블이 없는 키는 별도의 잘못된 선언 진단과 함께 중단됩니다. 전체 작성 방법과 의무가 featuresSchema 슬롯과 어떻게 다른지는 entities/component.md의 “Presence mandates”에 있습니다.
provider가 내보내는 출처 레이블
위의 어노테이션은 빌드 안으로 흘러 들어갑니다. Release나 Aggregate가 이를 작성하고, provider가 이를 소비합니다. Providers는 또한 빌드 밖으로 나가는 병렬 레이블 집합을 내보내며, 이를 렌더링된 출력에 붙여 다운스트림 도구가 런타임 리소스를 그것을 생성한 카탈로그 콘텐츠로 거슬러 귀속할 수 있게 합니다. 이 출처 레이블은 Release에 작성되지 않습니다. 이 레이블은 빌드 자체의 상태(Recipe 식별자, 경계 경로, aggregate 이름, 환경, 동기화 웨이브, 컴파일러 버전)에서 파생되며 렌더링 시점에 provider가 내보냅니다.
provider들이 내보내는 집합으로, helm provider가 렌더링하는 모든 Kubernetes 매니페스트, helm-chart provider가 서브차트에 추가하는 $import:로 로드된 모든 아티팩트, 그리고 compose가 내보내는 모든 서비스에 부착됩니다. helm-chart 서브차트 자체의 템플릿은 작성자가 작성한 그대로 복사되므로, 해당 작성자가 작성한 내용을 그대로 가집니다.
| 레이블 | 출처 | 내보내기 |
|---|---|---|
app.kubernetes.io/name | 노드 ID(FeatureRecipe가 내보내는 리소스의 경우 해당 첨부에 대해 도출된 식별자. 아래 참조) | helm과 helm-chart만 해당. Kubernetes 표준 레이블이며 compose 서비스에는 내보내지 않음 |
aggrega.ai/component-id | 노드 ID(FeatureRecipe가 내보내는 리소스의 경우 해당 첨부에 대해 도출된 식별자. 아래 참조) | 세 provider 모두 |
aggrega.ai/recipe-uri | 생성한 Recipe(FR이 내보낸 리소스의 경우 생성한 FeatureRecipe)의 <recipe-name>:<recipe-version> | 세 provider 모두, 생성한 엔터티에 이름과 버전이 모두 설정된 경우. helm 및 helm-chart에서는 어노테이션 |
aggrega.ai/boundary-path | component가 라우팅된 경계 경로 | 세 provider 모두, 경계 경로가 비어 있지 않은 경우. helm 및 helm-chart에서는 어노테이션 |
aggrega.ai/aggregate-name | Aggregate metadata.name | 세 provider 모두, 설정된 경우 |
aggrega.ai/compiler-version | 빌드 시점에 기록된 컴파일러 버전 | 세 provider 모두, 설정된 경우 |
aggrega.ai/provider | 리소스를 렌더링한 provider | 세 provider 모두 |
aggrega.ai/provider-version | 해당 provider의 버전 | 세 provider 모두 |
aggrega.ai/environment | Release metadata.environment | 세 provider 모두 — 모든 Release가 이를 선언함 |
aggrega.ai/sync-wave | 경계별 syncWave 정수 | 세 provider 모두, 0이 아닌 경우. helm 및 helm-chart에서는 어노테이션 |
aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider, aggrega.ai/provider-version 값은 빌드가 Kubernetes 레이블 값 규칙에 맞도록 요구하지 않는 문자열에서 옵니다. 예를 들어 imported/flow라는 이름의 Aggregate, eu/prod라는 이름의 환경, 개발 빌드의 (devel) 버전이 그렇습니다. helm과 helm-chart에서는 값이 이미 유효한 레이블 값이면 이들 각 레이블이 값을 작성된 그대로 담습니다. 유효한 레이블 값은 영문자, 숫자, -, _, .로 이루어지고, 양 끝이 영문자 또는 숫자이며, 최대 63자입니다. 그렇지 않으면 레이블은 그 형식으로 다시 쓴 값을 담고(그 밖의 모든 문자는 -가 되고, 연속된 -는 하나로 합쳐지며, 양 끝은 영문자 또는 숫자까지 잘리고, 결과는 최대 63자로 잘립니다), 작성된 그대로의 값은 같은 키 아래 애너테이션으로 추가됩니다. 따라서 imported/flow라는 이름의 Aggregate에는 aggrega.ai/aggregate-name: imported-flow 레이블과 aggrega.ai/aggregate-name: imported/flow 애너테이션이 붙습니다. 레이블이 유지하는 문자가 하나도 없는 값은 애너테이션만으로 전달됩니다. 셀렉터는 렌더링된 출력에 나타나는 그대로의 레이블 값과 일치하며, 정확한 이름이 필요한 도구는 애너테이션이 있으면 그것을 읽습니다. 레이블 값에 제약이 없는 Compose는 작성된 그대로의 값을 레이블로 담습니다.
provider별 내보내기 참고 사항
helm— 레이블은 렌더링된 모든 Kubernetes 리소스(Deployment, Service, PVC 등)의metadata.labels에 들어가고, 레이블 값이 담을 수 없는 키인aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wave, 그리고 위에서 설명한 대로 다시 쓴 모든 레이블의 작성된 그대로의 값은metadata.annotations에 들어갑니다. 소스 모드(렌더링 후 레이블 주입을 사용하는 Helm SDK 렌더링), 합성 모드(워크로드 합성),artifacts:경로 모두 같은 집합을 생성합니다.helm-chart— 같은 레이블과 어노테이션이 provider가 서브차트의templates/에 추가하는$import:로 로드된 각 아티팩트에 들어갑니다. 소스 차트 자체의 템플릿과 서브차트 루트에 배치된 인라인 콘텐츠 아티팩트에는 어느 것도 들어가지 않습니다. helm-chart.md를 참조하십시오.compose— 레이블은 내보내는 모든 compose 서비스의services.<name>.labels에 들어갑니다. 소스 모드(병합된 base + valuesMapping 문서에 대한 병합 후 레이블 주입)와 합성 모드(워크로드 합성이 서비스의 labels 블록을 직접 설정) 모두 같은 집합을 생성합니다. Kubernetes 전용인app.kubernetes.io/name은 compose 출력에서 생략됩니다.
FeatureRecipe가 내보내는 리소스의 경우 aggrega.ai/component-id 값은 호스트 component의 이름이 아니라 첨부로부터 만들어집니다. 이는 FeatureRecipe가 그 리소스를 전달하는 모든 방식에 적용되므로, 첨부의 리소스가 레이블상으로 호스트 component 자체의 리소스와 구별되지 않는 일은 없습니다. 그 식별자가 해당 리소스의 이름의 기준이 되는지는 전달 방식에 따라 다릅니다. Aggrega가 합성하는 워크로드는 식별자를 따라 이름이 지어지지만, 첨부 작성자가 제공한 차트나 프래그먼트는 호스트 component의 Helm 릴리스 이름과 출력 파일 접두사를 유지합니다. 작성자 자신의 템플릿이 그 이름을 기준으로 렌더링되기 때문입니다. 값이 구성되는 방식, 즉 두 가지 시작 형태, 구성 요소와 그 -- 결합, 레이블에 담을 수 없는 문자를 표기하는 방법, 대상에 비해 너무 긴 값을 줄이는 방법, 그리고 어떤 이름의 기준이 되고 어떤 이름의 기준이 되지 않는지는 provider와 무관하므로, 여기서 반복하지 않고 vocabulary/labels-and-annotations.md의 “Provenance labels emitted on rendered output”에서 한 번 설명합니다. 이 페이지는 나머지 절반, 즉 각 provider의 렌더링된 출력에서 레이블이 들어가는 위치를 다룹니다.
aggrega.ai/recipe-uri는 소비하는 Recipe의 식별자가 아니라 FeatureRecipe 자체의 name:version으로 확인됩니다. 생성한 엔터티를 식별하기 위해 이 레이블을 읽는 다운스트림 도구는 component가 내보낸 출력과 FR이 내보낸 출력 모두에 대해 올바른 출처를 얻습니다.
Sync-wave 어노테이션
위의 aggrega.ai/sync-wave 키는 다운스트림 도구가 적용 순서를 정하기 위해 읽는 sync-wave 어노테이션과 짝을 이룹니다. compose에서 이 키는 레이블이며 셀렉터 쿼리를 위해 wave 값을 노출합니다. helm과 helm-chart에서는 어노테이션이며, 짝을 이루는 어노테이션은 각 도구가 관례적으로 읽는 위치에 그 값을 드러냅니다.
| 어노테이션 | 내보내기 | 사용처 |
|---|---|---|
argocd.argoproj.io/sync-wave | helm은 자신이 렌더링하는 모든 Kubernetes 리소스에, helm-chart는 $import:로 로드된 각 아티팩트에 — 기여하는 경계에서 syncWave가 0이 아닌 경우 | ArgoCD의 sync-wave 순서 지정 |
helm.sh/hook-weight | helm만 해당, syncWave가 0이 아닐 때 이미 helm.sh/hook 어노테이션을 가진 차트 템플릿 매니페스트에 | hook 단계 내에서의 Helm hook-weight 순서 지정 |
helm.sh/hook-weight 내보내기는 경로에 따라 달라집니다
차트 작성자가 알아 두어야 할 미묘한 점이 있습니다. helm.sh/hook-weight는 차트 템플릿 경로, 즉 Helm SDK를 통해 렌더링되는 차트의 templates/ 디렉터리를 거쳐 렌더링된 매니페스트에만 출력됩니다. 아티팩트 경로(helm provider에서는 Recipe의 artifacts: 블록의 모든 항목으로, 인라인 콘텐츠이든 $import:로 로드된 것이든 상관없으며, helm-chart에서는 $import:로 로드된 항목)를 통해 생성된 Manifests는 argocd.argoproj.io/sync-wave 어노테이션과 전체 출처 레이블 세트를 갖지만, 아티팩트에 helm.sh/hook 어노테이션이 있더라도 helm.sh/hook-weight는 받지 않습니다.
이 구분은 구조적인 것입니다. helm.sh/hook과 helm.sh/hook-weight는 차트 템플릿 hook 리소스에 적용되는 Helm 런타임 순서 지정 기본 요소입니다. Recipe 작성자의 아티팩트는 Recipe 계층에서 선언되는 추가 리소스이며, 기본적으로 Helm의 hook 수명 주기에 참여하지 않습니다.
hook 리소스에 Helm hook-weight 순서 지정이 필요하다면, 해당 리소스를 artifacts: 항목이 아니라 helm provider가 렌더링하는 Recipe의 source: 디렉터리 아래 차트 템플릿으로 작성하십시오. helm-chart 서브차트의 템플릿은 작성된 그대로 복사되며 두 어노테이션 중 어느 것도 받지 않습니다. 차트 템플릿은 기여하는 경계의 syncWave 값에 맞는 argocd.argoproj.io/sync-wave와 helm.sh/hook-weight를 모두 받습니다.
작성 예시
경계 수준의 배치 및 레지스트리 구성:
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}컴포넌트별 재정의(같은 어노테이션 키에서는 컴포넌트가 경계보다 우선합니다):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereAggregate 측 어노테이션 캐스케이드
어노테이션은 Aggregate 작성 영역에도 존재합니다. 서브시스템 스코프(spec.subsystems.<name>.annotations)와 컴포넌트 인스턴스 스코프(spec.subsystems.<name>.components.<name>.annotations, 또는 최상위 컴포넌트의 경우 spec.components.<name>.annotations)입니다. Aggregate 측 캐스케이드는 Developer가 작성한 어노테이션을 서브시스템 트리를 따라 포함된 컴포넌트까지 전달합니다.
캐스케이드 규칙
서브시스템 수준 어노테이션은 해당 서브시스템 하위 트리의 모든 중첩 서브시스템과 모든 포함된 컴포넌트로 전파됩니다. 더 가까운 수준의 어노테이션은 키 단위로 바깥 수준의 어노테이션을 재정의합니다. 컴포넌트 수준 어노테이션은 같은 키에 대해 상속된 서브시스템 수준 어노테이션을 재정의하며, 형제 키나 형제 컴포넌트에는 영향을 주지 않습니다.
스코프에서 어노테이션 키는 다음 세 가지 상태 중 하나에 있습니다.
- 키 없음 — 해당 스코프는 이 어노테이션에 대해 값을 선언하지 않습니다. 중첩 서브시스템과 포함된 컴포넌트는 상위 스코프의 바인딩을 상속합니다.
- 문자열 값 — 해당 스코프가 값을 선언합니다. 중첩 서브시스템과 포함된 컴포넌트는 자체 값을 선언하거나 옵트아웃하지 않는 한 이 값을 상속합니다.
- 명시적 YAML
null— 해당 스코프가 자신의 하위 트리에서 이 키에 대해 상속된 바인딩을 제거합니다. 형제 컴포넌트와 형제 서브시스템은 독립적인 상속을 유지하며, 옵트아웃한 스코프의 하위 트리만 바인딩을 잃습니다.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideAggregate에서 선언된 Provider 어노테이션
위 매트릭스의 키는 Aggregate를 통해서도 캐스케이드되며, 프로바이더는 캐스케이드가 각 컴포넌트에 남긴 값을 적용합니다. 서브시스템의 aggrega.ai/namespace는 그 아래의 모든 컴포넌트의 배치 위치를 정하고, 컴포넌트 인스턴스 자신의 값은 대신 그 컴포넌트의 배치 위치를 정합니다. Aggregate가 가져오는 모듈은 자체 캐스케이드를 가집니다. 그 서브시스템과 컴포넌트 인스턴스는 모듈 자신의 컴포넌트에 도달하며, 가져오는 쪽 Aggregate가 선언한 어떤 것도 모듈 안으로 들어가지 않습니다.
Release는 모든 키에서 Aggregate 위에 놓입니다. Release가 컴포넌트에 대해 키를 설정한 경우(그 경계에서든 컴포넌트 자신의 항목에서든) Release의 값이 적용되고, 설정하지 않은 경우 Aggregate의 값이 적용됩니다. 두 쪽은 키 단위로 겹쳐지므로, aggrega.ai/namespace만 설정하는 Release는 Aggregate가 선언한 aggrega.ai/image-registry를 그대로 유효하게 둡니다.
Release의 명시적 null은 Release 자신의 값만 철회합니다. aggrega.ai/namespace: null을 쓴 컴포넌트 항목은 그 Release 경계가 넘겨주었을 네임스페이스를 제거하며, 그러면 컴포넌트는 자신의 Aggregate가 선언한 값을 받습니다. Aggregate도 선언하지 않았다면 값을 받지 않습니다. Release는 Aggregate가 선언한 값을 제거할 수 없으며, 그 위에 자신의 값을 설정할 수만 있습니다.
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name은 이 범위 밖에 있는 유일한 키입니다. 이 키는 여러 컴포넌트로 조립되는 엄브렐라 차트의 이름을 지정하므로, 컴포넌트의 어노테이션이 아니라 항상 그 차트에 기여하는 Release 경계에서 읽힙니다.
Recipe 또는 FeatureRecipe 템플릿은 어노테이션 버킷을 이름으로 읽습니다. .context.annotations.aggregate, .context.annotations.release, .context.annotations.catalog는 각각 해당 쪽이 쓴 내용을 담습니다. 따라서 한 버킷에서 배치 키를 읽는 템플릿은 그 쪽의 값만 봅니다.
측(side)과 필러(pillar)의 분할
Aggregate-as-Authoring-Surface 불변 조건은 Aggregate 측 어노테이션을 values 필러로 제한합니다. Manifest 어노테이션 바인딩은 maps.infra(Release 측 라우팅) 또는 maps.values(Aggregate 측 라우팅) 아래에 라우팅 경로를 선언합니다. 바인딩이 maps.infra 경로만 선언하는 Aggregate 측 어노테이션은 어노테이션 키, 라우팅된 필러, 작성 측을 명시하는 명확한 진단과 함께 빌드를 중단합니다. Release 측에도 대칭 규칙이 적용됩니다. Release 측 어노테이션은 maps.infra를 통해서만 라우팅할 수 있으며, values 전용 바인딩에 대한 Release 측 어노테이션은 대응되는 오류를 발생시킵니다. 각 진단은 어노테이션 값이 작성된 문서의 도메인으로 분류되므로(Aggregate에서는 [DEVELOPER_ERROR], Release에서는 [OPS_ERROR]), 머리말이 열어야 할 영역을 알려 줍니다.
두 필러 모두에 경로를 선언하는 바인딩은 각 패스에서 측과 호환되는 부분집합을 라우팅합니다. Aggregate 측 어노테이션은 values 필러 경로만, Release 측 어노테이션은 infra 필러 경로만 발생시킵니다. 측 간 조합(Aggregate의 values, Release의 infra)은 (Component, Feature) 쌍마다 두 필러가 모두 채워진 Feature 첨부 하나를 생성하며, 리프별 출처 정보가 각 리프를 어느 측이 제공했는지 기록합니다.
작성 예시 — 서브시스템 어노테이션이 values로 라우팅됨
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0어노테이션 확장 후 api와 worker 모두 values.pool 필드가 "shared-pool"인 합성된 feature.myco/db-pool Feature 첨부를 가집니다. 빌드 그래프(aggrega validate --release <release> --ir-graph)는 각 리프를 origin: annotation, side: aggregate, annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool과 함께 기록합니다.
구조화된 어노테이션 값
구성 가능한 필드가 여러 개인 Feature에서는 하나의 어노테이션 키로 여러 필드의 값을 한꺼번에 전달하고 싶어집니다. 구조화된 어노테이션 형식을 사용하면 하나의 키가 한 번의 선언으로 여러 바인딩 경로에 라우팅될 수 있습니다:
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100Manifest 바인딩은 네 하위 키 모두의 라우팅을 필러별로 묶인 maps: 목록에 선언합니다:
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connections어노테이션 값의 형태는 다음 세 가지 중 하나입니다:
- 스칼라 문자열 — 단일 값입니다. 바인딩은 전체에서 정확히 하나의 경로를 선언해야 하며, 스칼라는 그 경로로 라우팅됩니다.
- 구조화된 객체 — 하위 키에서 하위 값으로의 맵입니다. 각 하위 키의 경로는 바인딩의
maps.infra또는maps.values목록에 있어야 하며, 하위 값은 선언된 필러에서 지정된 Feature 스키마 필드로 라우팅됩니다. - 명시적 YAML
null— 이 캐스케이드 스코프에서 상속된 바인딩 전체를 옵트아웃합니다.
구조화된 값 안의 각 하위 키는 바인딩의 maps 목록에 대해 독립적으로 해석됩니다. maps.infra와 maps.values 어디에도 없는 하위 키는 문제가 된 하위 키와 선언된 경로를 명시하는 명확한 오류와 함께 빌드를 중단시킵니다.
구조화된 값의 캐스케이드 병합
구조화된 어노테이션은 하위 키 단위의 깊은 병합으로 캐스케이드됩니다. 자식 캐스케이드 스코프의 어노테이션은 부모의 어노테이션과 하위 키별로 병합되며, 더 가까운 수준이 하위 키 단위로 부모를 재정의합니다:
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parent캐스케이드 이후의 유효 어노테이션:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }— 이 스코프에서read_replicas는 옵트아웃됨
값이 스칼라인 자식 캐스케이드 수준은 (구조화된 부모에 대해) 병합되지 않고 전체를 대체합니다. 캐스케이드 수준 간의 형태 불일치는 더 가까운 수준의 값을 우선하여 해결되며, 컴파일러는 형태 불일치에 대해 경고하지 않습니다.
전체 값 null과 하위 키별 null
캐스케이드에는 서로 다른 단위의 두 가지 옵트아웃 메커니즘이 있습니다:
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: null이 컴포넌트에서 어노테이션 바인딩 전체가 억제되며, 이 스코프에서는 이 어노테이션 키로부터 합성 Feature 연결이 생성되지 않습니다. 형제 컴포넌트는 상속된 바인딩을 유지합니다.
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: null어노테이션은 이 스코프에서 계속 기여하지만 read_replicas 하위 키는 억제됩니다. 다른 하위 키(이 스코프에서 선언되었거나 부모 캐스케이드 수준에서 상속된 것)는 그대로 유지됩니다.
작성 지침: 스코프에서 어노테이션 기반 Feature 연결을 비활성화하려면 전체 값 null을 사용합니다. 어노테이션 기여의 대부분은 유지하면서 하나 이상의 특정 필드만 억제하려면 하위 키별 null을 사용합니다.
하위 키별 측면-필러 분할
어노테이션 값이 구조화된 경우 Aggregate-as-Authoring-Surface 불변 조건은 하위 키별로 적용됩니다. 각 하위 키의 필러(바인딩의 maps 선언에 따름)는 작성 측면과 호환되어야 합니다:
- Aggregate 측 어노테이션은
maps.values로 라우팅되는 하위 키만 가질 수 있습니다. - Release 측 어노테이션은
maps.infra로 라우팅되는 하위 키만 가질 수 있습니다.
호환되지 않는 필러로 라우팅되는 하위 키는 해당 하위 키와 필러를 명시하는 명확한 오류와 함께 빌드를 중단시킵니다. 오류 체인은 중단하기 전에 어노테이션별로 호환되지 않는 하위 키를 모두 수집하므로, 운영자는 수정-재빌드를 반복하지 않고 빌드 한 번에 모든 문제를 확인할 수 있습니다.
하위 키별 타입 검증
각 하위 키의 런타임 값은 라우팅된 필러에서 대상 Feature의 spec.schema에 선언된 타입에 대해 검증됩니다. 지원되는 선언 타입은 string, integer, number, boolean, object, array, null입니다. YAML 타입이 스키마의 선언 타입과 일치하지 않는 하위 값은 하위 키, 실제 타입, 선언 타입을 명시하는 명확한 오류와 함께 빌드를 중단시킵니다.
타입 일치는 엄격하며 강제 변환은 없습니다. 정수 타입 스키마 필드에 대한 문자열 "20"은 빌드를 중단시킵니다. 작성자는 Feature 스키마에 타입을 올바르게 선언하거나 문자열로 그대로 전달되는 스칼라 어노테이션을 사용합니다.
엄격한 검증을 위한 작성 수단. Feature의 spec.schema에 type이 선언되지 않은 속성은 중첩 맵을 포함한 모든 런타임 값 형태를 허용합니다. 스키마가 제약을 선언하지 않으면 빌드도 제약을 만들어 내지 않습니다. 엄격한 하위 키별 타입 검증을 원하는 작성자는 spec.schema의 모든 속성에 type을 선언합니다. 다운스트림의 FeatureRecipe 렌더링 계층은 어노테이션 기여가 어떤 형태이든 처리합니다.
측면 간 합성
Aggregate 측 어노테이션(values 하위 키)과 Release 측 어노테이션(infra 하위 키)이 모두 동일한 Component의 동일한 Feature 연결을 대상으로 하면, 빌드는 기여를 두 필러가 모두 채워진 단일 Feature 연결로 병합합니다. 리프별 출처 정보는 각 하위 키의 소스를 기록합니다. 합성된 연결은 Aggregate 작성 위치에 귀속된 values.db_name과 Release 작성 위치에 귀속된 infra.pool_size를 가집니다.
측면 간 합성 패턴은 개발자 의도 필드와 운영자 크기 조정 필드가 섞인 Features의 표준 작성 형태입니다. Aggregate는 인지적 선택(어떤 데이터베이스인지, 애플리케이션 수준에서 복제본이 몇 개인지)을 선언하고, Release는 물리적 크기(풀 크기, 인프라 수준의 연결 수)를 선언합니다. 하나의 Manifest 바인딩이 단일 maps 선언 집합으로 이 둘을 묶습니다.
관련 참조 문서
- Provider 아키텍처 — 프로바이더 플러그인 아키텍처와 프로바이더 렌더링 Plugin의 역할.
- ../entities/release.md — 경계 및 컴포넌트 어노테이션이 위치하는 Release 작성 표면.
- ../entities/aggregate.md — 서브시스템 및 컴포넌트 수준 어노테이션이 위치하는 Aggregate 작성 표면.
- ../entities/manifest.md — 어노테이션 바인딩이
maps:라우팅을 선언하는 Manifest의mappings.features.annotations맵. - ../../architecture/11-governance-and-compliance.md — 작성자가 제어하는 어노테이션을 보완하는 컴파일 시점 출처 기록에 관한 설명.