콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

레이블과 어노테이션

Aggrega 엔터티는 구조적으로 유사한 두 가지 메타데이터 메커니즘인 metadata.labels와 metadata.annotations를 가지며, 그 외에도 경계 캐스케이드 위치와 기능 부착 위치에 흩어져 있는 어노테이션 보유 필드를 가집니다. 서로 다른 여섯 위치에서 어노테이션/레이블 내용을 작성하거나 보유하며, 각 위치는 캐스케이드 규칙, 소비자, 접두사 관례가 서로 다릅니다. 이 페이지는 이러한 위치를 한곳에 정리하고, 런타임 템플릿 컨텍스트가 노출하는 세 가지 의미 버킷을 정의하며, 작성자가 따라야 할 접두사 규율을 제시하고, 다섯 가지 Feature 부착 위치를 나란히 정리하여 더 넓은 레이블/어노테이션 용어와 함께 볼 수 있도록 합니다.

애너테이션과 레이블을 담는 여섯 가지 위치

작성자는 여섯 가지 서로 다른 위치에서 레이블과 애너테이션을 접합니다. 각 위치는 범위, 캐스케이드 규칙, 소비자가 서로 다릅니다.

#보고 위치범위캐스케이드 규칙주요 소비자
1카탈로그 엔티티 metadata.labels엔티티별 식별 정보(Component, Feature, Aggregate)인스턴스로 캐스케이드되지 않으며, 카탈로그 엔티티 자체에 실립니다Components와 Features에는 aggrega search -l. Aggregate의 레이블은 그 문서에 담겨 있으며 이를 읽는 명령은 없음
2Component metadata.labels(내재적)Component 인스턴스별 속성(component.aggrega.ai/type 등)label-transform 변경이 적용된 후 IR 노드별 .context.labels로 캐스케이드됩니다셀렉터 매칭(usesSchema selector: 선언, 합성된 JSON Schema에서는 x-aggrega-selector:로 실림), Recipe 템플릿 로직
3Component metadata.annotationsArchitect가 작성하는 Component 인스턴스별 특성IR 노드별 .context.annotations.catalog 버킷으로 캐스케이드됩니다거버넌스 판정 역할(내재적 특성 정책), Recipe 템플릿 로직
4Aggregate / Subsystem annotations:Aggregate 측 인지적 메타데이터IR 노드별 .context.annotations.aggregate 버킷으로 캐스케이드됩니다인지적 라우팅을 위한 Recipe valuesMapping:
5Release 경계 annotations:aggrega.ai/* 잘 알려진 애너테이션을 포함한 Ops 측 물리적 메타데이터IR 노드별 .context.annotations.release 버킷으로 캐스케이드됩니다Providers(helm은 aggrega.ai/namespace를 읽고, compose는 같은 키에서 네트워크 이름을 도출합니다), 경계를 넘는 라우팅을 위한 FeatureRecipe injectMapping:
6Manifest features.annotations 바인딩애너테이션 기반 Feature 부착을 위한, 필러별로 묶인 하위 키 라우팅(maps.infra / maps.values)을 갖춘 애너테이션 키 → Feature 유형 바인딩해석 단계의 애너테이션 확장 하위 단계가 Release 경계(바깥에서 안쪽으로)와 Aggregate 서브시스템(바깥에서 안쪽으로)을 순회합니다. 컴포넌트별 재정의와 값 전체 / 하위 키별 null 옵트아웃이 적용되며, 측면 대 필러 검사가 작성 측면마다 어떤 필러가 작동할지를 결정합니다애너테이션 기반 Feature 확장(합성 Feature 부착이며, IR 그래프에 origin: annotation으로 기록됨)

위치 4와 5는 같은 YAML 형태(캐스케이드 경계의 annotations: 맵)를 공유하지만 서로 다른 IR 버킷으로 캐스케이드됩니다. 이 버킷 구분이 런타임이 노출하는 핵심 규칙입니다. 위치 6은 구조적으로 별개입니다. Aggregate / Release 내용이 아니라 Manifest 엔티티에 있으며, 그 소비는 애너테이션 기반 확장 패스에 의해 제어됩니다.

세 버킷 .context.annotations.* 의미 체계

렌더러가 Recipe 템플릿을 평가할 때, 노드별 .context.annotations 필드는 이름이 붙은 세 개의 버킷을 담습니다. 각 버킷은 애너테이션 이름을 키로 하는 평면 string → string 맵이며, 버킷은 누가 애너테이션을 작성했고 그 의도가 무엇인지를 결정합니다.

  • .context.annotations.release — Release 경계 애너테이션(보고 위치 5). 물리적 현실을 관리하는 데 사용되며, 렌더러는 적절한 경우 이를 infra: 필드로 라우팅합니다. aggrega.ai/* 잘 알려진 애너테이션은 이 버킷에 있습니다.
  • .context.annotations.catalog — Component 메타데이터 애너테이션(보고 위치 3). Architect가 작성하는 불변의 고유 특성으로, 주로 Wasm 정책 플러그인이 소비합니다.
  • .context.annotations.aggregate — Aggregate 서브시스템 애너테이션(보고 위치 4). 인지적 메타데이터로, 렌더러는 적절한 경우 이를 values: 페이로드로 라우팅합니다.

세 버킷의 분리는 사회 계약입니다

컴파일러는 버킷 경계를 강제하지 않습니다. 세 버킷은 평면 string → string 형태를 공유하며, Recipe의 템플릿은 세 버킷을 모두 읽을 수 있고, Release 경계 애너테이션이 인지적 메타데이터 필드로 해석되거나 카탈로그 애너테이션이 infra:로 라우팅되는 것을 막는 것은 없습니다. 이 분리는 컴파일러의 보장이 아니라 작성 규율입니다.

규율의 목표 — 버킷이 표현하도록 의도된 것:

  • release = “이 컴포넌트가 실행되는 위치, Ops가 관리”
  • catalog = “이 컴포넌트가 무엇인지, Architect가 작성”
  • aggregate = “이 컴포넌트가 하는 일, Developer가 작성”

작성자가 분리를 지키면 다운스트림 도구는 올바른 관심사에 대해 올바른 버킷을 읽을 수 있습니다. 작성자가 이를 어기면(예: Release 파일이 편리하다는 이유로 인지적 메타데이터를 release 애너테이션에 넣는 경우) 런타임은 여전히 동작하지만 버킷의 의도가 흐려집니다.

린터 소켓 — 버킷 간 읽기 표시

린터 플러그인(대역 외 권고, 배치 기준은 plugins/plugin-contract.md 참조)은 Recipe의 템플릿이 라우팅되는 필드와 의도가 맞지 않는 버킷에서 값을 가져오는 버킷 간 읽기를 표시할 수 있습니다. 기준은 다음과 같습니다.

  • values: 필드를 채우기 위해 .context.annotations.release를 읽는 경우 — 표시(인지적 메타데이터는 aggregate 버킷에서 와야 합니다).
  • infra: 필드를 채우기 위해 .context.annotations.aggregate를 읽는 경우 — 표시(물리적 메타데이터는 release 버킷에서 와야 합니다).
  • values: 또는 infra:를 채우기 위해 .context.annotations.catalog를 읽는 경우 — 일반적으로 권고만 함(카탈로그 애너테이션은 고유 특성이며, 이를 필러로 라우팅하는 것은 드물지만 항상 잘못된 것은 아닙니다).

게시용 린터에는 이 기준에 대한 규칙이 없으며 빌드도 이를 검사하지 않습니다. 직접 만든 린터 플러그인은 aggrega lint가 실행하는 린터 소켓을 통해 검사할 수 있습니다. 이 규율은 버킷 의도 관례를 따르는 검토자와 작성자에 의해 유지됩니다.

접두사 규율

어노테이션과 레이블 키는 일관된 <namespace>/<name> 형태를 따릅니다. 아래의 접두사 계열은 각 계열 아래에서 누가 키를 작성하는지, 각 계열이 어떻게 유지되는지를 설명합니다. 하나의 접두사는 예약되어 있으며, Manifest 바인딩이나 Recipe 출력 레이블이 그 안에서 새 키를 주장하면 빌드가 중단됩니다. 나머지는 카탈로그 관례이며, 키를 거부하는 장치가 없습니다. 둘의 차이는 빌드가 중단되는지 여부이므로, 다른 열보다 가운데 열을 먼저 읽으십시오.

접두사여기서 키를 작성하는 주체유지 방식목적예시
aggrega.ai/Aggrega 플랫폼 전용예약되어 있으며 강제됩니다. 이 접두사의 키는 플랫폼이 정의하며, 작성자는 플랫폼이 정의한 키를 씁니다 — 예를 들어 Release 경계의 aggrega.ai/namespace가 그렇습니다. 접두사 안에서 새 키를 선언하면 빌드가 중단됩니다. 접두사 바로 아래에 두는 Manifest features.annotations 바인딩도, outputLabels: 또는 outputComponentLabels:에서 그 아래에 두는 Recipe 출력 레이블 키도 마찬가지입니다. 그 아래에 작성되었지만 플랫폼이 정의하지 않은 어노테이션은 거부되지 않습니다. 빌드는 이를 그대로 전달하며, 그것이 Release에 있는 경우 이를 처리하지 않는 대상은 경고로 그 사실을 알립니다. errors/fatal-halts.md의 “A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Manifest 어노테이션 바인딩이 예약된 접두사를 선언함)” 및 “An output-label key uses a reserved namespace (출력 레이블 키가 예약된 네임스페이스를 사용함)“를 참조하십시오.provider가 직접 소비하는 플랫폼 고유 어노테이션aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/공식 표준 라이브러리관례. 여기서는 어떤 키도 거부되지 않습니다. 이 어휘는 검사가 아니라 합의에 따라 표준 라이브러리에 속합니다.Manifest features.annotations에 바인딩되는 Feature 어노테이션 단축키feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/공식 표준 라이브러리관례. 여기서는 어떤 키도 거부되지 않습니다.Component 고유 특성 레이블(component.aggrega.ai/type 셀렉터 키가 여기에 있습니다)component.aggrega.ai/type
aggregate.aggrega.ai/공식 표준 라이브러리관례. 여기서는 어떤 키도 거부되지 않습니다.Aggregate 모듈 수준 식별 레이블aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/공식 표준 라이브러리, 그리고 자체 카탈로그의 엔터프라이즈관례. 여기서는 어떤 키도 거부되지 않습니다.기능(capability) 레이블 — usesSchema 셀렉터나 Feature의 appliesTo가 구분 기준으로 삼는 동작 차원입니다. <role>은 해당 차원이 속한 관심사를 나타냅니다. 이는 component 역할이거나, 여러 역할이 공유하는 횡단 관심사입니다.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/엔터프라이즈 / 커뮤니티개방. 직접 관리하는 도메인 아래에서 작성합니다.사용자 정의 어노테이션과 레이블acme.com/billing-tier, corp/cost-center

사용자 정의 어노테이션을 작성할 때는 직접 관리하는 도메인(일반적으로 역방향 DNS 형식)을 사용합니다. 하위 접두사 없이 aggrega.ai/ 바로 아래에 작성하는 것은 플랫폼용으로 예약되어 있으며, Manifest의 features.annotations 바인딩도 aggrega.ai/ 바로 아래의 키를 바인딩할 수 없습니다. entities/manifest.md의 “aggrega.ai/ Prefix Reservation”을 참조하십시오.

기능 접두사 이름 짓기

기능 키는 <role>.aggrega.ai/<dimension>이며, 판단이 필요한 부분은 <role>입니다. 세 가지 규칙이 이를 다루며, 첫 번째 규칙이 가장 흔히 거꾸로 적용됩니다.

  • 처음 그것을 갖게 된 component 종류가 아니라 관심사의 이름을 붙입니다. 어떤 차원이 여러 component 종류가 공유하는 것을 설명한다면, 접두사는 공유된 관심사를 이름으로 삼아, 다음에 그것을 갖게 되는 종류가 병렬 어휘를 새로 만들지 않고 기존 어휘를 재사용하도록 합니다. component.aggrega.ai/hosting은 관심사이며 — 기반 리소스를 누가 운영하는가 — 데이터베이스와 모델 API를 같은 말로 설명합니다. dataplane.aggrega.ai/*는 트래픽 경로상의 위치를 나타내므로 프록시, 인그레스 게이트웨이, 서비스 메시가 같은 방식으로 자신을 설명합니다. 실제로 한 역할에만 해당하는 차원은 model.aggrega.ai/capability처럼 그 역할의 이름을 씁니다.
  • 접두사에는 하이픈 없는 소문자 단어 하나를 씁니다. 하이픈은 복합어가 자연스럽게 읽히는 <dimension> 쪽에 씁니다(request-mirroring, data-class, upstream-licensing).
  • 차원은 셀렉터가 필요로 할 때 추가되며, 차원이 선언하는 각 값에는 그 값을 갖는 component가 있습니다. 여기의 모든 단어는 카탈로그 작성자가 배워야 하고 Feature 작성자가 마주칠 수 있는 단어이므로, 차원은 usesSchema나 appliesTo가 실제로 묻는 무언가를 구분할 때에만 자리를 얻습니다. 어떤 component도 갖지 않는 값은 값이 없는 것보다 나쁩니다. 그 값을 지정한 셀렉터는 파싱되지만 아무것도 일치하지 않고 아무것도 보고하지 않습니다. 따라서 카탈로그가 입증할 수 없는 값은 component가 그 값을 가질 때까지 어휘에서 제외됩니다. 값이 제품의 속성이 아니라 자산(estate)이 자체 component를 어떻게 사용하는지에 대한 진술인 키는 예외이며, compliance.aggrega.ai/data-class가 그 경우입니다. component의 데이터가 어떤 등급인지는 자산이 그 component를 어떻게 사용하는지에 달려 있으므로, 어떤 표준 라이브러리 Component도 그 값을 갖지 않으며 어떤 표준 라이브러리 소켓이나 Feature도 그 값으로 선택하지 않습니다. 이 키와 값은 자산의 자체 Components와 자산이 연결하는 정책이 하나의 표기를 공유하도록 선언됩니다. 값을 지정한 셀렉터나 정책은 Components가 그 값을 갖는 카탈로그에서만 일치합니다. policy-data-class-route는 그러한 Component 하나와 그것을 읽는 정책을 보여 줍니다.

예약과 플랫폼 정의 키는 같은 것이 아닙니다

예약은 접두사만 있는 aggrega.ai/ 루트에 적용됩니다. 그 아래의 모든 <scope>.aggrega.ai/ 네임스페이스는 플랫폼이 소유하지 않는 별도의 키 공간이며, 이것이 카탈로그 어휘를 확장 가능하게 유지합니다. 엔터프라이즈 카탈로그는 빌드가 기록하는 어떤 것과도 충돌하지 않고 acme.aggrega.ai/team을 작성할 수 있습니다.

그럼에도 이러한 개방 네임스페이스 안의 몇몇 키는 플랫폼이 정의하고 빌드가 읽지만, 그렇다고 해당 네임스페이스가 예약되는 것은 아닙니다.

  • **component.aggrega.ai/type**은 모든 Component의 metadata.labels에 필수이며, 고정된 값 집합 중 하나를 취합니다. 셀렉터는 이 키로 일치를 판단하며, 컴파일러는 어떤 값을 갖는지에 따라 분기하지 않습니다.
  • Component의 metadata.annotations에 작성되는 **features.aggrega.ai/requiredType.<label>**은 지정된 유형의 Feature가 반드시 연결되어야 함을 선언합니다. 빌드는 각 노드의 최종 연결 집합에 대해 이 요구를 검사하며, 이를 충족하는 것이 없으면 중단됩니다. errors/fatal-halts.md의 “Required feature not attached (필수 feature가 연결되지 않음)”를 참조하십시오. 복수형에 주의하십시오. features.aggrega.ai/는 별도의 네임스페이스이며, 위 표에서 Manifest 바인딩 단축키를 담는 단수형 feature.aggrega.ai/와는 다릅니다.

차이는 이렇게 이해하면 됩니다. 예약된 접두사는 그 안에서 정의하려는 키를 거부하는 반면, 플랫폼 정의 키는 빌드가 알고 있는 이름 있는 키 하나로, 그 외에는 자유롭게 작성할 수 있는 네임스페이스에 놓여 있습니다. component.aggrega.ai/, features.aggrega.ai/ 등의 아래에 있는 그 밖의 모든 키는 빌드가 해석하지 않고 전달하는 메타데이터입니다.

Component의 metadata.annotations에 있는 그러한 키 중 하나는 빌드가 아니라 표준 게시 린터가 읽습니다. **observability.aggrega.ai/metrics-credential**은 제품의 메트릭이 어떻게 인증하는지를 나타냅니다. none은 자격 증명 없이 제공됨을, target-key는 Component가 모든 호출자에게 요구하는 키를 사용함을, separate-token은 별도의 토큰을 사용함을 뜻합니다. 빌드는 이를 다른 어노테이션과 마찬가지로 전달합니다. 린터는 이를 읽어 스크레이프 연결의 자격 증명을 대상의 호출자 키와 비교할지 결정하며, Component가 선언하는 metrics_credential_required provides 키와 일치하는지 확인합니다. cli/aggrega-lint.md의 “The discipline rules”를 참조하십시오.

렌더링된 출력에 내보내는 출처 레이블

provider가 소비하는 인바운드 어노테이션 외에도, Aggrega는 helm provider가 렌더링하는 모든 Kubernetes 매니페스트와 내보낸 모든 compose 서비스에 출처 레이블을 내보내며, helm-chart provider는 $import:로 로드하는 각 아티팩트에 helm provider와 같은 방식으로 동일한 레이블 집합을 기록합니다. 이 레이블 집합을 통해 다운스트림 도구(비용 대시보드, 관측성 스택, GitOps 컨트롤러)는 런타임 리소스를 그것을 생성한 카탈로그 콘텐츠로 거슬러 귀속시킬 수 있습니다. helm-chart 하위 차트 자체의 템플릿은 작성자가 작성한 그대로 복사되므로, 그 작성자가 작성한 레이블을 그대로 가집니다.

helm과 compose provider가 내보내는 집합입니다. helm에서는 표에 나온 대로 세 개의 키가 레이블이 아니라 어노테이션으로 기록됩니다:

레이블출처항상 내보내는지 여부
app.kubernetes.io/nameComponent 식별자 — 작성한 이름, 또는 가져온 Aggregate가 제공하는 컴포넌트의 경우 모듈 구분자를 풀어 쓴 정규화된 이름(아래 참조), 또는 FeatureRecipe가 내보내는 리소스의 경우 해당 연결에 대해 도출된 식별자Kubernetes 매니페스트에서는 예, compose 서비스에서는 내보내지 않음(표준 레이블이 K8s 전용이므로)
aggrega.ai/component-idComponent 식별자 — 작성한 이름, 또는 가져온 Aggregate가 제공하는 컴포넌트의 경우 모듈 구분자를 풀어 쓴 정규화된 이름(아래 참조), 또는 FeatureRecipe가 내보내는 리소스의 경우 해당 연결에 대해 도출된 식별자예
aggrega.ai/recipe-uri생성한 Recipe(FR이 내보낸 리소스의 경우 생성한 FeatureRecipe)의 <recipe-name>:<recipe-version>생성한 엔터티에 이름과 버전이 모두 설정된 경우. helm에서는 어노테이션
aggrega.ai/boundary-pathcomponent가 라우팅된 경계 경로경계 경로가 비어 있지 않은 경우. helm에서는 어노테이션
aggrega.ai/aggregate-nameAggregate metadata.name설정된 경우
aggrega.ai/compiler-version빌드 시점에 기록된 컴파일러 버전설정된 경우
aggrega.ai/provider리소스를 렌더링한 provider(helm, helm-chart, compose)예
aggrega.ai/provider-version해당 provider의 버전예
aggrega.ai/environmentRelease metadata.environment예 — 모든 Release가 이를 선언함
aggrega.ai/sync-wave경계별 syncWave 정수로, GitOps 도구가 리소스를 적용하는 순서0이 아닌 경우. helm에서는 argocd.argoproj.io/sync-wave 옆에 기록되는 어노테이션

집합체 이름, 환경, 컴파일러 버전, 공급자의 이름과 버전은 사용자나 빌드가 선택한 문자열이며, 이들 중 어느 것도 기록되는 위치에서 Kubernetes 레이블 값 규칙을 따르도록 요구되지 않습니다. helm에서는 값이 이미 유효한 레이블 값인 경우 — 문자, 숫자, -, _, .로 이루어지고, 양 끝이 문자 또는 숫자이며, 최대 63자 — 이러한 각 레이블은 작성된 그대로의 값을 담고, 그렇지 않으면 유효한 값으로 다시 쓴 값을 담으며, 원래 그대로의 값은 같은 키 아래에 어노테이션으로 추가됩니다. imported/flow라는 이름의 Aggregate에는 레이블 aggrega.ai/aggregate-name: imported-flow와 어노테이션 aggrega.ai/aggregate-name: imported/flow가 붙습니다. 이미 규칙에 맞는 값은 어노테이션을 추가하지 않습니다. Compose는 원래 그대로의 값을 레이블로 담습니다. 다시 쓰기 규칙은 providers/well-known-annotations.md “공급자가 내보내는 출처 레이블”에 설명되어 있습니다.

FeatureRecipe가 내보내는 리소스의 경우, aggrega.ai/component-id 값은 호스트 component의 이름이 아니라 연결로부터 구성됩니다. 이는 FeatureRecipe가 워크로드를 합성하든, 독립 아티팩트 집합을 내보내든, 작성자가 제공한 차트나 프래그먼트를 렌더링하든, 리소스를 전달하는 모든 방식에 적용됩니다. 따라서 식별자로 연결의 리소스를 선택하는 쿼리는 그 리소스를 모두 반환하며, 그중 어느 것도 호스트 component가 직접 내보낸 리소스와 구별되지 않는 일이 없습니다. 값이 구성되는 방식은 Feature가 연결된 위치에 따라 달라지며, 어느 경우든 결과는 유효한 Kubernetes 레이블 문자열입니다.

가져온 Aggregate가 제공하는 component의 경우, 식별자는 해당 component의 정규화된 이름이며 모듈과 component를 잇는 구분자는 풀어 쓰입니다. 예를 들어 data-layer.main-db는 data-layer-zdmain-db로 기록됩니다. 점은 리소스 이름이나 클러스터 주소에 안전하게 담을 수 있는 문자가 아니기 때문입니다. 구분자가 없는 작성한 이름은 바이트 단위 그대로 기록됩니다.

식별자는 리소스가 무엇에 속하는지를 나타냅니다. 이는 리소스가 무엇으로 불리는지와는 다른 질문이며, 한 가지 전달 방식에서는 두 질문의 답이 다릅니다.

  • FeatureRecipe가 워크로드를 합성하는 경우, Aggrega가 해당 리소스를 직접 구성하므로 이름도 식별자에 따라 붙입니다. 식별자는 레이블뿐 아니라 metadata.name, 셀렉터 레이블, 내보낸 파일 이름에도 반영됩니다. 이는 레이블일 뿐 아니라 클러스터 내부의 이름이기도 합니다.
  • FeatureRecipe가 작성자가 작성한 차트나 프래그먼트를 전달하는 경우, 이름은 그것을 작성한 사람의 몫입니다. 해당 템플릿이 렌더링될 때 기준이 되는 Helm 릴리스 이름과, 그 렌더링이 내보내는 파일의 접두사는 호스트 component의 것으로 유지됩니다. 차트는 흔히 리소스 이름을 릴리스 이름에 따라 붙이므로, 이를 바꾸면 차트 자체가 선언한 리소스의 이름이 이미 배포된 클러스터에서 차트와 무관한 이유로 바뀌게 됩니다. 레이블은 여전히 연결 자체의 식별자를 담으며, 이것이 연결의 리소스를 찾을 수 있게 해 줍니다.
  • Feature가 경계에 연결된 경우에는 대신 사용할 호스트 component 이름이 없으므로, 구성된 식별자가 레이블뿐 아니라 이름 지정의 기준도 됩니다.

어느 경우든 값은 작성한 부분들을 --로 이어 구성하며, 앞에는 둘 중 어느 경우인지 나타내는 고정된 시작부가 붙습니다. 사용되는 시작부는 두 가지이며, 직접 작성하는 component 식별자는 둘 중 어느 것으로도 시작할 수 없습니다. 이 덕분에 작성한 이름과 Aggrega가 구성한 이름이 서로 혼동되는 일이 없습니다.

Feature가 component에 연결된 경우, 구성 부분은 고정된 cfr 시작부, Feature가 연결된 component의 식별자, 그리고 연결에 사용된 키입니다. component api에 mon으로 연결된 Feature는 cfr--api--mon이 됩니다. 호스트 component가 값에 포함되는 이유는 하나의 Feature 이름을 여러 component에 연결하면 각 component에 별도의 리소스 집합을 내보내고, 각 집합에 고유한 식별자가 필요하기 때문입니다. mon을 api와 worker 모두에 연결하면 하나의 값이 아니라 cfr--api--mon과 cfr--worker--mon이 됩니다. 같은 이유로, 호스트 component와 정확히 같은 이름의 연결도 해당 component 자체의 값과 구별되는 값이 됩니다. mon에 연결된 mon은 cfr--mon--mon이 됩니다.

Feature가 경계에 연결된 경우(compose-bridge 게이트웨이 서비스가 대표적인 예입니다), 구성 부분은 고정된 bfr 시작부, 가장 바깥쪽부터 차례로 경계 경로의 각 세그먼트, 그리고 Feature가 연결된 이름입니다. bridge 경계에 있는 gateway라는 Feature는 bfr--bridge--gateway가 되고, prod/eu 경계에 있는 같은 Feature는 bfr--prod--eu--gateway가 됩니다.

값이 담을 수 없는 문자는 대체되지 않고 풀어서 기록됩니다. 그리고 이 값은 레이블이자 클러스터 안의 이름이기도 하므로, 모든 종류의 Kubernetes 리소스 이름이 허용하는 문자, 즉 소문자, 숫자, 하이픈으로 제한됩니다. 따라서 작성한 하이픈은 하이픈으로 남고 소문자나 숫자는 그대로 유지되며, 그 밖의 모든 문자(레이블 값은 허용하지만 리소스 이름은 거부하는 대문자 포함)는 짧은 이스케이프가 됩니다. my_zone이라는 이름의 어태치먼트는 my-zuzone을 기여하고, 어태치먼트 worker를 가진 컴포넌트 myApi는 cfr--my-zx000041pi--worker가 됩니다. 이 이스케이프된 값이 모든 대상에서 어태치먼트의 리소스에 레이블로 붙고 선택에 쓰이는 값이며, 어태치먼트가 합성하는 워크로드의 이름과 파일 이름의 기준이 되는 값이고, 경계 어태치먼트의 릴리스 이름이 파생되는 값입니다. 리소스 이름 규칙이 레이블만으로 풀어 쓸 문자에 더하는 것은 대문자뿐이므로, 어느 부분에도 대문자가 없는 합성 값(cfr--api--mon, bfr--prod--eu--gateway)은 레이블만으로 가질 값과 같습니다. 따라서 구별할 수 있는 두 어태치먼트는 이름을 어떻게 지었든, 경계가 얼마나 깊든 항상 두 개의 값이 됩니다. --는 어떤 작성 부분에도 포함될 수 없는 연속이므로, 부분 사이의 구분을 옮기면 값이 충돌하는 대신 바뀌기 때문입니다.

구성된 값의 최대 길이는 Aggrega가 가진 숫자가 아니라 대상이 정합니다. 리소스가 렌더링되는 대상에 질의하고, 그 대상이 허용할 때까지 값을 줄입니다. Kubernetes 레이블 값은 최대 63자이고, 같은 식별자에서 파생된 Helm 릴리스 이름은 더 엄격하게 제한되므로, 같은 연결이라도 대상에 따라 더 짧게 정해질 수 있습니다. 길이에 맞는 값은 구성된 그대로 내보내며, 이것이 일반적인 경우이자 표준 라이브러리 카탈로그의 모든 연결에 해당하는 경우입니다. 맞지 않는 값은 줄여집니다. 각 부분은 앞부분을 유지하고, 작성할 수 있는 어떤 이름에서도 생기지 않는 표식 뒤에 전체 식별자의 10자 다이제스트가 덧붙여집니다. 따라서 줄인 값은 줄인 값임을 알아볼 수 있으며, 길이에 맞았던 값으로 오인될 수 없습니다. 깊이 중첩된 gateway 연결은 bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e처럼 렌더링될 수 있습니다. 줄인 두 값이 겹칠 가능성은 매우 낮으며, 겹치는 경우 빌드는 두 값이 이름을 공유하도록 두지 않고 중단됩니다.

어떤 쌍이 중단되는지와 이를 분리하는 방법은 errors/fatal-halts.md의 “The same name is derived more than once inside the output(출력 내에서 같은 이름이 두 번 이상 파생됨)”을 참조하십시오.

FR이 내보낸 리소스의 aggrega.ai/recipe-uri는 이를 소비하는 Recipe의 식별자가 아니라 FeatureRecipe 자체의 name:version으로 확인됩니다. 따라서 생성한 엔터티를 식별하기 위해 recipe-uri를 읽는 다운스트림 도구는 component가 내보낸 출력과 FR이 내보낸 출력 모두에 대해 올바른 출처를 얻습니다.

provider별 내보내기 세부 사항(렌더링된 출력의 어디에 레이블이 놓이는지, 각 provider가 이를 어떻게 직렬화하는지)은 providers/well-known-annotations.md의 “Provenance labels emitted by providers”를 참조하십시오.

Recipe가 선언하는 출력 레이블

컴파일러가 소유하는 출처 레이블 집합과 별도로, Recipe 작성자는 Recipe.spec.outputLabels:를 통해 Recipe의 렌더링된 출력에 기록할 자체 레이블을 선언할 수 있습니다. 이 레이블은 출처 레이블과 같은 내보내기 경로를 따릅니다. 즉 같은 레이블 집합에 병합되어 출처 레이블이 놓이는 모든 위치에 놓이지만, 컴파일러가 아니라 작성자가 소유합니다. 의도된 용도는 실현 특성입니다. 이는 특정 Recipe가 component를 실현하는 방식의 속성으로(예를 들어 같은 component 유형에 대해 관리형 서비스 Recipe와 자체 호스팅 차트 Recipe를 구분하는 hosting: managed와 hosting: self-hosted), 비용, 정책, 인벤토리 도구가 조회할 수 있도록 출력에 드러납니다.

aggrega.ai/와 app.kubernetes.io/ 네임스페이스는 출처 레이블 집합용으로 예약되어 있습니다. 두 접두사 중 하나에 속하는 키는 로드 시점에 거부됩니다. 이는 outputLabels:에서도, 그리고 component 레이블 키를 지정하여 component 자체가 선언한 값을 기록하는 동반 블록인 outputComponentLabels:에서도 마찬가지입니다. 따라서 검증된 출력 레이블 집합은 항상 출처 키와 겹치지 않으므로, 병합된 출력에서 둘이 충돌하는 일은 없습니다. 판정 기준은 접두사가 붙지 않은 루트입니다. component.aggrega.ai/hosting처럼 범위가 지정된 키는 별도의 네임스페이스에 속하므로 그대로 작성하거나 승격할 수 있습니다. provider별 노출 위치(합성 시 helm 객체와 pod-template, source-render와 아티팩트의 경우 객체, compose 서비스 레이블, .tf.json 아티팩트 본문의 terraform 리소스별 태그)는 출처 레이블의 배치와 일치하며, Recipe 엔터티 페이지의 “outputLabels: 필드”와 “outputComponentLabels: 필드”에 자세히 설명되어 있습니다.

Feature 연결 — 다섯 가지 작성 위치

Features는 서로 다른 다섯 가지 작성 위치를 통해 Components에 연결되며, 각 위치는 범위, 대상 사용자, 5-Tier Onion Model 안에서의 순서 우선순위가 서로 다릅니다. 전체 연결 순서와 Onion Model 자체는 architecture/10-compilation-pipeline.md에 설명되어 있으며, 아래 표는 다섯 가지 위치를 나란히 나열합니다.

티어보고 위치작성 주체범위캐스케이드 규칙
1Aggregate 컴포넌트 features: 블록개발자컴포넌트 인스턴스별(세분화)없음 — 작성자가 직접 지정
2Aggregate 서브시스템 features: 블록개발자서브시스템 범위(Aggregate 내 횡단)서브시스템의 모든 컴포넌트로 전파
3Release 경계 components.<id>.features운영컴포넌트 인스턴스별(세분화, 운영 측)없음 — 작성자가 직접 지정
4Release 경계 features: 블록운영경계 범위(경계 내 횡단)경계의 모든 컴포넌트로 전파
5Manifest features.annotations 확장플랫폼 운영자어노테이션 기반(합성 연결)경계 트리(Release 측) 또는 서브시스템 트리(Aggregate 측)를 따라 전파되며, 컴포넌트별 재정의와 하위 키별 null 옵트아웃이 적용됨

다섯 가지 위치는 누적됩니다. 어느 위치에 있는 연결이든 Component의 확정된 기능 집합에 기여합니다. 동일한 Feature 인스턴스 이름이 둘 이상의 위치에 나타나면 각 기여는 서로를 대체하지 않고 하나의 연결로 병합되며, 이들 사이에 타입 불일치가 있으면 feature-merge-conflict 오류로 빌드가 중단됩니다.

다섯 가지 위치는 중복이 아니라 아키텍처의 관심사 분리 — 개발자(티어 1-2), 운영(티어 3-4), 플랫폼 운영자(티어 5) — 에 따라 의도된 것입니다. 작성자는 연결을 누가 소유하며 어떤 범위에서 적용되는지에 맞는 위치를 선택합니다.

Feature 적용 여부를 결정하는 레이블

Feature는 spec.appliesTo와 spec.appliesToAnyOf로 연결될 수 있는 위치를 선언하며, 빌드는 이 선언을 연결이 놓이는 노드의 최종 확정된 레이블에 대해 판정합니다. 해당 레이블이 충족하지 않는 노드에 Feature를 연결하면 빌드가 중단됩니다. 두 항목 중 어느 것도 선언하지 않은 Feature는 요구 사항이 없으므로 어디에든 적용됩니다.

최종 레이블 집합은 두 단계로 구성되며, 두 단계 모두 작성자가 흔히 가정하는 방식이 아닙니다.

  1. 노드는 자신의 type:이 가리키는 Component 카탈로그 엔티티에서 레이블을 가져옵니다. 레이블은 인스턴스가 아니라 컴포넌트 타입의 속성입니다. Aggregate는 컴포넌트 인스턴스에 레이블을 붙일 수 없으며, Release도 마찬가지입니다. Aggregate 자체의 metadata.labels는 재사용 가능한 모듈로서의 Aggregate를 설명할 뿐, 그 안의 컴포넌트로 전파되지 않습니다. 따라서 같은 타입의 두 인스턴스는 동일한 레이블을 가지며, 노드의 레이블을 바꾸려면 노드가 가리키는 타입을 바꾸거나 그 타입의 엔티티를 바꿔야 합니다.
  2. 그다음 label-transform 연결이 레이블을 다시 쓸 수 있습니다. 워크스페이스 구성이 label-transform 역할로 거버넌스 플러그인을 연결하면, 이 플러그인은 토폴로지 구성 시점에 실행되며 레이블에 대한 판정이 이루어지기 전에 노드 레이블을 추가, 변경 또는 제거할 수 있습니다. 그 밖의 것은 건드릴 수 없으므로 레이블은 플러그인이 바꿀 수 있는 노드의 유일한 부분이며, 바로 적용 가능성을 좌우하는 부분입니다.

따라서 단일 문서가 선언하는 레이블을 기준으로 한 제안은 예측이 아니라 근사치입니다. Component 엔티티의 metadata.labels를 읽으면 해당 타입의 노드가 처음에 어떤 레이블로 시작하는지 알 수 있습니다. 이는 유용할 만큼 자주 맞지만 두 가지 경우에 틀립니다. 노드와 이름만 같은 문서는 레이블이 다른 별개의 대상이며, label-transform 연결은 어떤 문서와도 무관하게 레이블 집합을 바꿀 수 있습니다. 소스만으로 연결 제안을 제공하는 도구는 이 근사치를 기반으로 동작하며, 빌드의 판정은 최종 확정된 집합에 대해 이루어집니다.

연결 우선순위

두 기여가 같은 연결의 같은 필드를 제공하면, 렌더링된 출력에 어느 쪽이 담길지를 네 가지 규칙이 결정합니다. 이 규칙은 이 순서대로 적용되며, 이 순서가 결과를 예측 가능하게 합니다.

  1. 출처. 명시적으로 작성된 기여는 각각 어느 범위에서 선언되었든 어노테이션 기반 기여보다 우선합니다. features: 블록에 필드를 적는 것이 작성자가 어노테이션이 기여했을 내용을 재정의하는 방법이며, 어노테이션은 직접 작성한 내용을 조용히 밀어내는 일이 없습니다. 컴파일러는 억제된 어노테이션을 채택된 값과 함께 기록하고 권고로 보고하므로, 재정의는 불분명하지 않고 드러납니다.
  2. 필러 소유권. 각 영역은 자신의 필러를 채웁니다. Aggregate 측 위치는 values를, Release 측 위치는 infra를 기여합니다. 두 측은 결코 같은 필러에 쓰지 않으므로 개발자 기여와 운영자 기여가 같은 필드를 두고 다툴 수 없으며, 개발자 대 운영자 우선순위 문제는 생기지 않습니다.
  3. 구성 권한. 배포하는 Aggregate의 선언은 그것이 구성하는 Aggregate 내부의 선언보다 우선하며, 구성된 Aggregate가 더 좁은 범위에서 선언했더라도 마찬가지입니다. 구성이 권한을 유지합니다. 모듈은 더 좁은 범위를 선택하는 것만으로 자신을 사용하는 Aggregate를 이길 수 없습니다.
  4. 구체성. 하나의 작성 수준과 하나의 필러 안에서는 더 좁은 범위가 더 넓은 범위를 필드 단위로 세분화합니다. 컴포넌트 범위 연결은 같은 인스턴스 이름의 서브시스템 전체 또는 경계 전체 연결을 재정의하지만, 실제로 언급한 필드에 대해서만 그렇습니다. 더 좁은 범위가 생략한 필드는 더 넓은 범위의 값을 유지하므로, 공유 연결이 공통 구성을 제공하고 개별 컴포넌트가 그중 한 필드만 조정할 수 있습니다. 같은 범위의 두 기여는 작성 순서로 해결되며 나중 것이 채택됩니다. 이 덕분에 안쪽 서브시스템이 바깥쪽 서브시스템을, 더 깊은 경계가 더 얕은 경계를 세분화할 수 있습니다.

우선순위는 필드 값을 결정합니다. 평가 순서는 바꾸지 않습니다. 컴파일러가 위치들을 합치는 순서와 각 연결의 렌더링 전 injectMapping을 실행하는 순서는 architecture/10-compilation-pipeline.md에 설명된 고정된 5단계 순서입니다. 연결에 작성된 inject 블록은 위의 범위 순위가 아니라 이 평가 순서를 따르므로, 하나의 연결이 서로 경쟁하는 두 가지 순서를 갖는 일은 없습니다.

metadata.labels 및 metadata.annotations를 가지는 종류

metadata.labels는 Component, Feature, Aggregate 및 네 가지 라이브러리 종류에 있고, metadata.annotations는 Aggregate를 제외한 같은 종류에 있습니다. Manifest, Release, Recipe, FeatureRecipe, Plugin은 둘 다 가지지 않습니다.

캐스케이드 요약

컴파일러가 평가하는 여섯 표면에 걸친 캐스케이드 규칙은 다음과 같습니다.

  1. 카탈로그 엔터티 레이블(표면 1) 은 카탈로그 엔터티에 머뭅니다. 인스턴스로 전달되지 않으며, 소비자는 카탈로그 내용을 직접 검사하여 이를 읽습니다.
  2. Component metadata.labels(표면 2) 는 토폴로지 구성 시 선택적인 label-transform 패스를 거친 후 노드별 .context.labels로 전달됩니다.
  3. Component metadata.annotations(표면 3) 는 노드별 .context.annotations.catalog 버킷으로 전달됩니다.
  4. Aggregate / Subsystem annotations:(표면 4) 는 서브시스템 계층을 따라 바깥 서브시스템에서 안쪽으로 누적되며 캐스케이드되어 노드별 .context.annotations.aggregate 버킷으로 들어갑니다.
  5. Release 경계 annotations:(표면 5) 는 경계 계층을 따라 바깥 경계에서 안쪽으로 캐스케이드되어 노드별 .context.annotations.release 버킷으로 들어갑니다.
  6. Manifest features.annotations(표면 6) 는 노드별 IR 데이터로 직접 캐스케이드되지 않습니다. 해석 단계의 어노테이션 기반 확장 하위 단계가 바인딩을 소비하여 노드별 Feature 연결을 합성하며, IR 그래프(--ir-graph)는 이를 origin: annotation으로 기록합니다. 합성된 연결은 해석 이후 단계에서 그 출처를 통하지 않고서는 명시적 연결과 구조적으로 구별되지 않습니다. 확장에 대한 전체 설명은 providers/well-known-annotations.md를, 카탈로그 로드 및 검사 시점의 메커니즘은 architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion”을 참고하십시오.

표준 캐스케이딩 어노테이션 설계는 architecture/06-data-taxonomy-and-composition.md §2(Flow 5)를 참고하십시오.

상호 참조