Feature
Feature 엔티티의 개념적 역할(Domain 2의 모듈식 운영 특성)은 architecture/04-entity-taxonomy.md에서 다룹니다. 운영 Features와 자격 증명 Features(feature.aggrega.ai/kind: secret 레이블이 지정된 것)의 구분은 architecture/08-credential-model.md에 설명되어 있습니다. Feature 셀렉터가 사용하는 시맨틱 레이블 어휘는 entities/component에서 다룹니다. 이 페이지는 Feature 카탈로그 작성 표면을 다룹니다.
카탈로그 위치
Components(카테고리 하위 디렉터리가 있는 세 세그먼트 URI를 사용함)와 달리 Features는 평면적으로 구성됩니다. 게시자 아래에 Feature마다 디렉터리가 하나씩 있고, 그 안에 버전마다 디렉터리가 하나씩 있습니다.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...OCI URI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (예: hub.aggrega.ai/feature/core/data-masking:1.0.0).
작성 계약
Features는 다음을 선언합니다.
metadata.labels: Feature를 자격 증명 Feature로 표시하려면feature.aggrega.ai/kind: secret을 사용합니다. 이 레이블은 작성자, 카탈로그 사이트, 레이블 셀렉터를 위한 설명용 메타데이터입니다. 이 레이블을 읽는 컴파일러 분기는 없으며, 연결이 무엇을 생성하는지는 레이블이 아니라 Manifest가 그 타입을 매핑하는 FeatureRecipe가 결정합니다. 자격 증명 Feature와 일반 Feature는 같은 연결 표면에서, 어떤 범위에서든 같은 방식으로 연결됩니다. 표준 라이브러리의 자격 증명 계열은 결과에 따라 나뉩니다. **core/secret-value**는 값을 inject 파이프로 전달합니다. **core/referenced-secret**는 참조 가능한 시크릿 리소스(Kubernetes Secret, AWS Secrets Manager 시크릿, Vault 항목)를 가리키며, 이 리소스는 해당 FeatureRecipe의 출력이 생성하거나 이미 존재하는 것입니다. 또한schema.provides출력 계약 —name(리소스의 provider 중립적 로케이터)과key(그 안의 데이터 필드) — 을 선언하며, 소비자는 이를.features.<slot>.provides.<key>로 읽어 리소스 이름을 다시 도출하지 않고 리소스를 참조합니다. **core/referenced-secret-set**는 호출자가 제공한 데이터 키 집합을 담은 리소스 하나를 구체화하고 로케이터만 게시하며, 대상이 읽을 키 이름을 이미 알고 있는 소비자를 위한 것입니다. **core/secret-provided**는 기존 시크릿의 값을 노출합니다. **core/generated-secret**는 대상 엔진이 자격 증명을 직접 생성하고 관리하므로 아무것도 생성하지 않습니다. 따라서values도provides도 선언하지 않으며, 그 FeatureRecipes는 바이트를 렌더링하지 않는 순수한 연결입니다. 구성원을 구분하는 축은 두 가지입니다. 하나는 누가 자료를 제공하는지 — 작성자가 직접 작성하거나 가져올 위치를 지정하는지, 또는core/generated-secret처럼 대상 엔진이 전적으로 소유하는지 — 이고, 다른 하나는 연결이 무엇을 산출하는지, 즉 주입된 값인지, 참조 가능한 리소스인지, 아무것도 렌더링되지 않는지입니다. 모든 구성원은 같은 연결 표면에서 서로 동등하므로, 자격 증명 슬롯은 항상 바인딩되며 Releases 사이에서 달라지는 것은 무엇이 그 슬롯을 바인딩하는지입니다.schema.provides계약을 선언하는 자격 증명 Feature는 이를 구현하는 모든 FeatureRecipe가 해당 키를 게시하도록 요구하며 — 그렇지 않으면 빌드가 중단됩니다 —featuresSchema슬롯의selector는 필요한 계열 구성원을 대상으로 지정합니다.usesSchema(선택 사항): Feature가 소비할 수 있는 토폴로지 소켓을 선언합니다(예: vault를 대상으로 하는 자격 증명 Feature의path/key소켓). Split Schema 메커니즘은 architecture/13-catalog-and-registry.md §2를 참조하십시오.schema: Feature 연결의values및infra블록을 검증합니다. 이는 Developer가 Aggregate에서 각 연결에 구성하는 인지적 의도(values는 Developer의 영역이며, Release 스키마는 Feature 연결에서values:를 금지합니다)와 Operator가 Release에서 환경별로 결정하는 용량(infra)입니다.default:를 선언한 필드는 아무것도 작성하지 않았을 때 검증 대상이 되는 동시에 렌더링된 pillar에 채워집니다. Feature 범위와 작성 형태를 참조하십시오. 압축 형식 YAML 약식(기본값,vocabulary/compact-form-authoring.md참조) 또는 전체 JSON Schema YAML로 표현된 JSON Schema 2020-12를 허용하며, 공유 형태를 위해 SchemaLibrary 항목에 대한 문서 간$ref:를 사용할 수 있습니다(vocabulary/cross-document-ref.md참조). 시크릿 자료를 담는 리프는sensitive: true를 선언합니다. 표준 라이브러리의 자격 증명 Features는 자료를 담는 리프를 표시하고, 게시된 로케이터는 의도적으로 표시하지 않습니다. 리소스 이름과 데이터 키는 모두 공개 정보이기 때문입니다. 이 키워드와 이를 선언해 얻을 수 있는 효과의 한계는vocabulary/compact-form-authoring.md의 “Declaring a leaf sensitive”에 있습니다.featuresSchema(선택 사항): Feature가 자체 동작에 필요한 연결 슬롯을 선언합니다. Feature는 Component와 똑같이 슬롯을 선언하므로, 자체적으로 자격 증명이 필요한 Feature(예: Datadog 사이드카 Feature의 API 키)는 호스트 Component의 슬롯에 손을 뻗는 대신 바인딩 지점을 지정합니다. Feature가 자체 슬롯을 선언하고 FeatureRecipe가 그 슬롯을 채운 것을 읽는 예는 A Feature’s Own Credential을 참조하십시오. 각 슬롯은 Component의featuresSchema슬롯과 같은 필드를 같은 의미로 허용합니다. 여기에는 선택적selector(어떤 Feature가 슬롯을 채울 수 있는지 제한하는 Kubernetes 스타일 레이블 셀렉터로,usesSchema소켓 셀렉터의 슬롯 버전입니다. 레이블이 이를 만족하지 않는 채움은 중단되며, 셀렉터는 연결된 Feature의 레이블에 대해서만 평가됩니다), 선택적sensitive(슬롯을 바인딩하는 것이 무엇이든 시크릿 자료를 다룬다는 선언으로, 특정 채움이 아니라 바인딩 지점에 관한 진술입니다), 그리고 같은 개방성이 포함됩니다. 슬롯을 선언해도 어떤 슬롯도 선언하지 않은 이름으로의 연결은 금지되지 않습니다. 전체 필드 표, 슬롯 수준의 민감도 선언과 스키마 리프의 선언과의 차이, 슬롯을 선언하는 하나의 엔터티가 배포되는 두 가지 형태는 모두 entities/component.md “Attachment Slots”에 있습니다.appliesTo/appliesToAnyOf: Feature가 어떤 Components에 연결될 수 있는지 제어하는 레이블 셀렉터입니다. 정적 분석 단계에서 컴파일러의 네이티브 레이블 매칭 엔진이 평가합니다. 셀렉터 구문 참조는 아래의 레이블 기반 연결과 architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors”를 참조하십시오.interoperability(선택 사항):conflictsWith를 담는 중첩 블록으로, 이 Feature와 함께 하나의 컴포넌트에 도달할 수 없는 Features를 나타냅니다. 하나의 컴포넌트가 결국 둘 다 갖게 되면, 각각이 어느 범위에서 연결되었든 렌더링 전에 빌드가 중단됩니다. 자세한 설명은 아래의interoperability블록을 참조하십시오.
Feature의 구조적 렌더링은 해당 FeatureRecipe에 바인딩되며, FeatureRecipe는 Feature 인터페이스를 구체적인 인프라 구현에 매핑합니다.
레이블 기반 연결
Feature 스키마의 두 applies 셀렉터는 Feature가 어떤 Components에 연결되는지를 제어하며, 정적 분석 단계에서 컴파일러의 네이티브 레이블 매칭 엔진이 평가합니다:
appliesTo— Kubernetes 스타일의 레이블 셀렉터 문자열이며, AND 조합을 위한 수단입니다. 쉼표로 구분된 요구 사항이 모두 충족되어야 하며, 전체 연산자 어휘를 사용할 수 있습니다:key=value,key!=value,key in (v1, v2),key notin (v1, v2), 단독key(레이블 존재),!key(레이블 부재).appliesTo: "datastore.aggrega.ai/engine=vector"를 선언한 Feature는 정확히 그 키-값 쌍으로 레이블이 지정된 Components에만 연결됩니다.appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"는 “제한된 데이터를 보유하지 않는 모든 server 또는 worker”를 하나의 셀렉터 문자열로 표현합니다.appliesToAnyOf— OR 조합을 위한 수단입니다. 셀렉터 항목의 목록이며, 어느 한 항목만 일치해도 충분합니다. 각 항목은 문자열 형식의 셀렉터(appliesTo와 같은 문법이며, 문자열 안의 요구 사항은 AND로 결합됨)이거나, 동등 비교만 하는 평면 키-값 맵입니다. 하나의 Feature가 서로 관련 없는 여러 component 형태에 맞을 때 사용합니다. 예를 들어{ component.aggrega.ai/type: worker }또는{ component.aggrega.ai/type: task }에 적용되는 관측성 Feature를, 둘을 하나의 셀렉터 문자열로 억지로 합치지 않고 표현할 수 있습니다.
any-of 형식이 없다면 Architect는 Feature가 맞는 서로 관련 없는 component 형태마다 같은 Feature YAML을 중복 작성해야 합니다. 두 형식은 함께 쓸 수 있습니다. Feature는 둘 다 선언할 수 있으며, 그 결과는 형식 간에 AND로 결합됩니다. 즉 appliesTo 문자열이 충족되어야 하고, 동시에 appliesToAnyOf 항목 중 최소 하나가 일치해야 합니다. 생략되었거나 비어 있는 셀렉터는 아무 제약도 선언하지 않으며 모든 레이블 집합과 일치합니다.
셀렉터 문자열은 Feature의 연결이 평가될 때마다 여섯 가지 형식에 비추어 해석되며, 이 형식에서 벗어난 요구 사항은 다른 셀렉터로 해석되지 않고 빌드를 중단시킵니다. 해당하는 경우는 빈 요구 사항(앞이나 뒤의 쉼표, 중복된 쉼표, 또는 구분자만으로 된 문자열), 공백이나 =, !, (, ), 쉼표 중 하나를 포함한 키, 그리고 닫히지 않은 in ( 또는 notin ( 집합입니다. 이것이 그렇지 않으면 의도와 정반대를 조용히 선택해 버릴 실수를 잡아냅니다. Feature를 frontend에서 제외하려고 작성한 appliesTo: "!tier=frontend"는 거부되는데, !는 레이블 키만을 지정하기 때문입니다. 값을 제외하는 방법은 tier!=frontend입니다. 또한 tier in frontend는 거부되며 tier in (frontend)로 써야 합니다. 값은 연산자 뒤의 텍스트이며 어떤 문자를 포함하든 상관없으므로, tier==frontend는 값이 =frontend인 레이블을 요구합니다. 중단 시에는 Feature, 그 셀렉터, 그리고 해석할 수 없었던 요구 사항을 표시합니다. 아무것도 연결하지 않은 Feature는 평가되지 않으므로, 그 Feature의 잘못된 셀렉터는 어떤 연결이 그것을 지정할 때까지 보고되지 않습니다.
셀렉터 문법 참조는 architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors”를 참고하십시오. Feature 셀렉터가 받아들이는 문법은 usesSchema 소켓 셀렉터가 받아들이는 문법과 같으며, Kubernetes 사용자가 kubectl get -l에서 익히 아는 문자열 형식입니다.
interoperability 블록
Feature 스키마는 선택적인 spec.interoperability 블록을 선언하며, 이 블록은 하나의 제어 항목을 담습니다. 바로 이 Feature가 하나의 컴포넌트에서 다른 어떤 Features와 공존할 수 있는지입니다.
interoperability.conflictsWith — 정의 중인 Feature와 상호 배타적인 Features의 목록이며, 각 항목은 어태치먼트의 type이 Feature를 지정하는 방식대로 작성합니다. 이 목록은 호환되지 않는 구성이 생성되는 것을 막습니다. 예를 들어 TCP 전용 메시와 HTTP 인식 프록시를 같은 컴포넌트에 함께 어태치하는 경우입니다.
하나의 컴포넌트가 결과적으로 이 Feature와 그 목록이 지정하는 Feature를 함께 갖게 되면, 빌드는 아무것도 렌더링하기 전에 중단됩니다. 기준은 도달 범위입니다. 어태치먼트는 그것이 작성된 컴포넌트에 도달하고, 그것이 작성된 서브시스템이나 경계 안의 모든 컴포넌트에도 도달하며, 중첩된 경계도 포함됩니다. Release 컴포넌트 항목에 작성된 어태치먼트나 어노테이션 기반 확장으로 생성된 어태치먼트도 같은 방식으로 해당 컴포넌트에 도달합니다. 따라서 선언된 충돌은 두 Features가 같은 컴포넌트에 어태치된 경우, 하나는 경계에, 다른 하나는 그 안의 컴포넌트에 있는 경우, 하나는 바깥 경계에, 다른 하나는 그 안에 중첩되어 컴포넌트를 담은 경계에 있는 경우, 그리고 하나는 서브시스템에, 다른 하나는 그 서브시스템의 컴포넌트에 있는 경우에 빌드를 중단합니다. 공유하는 컴포넌트가 없는 형제 경계에 어태치된 두 Features는 만나지 않으며, 컴포넌트를 담지 않은 경계는 어디에도 도달하지 않으므로 어느 경우도 중단되지 않습니다.
- 한 번의 선언으로 충분합니다. 어느 한 Feature의 목록이 다른 Feature를 지정하면 빌드가 중단됩니다. 두 번째 Feature가 첫 번째 Feature를 다시 목록에 넣을 필요는 없습니다.
- 버전과 관계없이 이름으로 비교합니다. 각 항목과 각 어태치먼트의 타입은 버전을 제거한 상태로 비교되므로,
core/fixed-replica-controller항목은core/fixed-replica-controller:2.0.0어태치먼트와 일치하며, 버전을 포함한 항목은 그것이 지정하는 Feature의 모든 버전과 일치합니다. - 읽는 것은 이름뿐입니다. 컴파일러는 Feature 작성자가 선언한 이름을 컴포넌트가 갖는 Features와 비교합니다. 이는 작성자가 작성한 데이터를 대상으로 하는
appliesTo와 같은 종류의 평가입니다. 두 Features가 호환되지 않는지는 작성자의 판단이며, 그 판단을 기록하는 곳이 이 목록입니다.
중단 메시지는 다른 Feature를 목록에 지정한 Feature, 두 Features 각각이 어태치된 모든 위치(Aggregate의 컴포넌트, 서브시스템, 경로를 포함한 Release 경계, Release 컴포넌트 항목, 또는 지정된 어노테이션의 어노테이션 기반 확장), 그리고 둘이 만나는 컴포넌트를 표시합니다. 여러 컴포넌트에서 만나는 쌍은 컴포넌트마다 한 번씩 보고됩니다. 메시지는 errors/fatal-halts.md를 참조하십시오.
예:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controller이 Feature는 server 타입의 Components에만 어태치되며, 레플리카를 제어하는 다른 Feature와의 비호환성을 선언합니다. 어떤 컴포넌트든 결과적으로 둘을 모두 갖게 되는 빌드는 렌더링 전에 중단됩니다. 자신이 어태치된 컴포넌트의 이름이 필요한 FeatureRecipe(예를 들어 오토스케일러가 대상을 가리키게 하려는 경우)는 템플릿 컨텍스트에서 그 이름을 읽어 출력에 필요한 곳에 씁니다. .context.instance_id는 컴포넌트의 식별자이고, .context.rendered_name은 컴포넌트 자신의 provider가 그 컴포넌트를 위해 렌더링하는 리소스에 부여하는 이름으로, 리소스를 대상으로 지정할 때 사용할 이름입니다. helm에서는 합성된 워크로드가 내보내는 Deployment의 이름이자, 차트가 자체 이름을 만드는 기반이 되는 릴리스 이름입니다.
extends를 통한 상속
Feature는 spec.extends: <feature-name>를 선언하여 작성 표면을 상속받을 기반 Feature를 가리킬 수 있습니다. 이 참조는 Feature가 게시되는 레지스트리 좌표가 아니라 metadata.name으로 기반을 지정하며, 모든 카탈로그 참조와 동일한 세 가지 버전 형식을 사용합니다. 사용 가능한 가장 높은 릴리스를 뜻하는 버전 없는 형식(core/queue), 정확한 버전(core/queue:1.0.0), 캐럿 범위(core/queue:^1.0.0)입니다. 컴파일러는 카탈로그 로드 시 부모 체인을 순회하고, 체인에 순환이 없는지 검증한 다음, 부모 spec을 자식에 병합하여 하나의 해석된 Feature를 만듭니다. 키가 충돌하면 자식이 작성한 필드가 우선하며, 부모의 metadata.labels와 metadata.annotations, appliesTo / appliesToAnyOf 선택자, interoperability 블록, usesSchema, featuresSchema, 그리고 schema의 JSON Schema 2020-12 선언은 아래로 자동 병합됩니다. 그 밖의 모든 metadata 필드는 자식의 것을 그대로 사용하므로, 식별 정보와 출처 정보는 절대 상속되지 않습니다.
Feature의 metadata:가 상속하는 것. labels와 annotations는 체인을 따라 키별로 병합되며, 기반이 먼저 적용되고 공유 키에서는 확장하는 Feature의 값이 우선합니다. 이는 Components가 따르는 것과 같은 규칙입니다. metadata:의 나머지는 전달되지 않습니다. name, version, description, maintainers, license, repository, home, keywords는 확장하는 Feature가 작성한 그대로의 자체 값입니다.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }병합된 core/kafka-queue는 부모로부터 appliesTo를 상속하고, values.qos와 infra.partition_count 속성을 상속하며, 그 위에 values.compression_codec를 추가합니다. appliesTo를 명시적으로 선언한 자식은 부모의 선택자를 통째로 재정의합니다(레이블 선택자 병합은 깊은 병합이 아니며, 자식의 선택자가 부모의 선택자를 대체합니다). 자식의 schema.values.qos는 해당 속성에 대한 부모의 선언을 재정의합니다.
부착 표면의 각 부분이 상속되는 방식. 두 선택자 형식은 대체하지 않고 조합되므로 서로 독립적으로 상속됩니다. 존재하는 각 형식은 충족되어야 하며(appliesTo 문자열이 일치해야 하고, 그리고 appliesToAnyOf 항목 중 적어도 하나가 일치해야 함), 없는 형식은 아무것도 제약하지 않습니다. 따라서 Feature는 기반의 AND 선택자를 가져오면서 자체 OR 집합을 선언할 수 있습니다. interoperability 블록은 필드 단위로 상속됩니다. conflictsWith 목록 없이 블록을 선언한 자식은 여전히 기반이 선언한 목록을 가지며, 자체 conflictsWith를 선언한 자식은 기반의 목록에 추가하는 것이 아니라 그것을 대체합니다. 셋 중 어느 것도 선언하지 않은 Feature는 기반이 부착되는 곳에 정확히 부착됩니다.
상속은 인터페이스 바인딩이 아니라 스키마 병합입니다. Feature extends: 체인은 다형적 계열이 아니라 하나의 해석된 Feature를 만듭니다. 체인의 기반 Feature URI는 Manifest 바인딩의 feature: 필드가 참조하는 대상이 아닙니다. Manifests는 말단 Feature의 URI로 바인딩하며, 해석된 스키마에는 상속된 속성이 포함됩니다. FeatureRecipe가 implements:하는 Feature 계약도 마찬가지로 말단 URI이며, FeatureRecipes는 상속 체인을 탐색하지 않습니다.
aggrega pull이 베이스를 가져옵니다. 베이스 Feature는 그것을 확장하는 Feature를 연결하는 모든 Release의 종속성이며, 다른 무언가가 그것을 지정하는지와는 관계없습니다. aggrega pull은 각 extends:를 체인 끝까지 따라가, 어떤 카탈로그 디렉터리에도 없는 베이스를 레지스트리에서 가져오고, 모든 베이스를 Release의 lockfile에 기록하며, 각 베이스는 그것을 지정하는 Feature의 spec.extends에서 참조됩니다. 빌드는 그곳에서 베이스를 읽습니다.
오류 모드. 순환하는 extends: 체인과 어떤 카탈로그 엔터티도 제공하지 않는 부모는 빌드를 중단시키며, 해석이 시작된 Feature, extends: 줄을 열어야 할 Feature, 그리고 그것이 선언한 참조를 명시합니다. 메시지는 Cyclic extends on Components or Features (Component 또는 Feature의 순환 extends)와 An extends: chain cannot be assembled (체인을 조립할 수 없음)에 있습니다.
Components, Features, 자격 증명 Features 전반에 걸친 더 넓은 상속 / 인터페이스 용어는 vocabulary/inheritance-and-interface.md를 참조하십시오.
조합 가능성: 순수성 사회 계약
표준 라이브러리의 관례는 Feature 하나에 내부 기능 하나입니다. 관측성 사이드카는 관측성 Feature이고, 네트워크 프록시 사이드카는 네트워크 프록시 Feature이며, 이 둘은 서로 무관한 두 관심사를 가진 하나의 복합체로 합쳐지지 않습니다. 이 관례는 개별 Features를 조합 가능하고, 독립적으로 버전 관리되며, 독립적으로 부착 가능한 상태로 유지합니다.
핵심 Go 컴파일러는 이 관례를 강제하지 않습니다. 관심사가 섞인 Feature 정의도 구문상 유효하며 문제없이 컴파일됩니다. 강제는 선택 사항입니다.
- 내부 카탈로그를 작성하는 기업은 CI/CD에서 Feature 정의를 검사하고 단일 Feature의
appliesTo레이블이 서로 무관한 기능 영역에 걸쳐 있을 때 경고하는 사용자 정의 linter 플러그인을 작성할 수 있습니다. - 두 Features가 겹친다는 사실을
interoperability.conflictsWith에 기록한 Feature 작성자는 빌드 시점 검사를 선택하게 됩니다. 컴파일러는 두 Features가 하나의 컴포넌트에 도달하는 곳마다 중단합니다. 이 검사는 선언된 이름만 비교할 뿐이므로, 순수성 관례 자체가 아니라 작성자가 작성한 선언을 강제합니다.
오픈 소스 표준 라이브러리 Features는 작성 규율에 따라 순수성 관례를 따릅니다. 기업 카탈로그는 긴밀하게 결합된 복합체가 배포 모델에 실제로 적합한 경우 자유롭게 이를 벗어날 수 있습니다.
무엇이 Feature가 될 자격이 있는가, 그리고 제품 고유의 다이얼은 어디에 속하는가
Feature는 **부착물(attachment)**입니다. 개발자나 운영자가 의도적으로 부착하는 무언가(리소스, 파이프라인 단계, 연결 구성)를 가져오며, 표준 라이브러리의 관례는 Feature가 서로 독립된 최소 두 개의 제품에서 이행될 수 있어야 한다는 것입니다. 이 후반부가 Feature를 작성하기 전에 적용해야 할 기준입니다. 부착물이라는 단어가 약속하는 것이 바로 이식성이기 때문입니다. 부착물은 해당 기능이 옮겨 다닐 수 있음을 뜻합니다. 한 컴포넌트에 부착하고 다른 컴포넌트에 부착하면, 각 제품의 구현이 저마다의 방식으로 그것을 이행합니다.
현장에서 단 하나의 제품만 가진 기능은 Feature가 아니라 그 제품 고유의 다이얼입니다. 그것은 해당 제품 자체의 표면에 작성된 값으로 두어야 하며, 그 값을 결정하는 작성자가 자신의 기둥(pillar)에서 설정하고 같은 제품을 구성하는 다른 모든 것과 나란히 읽습니다. 이를 Feature로 게시하면 다른 어떤 제품도 제공할 수 없는 이식성을 내세우게 됩니다. 그 부착물은 구조상 하나의 제품만을 가리키므로, 작성자가 다음에 사용하려는 제품에 이를 부착하면 타입을 명시하며 중단되는 빌드를 만나게 되고, Feature는 결코 갖지 않았던 기능을 가르친 셈이 됩니다.
이 기준은 이 카탈로그의 컴포넌트가 아니라 현장의 제품을 세며, 각 제품은 자체의 최신 구성 레퍼런스를 기준으로 판단합니다. 서로 독립된 두 제품이 어떤 기능을 구현하면 그중 몇 개가 여기에 포함되어 있든 그 기능은 이식 가능합니다. 따라서 카탈로그의 어떤 것도 구현하기 전에 Feature를 선언할 수 있으며(이 경우 부착하면 타입을 명시하며 빌드가 중단됩니다), 포함된 각 구현은 하나의 제품을 위한 FeatureRecipe로서 그 제품이 구성하는 방식대로 부착물을 이행합니다.
업스트림 인증서 피닝이 실제 사례입니다. 핀은 업스트림이 제시할 수 있는 키를 제어하는 수단으로, 공개 키가 Release가 제공하는 키와 일치하는 인증서만 허용합니다. 이는 업스트림의 인증서가 Release가 제공하는 트러스트 앵커로 체인되도록 요구하는 것과는 다른 단언이며, 인증서의 주체가 무엇을 말하는지 단언하는 것과도 또 다릅니다. 그 두 가지는 인증서가 무엇을 말해야 하는지를 명시하는 반면, 핀은 그것이 어떤 키여야 하는지를 명시합니다. 여기 있는 여러 게이트웨이는 앵커에 대해 검증할 수 있으며, 그래서 dataplane.aggrega.ai/upstream-tls: trust-anchor가 셀렉터가 일치시킬 수 있는 값입니다. 피닝은 별개의 기능이며, 서로 독립된 최소 두 개의 제품이 업스트림으로 여는 연결에 대해 이를 구현합니다. Tyk는 업스트림의 공개 키를 PEM 형식으로 받고, Envoy는 그 해시를 받습니다. 따라서 이는 Feature core/upstream-key-pinning이며, 그 셀렉터는 dataplane.aggrega.ai/upstream-pinning: public-key를 지정합니다. 이 카탈로그가 무엇을 구현하는지는 제품별로 답해집니다. core/gateway/tyk는 해당 값과 각 대상에 대한 FeatureRecipe를 갖추고 있는 반면, Envoy를 내장한 여기의 게이트웨이들은 클라이언트가 제시하는 인증서에 대해서만 핀 설정을 노출하거나 전혀 노출하지 않으므로 값을 갖지 않으며, 이들에 대한 부착은 셀렉터에서 중단됩니다. 핀은 업스트림이 제시할 수 있는 것을 좁힙니다. 이는 제어 수단이지, 연결이 그 밖의 측면에서 안전하다는 보증이 아닙니다.
이 기준에는 두 가지 한계가 있으며, 두 번째가 가장 쉽게 빠뜨리는 부분입니다.
- 이는 작성 규율이지 컴파일러 검사가 아닙니다. 어떤 제품도 구현하지 않는 옵션을 선언한 Feature도 스키마 검증, 게시 린터, 렌더링을 모두 통과합니다. 컴파일러는 Feature가 약속하는 내용을 해석하지 않습니다. 판단은 카탈로그 작성자의 몫입니다.
- 한 제품이 어떤 옵션을 이행하지 못한다는 것은 그 옵션을 없앨 근거가 되지 않습니다. 둘 이상의 제품이 함께 묶일 수 있는 이름으로 어떤 기능을 제공한다면 그 기능은 이식 가능하며 Feature는 이를 유지합니다. 이행할 수 없는 제품은 그것을 거절합니다. 모든 제품이 지원하는 것만으로 축소된 Feature에는 말할 것이 거의 남지 않습니다.
Feature 범위와 작성 형태
Feature의 spec.schema는 Feature 자체의 values: 및 infra: 형태를 정의합니다. 이는 개발자가 Aggregate에서 Feature 연결마다 구성하는 인지적 의도(values)로, 운영자가 환경마다 결정하는 용량 수치(infra)와 구별됩니다. Feature의 필러는 자체 네임스페이스에 존재하며 호스트 Component의 필러와 독립적으로 검증됩니다. 개발자가 Aggregate에서 autoscaler Feature를 web-server Component에 연결하면, Aggregate는 Component의 values:(호스트 형태)와 함께 Feature의 values:(스케일링 의도 형태 — 어떤 메트릭이 스케일링을 이끄는지)를 담습니다. 운영자가 다루는 용량 수치(min_replicas / max_replicas)는 Feature 연결에 대한 Release의 infra: 블록을 통해 전달됩니다.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10Feature의 schema:는 Feature 연결 자체의 values: 및 infra: 블록을 검증합니다. Component의 schema:는 Component 자체의 블록을 검증합니다. 두 스키마는 정적 분석 단계에서 독립적으로 평가되며, Feature의 schema:와 일치하지 않는 연결 필러는 호스트 Component가 아니라 Feature 연결 위치로 범위가 지정된 오류와 함께 빌드를 중단시킵니다. 검증되는 것은 연결의 유효 구성, 즉 그 연결을 구성한 모든 범위를 합성한 결과입니다. 따라서 한 범위에서 적합하게 만든 값이 더 좁은 범위에서 허용되지 않는 값으로 재정의되면 이를 잡아냅니다.
선언된 기본값은 연결의 렌더링된 필러에 구체화됩니다. 검증과 별개로, Feature의 values 또는 infra 필드에 선언된 default:는 빌드 시점에 아무것도 작성되지 않은 모든 키에 대해 해당 연결의 렌더링된 필러에 채워집니다. 따라서 {{ .infra.tier }}를 읽는 FeatureRecipe 템플릿은 빈 값이 아니라 스키마에 선언된 값을 받습니다. 작성자가 제공한 값이 항상 우선하며, 기본값은 작성자가 생략한 키만 채웁니다. Feature 스키마의 키 하나를 작성한 연결도 그 스키마의 나머지 키에 대해서는 선언된 기본값을 받으며, 부분적으로 작성된 중첩 객체는 작성된 내용을 유지하면서 작성되지 않은 형제 키를 얻습니다.
작성 시 알아 둘 만한 채우기의 세 가지 특성은 다음과 같습니다.
- 기본값은 어떤 범위가 제공한 값도 대체하지 않습니다. Feature가 둘 이상의 범위(예: Release 경계와 그 구성 요소 중 하나)에 연결된 경우, 더 좁은 범위의 값이 유지되며 기본값은 어떤 범위도 전혀 작성하지 않은 부분만 채웁니다.
- 기본값은 연결을 채울 뿐, 연결을 만들지는 않습니다. 아무것도 연결하지 않은 Feature에 기본값을 선언해도 출력에는 아무것도 추가되지 않으므로, Feature의 스키마는 어떤 작성자도 요청하지 않은 구성을 추가할 수 없습니다.
- 단일 구성 요소가 아니라 Release 경계에 선언된 연결은
infra만 채웁니다. 해당 표면에는 채울values:블록이 없기 때문입니다.
구체화는 검증과 동일한 스키마 해석을 사용하므로, 부모 Feature에 선언된 기본값은 extends: 자식의 연결에도 도달하며, 문서 간 $ref:를 통해 SchemaLibrary에서 도달한 기본값도 구체화됩니다. 로컬 문서 내 #/$defs/ 참조 안에만 선언되었거나 allOf / oneOf / anyOf 분기 아래에 선언된 기본값은 구체화되지 않습니다.
검증만으로는 드러나지 않으므로 분명히 밝혀 둘 결과가 하나 있습니다. default:도 함께 지닌 required: 필드는 그 기본값으로 충족되므로 생략해도 적법하며, 검사가 수락한 값이 곧 렌더링된 출력에 담기는 값입니다.
컴파일러의 템플릿 컨텍스트는 .features.<alias> 필드(연결마다 .type, .resolved_version, .labels, .values, .infra, .provides 포함)를 통해 Feature의 인스턴스 상태를 바인딩된 FeatureRecipe에 노출합니다. FeatureRecipe 내부의 템플릿은 FeatureRecipe 자체 템플릿 범위에서 .values.<field>를 통해 Feature 자체의 values:를 읽습니다. Feature가 호스트 Component에 대한 uses: 소켓을 명시적으로 선언하지 않는 한, 호스트 Component의 values:는 FeatureRecipe의 템플릿에서 직접 보이지 않습니다.
이러한 범위 분리 덕분에 Features는 조합 가능합니다. autoscaler Feature는 어떤 Component에 연결되는지에 의존하지 않으며, 그 schema:는 호스트와 관계없이 자동 스케일링 의도를 기술합니다. 호스트 Component의 values:는 호스트의 관심사이고 Feature의 values:는 Feature의 관심사이며, 두 필러는 경계를 넘어 필드 이름을 누출하지 않고 합성됩니다.
어노테이션 바인딩 대상
Feature는 어노테이션 바인딩을 직접 선언하지 않으며, Manifest의 mappings.features.annotations 맵이 이를 담습니다. Feature는 라우팅 대상으로서 간접적으로 바인딩 관계에 참여합니다. 각 바인딩은 feature: 필드로 Feature 타입을 지정하고, 바인딩의 maps.infra 및 maps.values 목록은 지정된 Feature의 spec.schema.infra.<path> 및 spec.schema.values.<path> 속성으로 향하는 점 표기 경로를 선언합니다.
카탈로그 로드 시 컴파일러는 바인딩의 maps 목록에 있는 모든 점 표기 경로가 대상 Feature의 spec.schema가 지정된 필러에서 실제로 선언하는 속성에 대응하는지 검증합니다. Feature 스키마가 선언하지 않은 경로로 라우팅하는 바인딩은 명확한 OPS_ERROR와 함께 카탈로그 로드를 중단하며, 이 오류는 바인딩, 대상 Feature, 그리고 라우팅된 필러와 경로를 명시합니다. 바인딩은 운영자의 문서인 Manifest에 작성되기 때문입니다. 따라서 스키마 작성자는 spec.schema.values.<path> 또는 spec.schema.infra.<path> 아래에 선언한 모든 속성이 바인딩 대상으로 도달 가능하다는 것을 알 수 있으며, 반대로 Manifest 바인딩이 경유하는 모든 속성은 대상 Feature의 스키마에 존재해야 합니다.
Aggregate 측 또는 Release 측 어노테이션이 바인딩과 일치하면, 컴파일러는 필러 페이로드가 어노테이션 값을 지정된 경로로 라우팅하는 Feature 연결을 합성합니다. 합성된 연결은 같은 위치에서 작성자가 명시적으로 선언한 Feature 연결과 구조적으로 구별되지 않으며, 이후의 렌더링, 검증, FeatureRecipe 템플릿 컨텍스트는 모두 두 형태를 동일하게 처리합니다. 바인딩 형태, 측-필러 구분, 명시적 연결 우선 원칙은 entities/manifest.md §“Annotation-Driven Feature Bindings”를 참고하십시오. Aggregate 측 캐스케이드 규칙과 작성 예시는 providers/well-known-annotations.md §“Aggregate-side annotation cascade”를 참고하십시오.
assertions: 블록
Feature.spec.assertions:는 Feature 계약의 아키텍처 불변 조건을 표현하는 이름이 있는 규칙의 선택적 맵으로, Feature의 values:와 연결된 Component의 해석된 상태에 걸친 필드 간 규칙입니다. 각 키는 실패 메시지에 나타나는 규칙 식별자이고, 각 값은 Go 템플릿 본문입니다. 컴파일러는 스키마 검증 후, 바인딩된 FeatureRecipe가 렌더링되기 전에 작성된 순서대로 이를 평가하며, 처음으로 실패한 규칙이 해당 규칙 자체의 오류 메시지와 함께 빌드를 중단합니다.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Component assertions와 마찬가지로 Feature assertions는 계약 수준의 불변 조건, 즉 어떤 FeatureRecipe가 렌더링을 구현하든 Feature 연결이 충족해야 하는 속성을 표현합니다. 특정 구현에 의존하는 필드 간 규칙(Wasm 플러그인 요구 사항, 차트의 특이 동작)에는 대신 FeatureRecipe의 assertions: 필드를 사용합니다. 전체 작성 문법, 템플릿 컨텍스트, Feature assertions와 FeatureRecipe assertions 간의 책임 분담은 templates/assertions-block.md를 참조하십시오.