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

명명 관례

이 장에서는 작성된 Aggrega 콘텐츠에 적용되는 명명 및 대소문자 규칙을 다룹니다. 사용자가 작성하는 인스턴스 이름의 패턴, DSL 필드 이름의 대소문자 규칙, 사용자가 아니라 플랫폼이 정의하는 식별자에 플랫폼이 사용하는 대소문자 표기, 그리고 YAML 작성 단계에서 사용하는 주석 구문이 그 대상입니다.

인스턴스 이름

사용자가 작성하는 인스턴스 이름, 즉 개발자가 component, feature, aggregate, subsystem, boundary, 그리고 uses 소켓과 별칭에 대해 작성하는 키는 모두 하나의 패턴 ^[a-zA-Z0-9_-]+$와 일치합니다. kebab-case(pii-filter, my-agent)와 snake_case(openai_key, db_credentials) 모두 유효하며, 팀은 선호하는 관례를 어느 것이든 채택할 수 있습니다.

허용되는 문자: 영숫자(a-z, A-Z, 0-9), 하이픈(-), 밑줄(_). 그 밖의 문자는 허용되지 않습니다.

예시:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
패턴범위예시
^[a-zA-Z0-9_-]+$사용자가 작성하는 모든 인스턴스 이름web-server, openai_key, pii-filter

이 패턴은 해석 시점에 JSON Schema patternProperties를 통해 강제됩니다.

component 이름의 비용, 그리고 일부 대상에서 대문자의 비용이 더 큰 이유

위 패턴은 무엇을 작성할 수 있는지를 말합니다. 이름이 치르는 비용은 별개의 문제이며, component가 배포되는 대상에 따라 달라집니다. 따라서 빌드가 이름을 거부하는 시점이 아니라 이름을 고르기 전에 알아 두는 것이 좋습니다.

component의 이름은 그 component가 내보내는 모든 리소스에 찍히는 식별자가 되며, 각 대상은 이 식별자에서 자체 이름을 도출합니다. 차트 설치 도구는 release 이름을, 컨테이너 오케스트레이터는 서비스 이름을 도출합니다. 문자 집합이 패턴보다 좁은 대상은 허용하지 않는 문자를 담을 수 없으며, Aggrega는 그런 문자를 비슷한 문자로 조용히 바꾸지 않습니다. 작성자가 구별할 수 있는 두 이름이 클러스터에서 하나의 이름이 되어서는 안 되기 때문입니다. 그래서 대상이 허용하지 않는 문자는 대신 이스케이프로 기록되며, 이스케이프는 대체하는 문자보다 깁니다.

실제 결과: 대문자는 어떤 대상에서는 비용이 없고 다른 대상에서는 비용이 큽니다.

  • 이름에 대문자를 허용하는 대상(예: 컨테이너 오케스트레이션 compose 파일)에서는 PaymentsAPI가 작성한 그대로 전달되며 11자를 차지합니다.
  • 이름이 소문자만 허용하는 대상(차트 설치 도구의 release 이름)에서는 모든 대문자가 이스케이프되며, 대문자 여섯 개만으로 된 이름도 이미 그 대상이 허용하는 길이를 넘습니다.

두 번째 효과가 있으며, 이쪽이 더 결정적입니다. 이스케이프는 하이픈으로 시작합니다. 따라서 이름이 소문자나 숫자로 시작해야 하는 대상은 첫 문자가 허용되지 않는 문자인 이름을 나머지가 아무리 짧더라도 거부합니다. 어떤 단축도 이를 해결하지 못합니다.

지침은 이 두 효과에서 나옵니다. 소문자와 숫자를 사용하고 단어 사이에는 하이픈을 두며, 이름은 소문자로 시작하십시오. payments-api는 Aggrega가 provider를 제공하는 모든 대상에서 변경 없이 전달됩니다. payments_api는 compose 파일에서는 전달되지만 helm 대상에서는 그렇지 않습니다. helm 대상의 리소스 이름은 밑줄을 허용하지 않으므로, component 이름을 따서 붙이는 Service, 워크로드, release의 이름은 payments-zuapi로 표기됩니다. PaymentsAPI는 그곳에서 비용이 더 큽니다. 그런 리소스의 주소를 게시하는 Recipe는 대상의 표기를 예측하는 대신 대상 자체의 표기를 읽습니다. templates/rendered-resource-names.md를 참조하십시오.

숫자로 시작하는 이름은 작성해도 유효하며 compose 파일에서는 비용이 없지만, helm 대상은 이를 거부합니다. Kubernetes Service 이름은 문자로 시작해야 하고, 차트나 합성된 워크로드가 내보내는 Service는 component 이름을 따서 이름이 붙으므로, 1cache라는 component는 클러스터가 거부할 Service를 렌더링하는 대신 helm 빌드를 중단시킵니다. 이 거부는 해당 component를 지목하고 Service 이름이 문자로 시작해야 한다고 알려 줍니다.

이 중 어느 것도 컴파일러가 스스로 적용하는 규칙이 아닙니다. 컴파일러는 어떤 대상의 명명 규칙도 보유하지 않으며 제한을 만들어 내지도 않습니다. 각 대상의 provider가 자체 이름을 책임지므로, 이름은 component가 실제로 배포되는 대상이 그 이름을 사용할 수 없다고 할 때만 거부되며, 그 거부에는 해당 대상 자체의 사유가 담기고 작성한 spec.components 키를 가리킵니다. 어떤 대상에서는 괜찮고 다른 대상에서는 거부되는 이름은 불일치가 아니라 예상된 동작입니다.

Aggrega가 직접 구성하는 이름(예: boundary에 연결된 feature의 식별자)은 반대로 처리됩니다. 이런 이름은 여러 곳에 작성된 부분으로 조합되어 어느 한 작성자도 그 길이를 알 수 없으므로, 거부되지 않고 대상에 맞게 단축됩니다. 거부되는 것은 직접 작성한 이름뿐입니다.

예약된 경로 구분자로서의 점

마침표 문자(.)는 사용자가 작성하는 모든 인스턴스 이름에서 사용할 수 없도록 예약되어 있습니다. 점은 aggregate 간 component 참조를 위해 컴파일러가 생성하는 경로 구분자라는 구조적 용도로 쓰입니다.

루트 Aggregate가 main-db라는 component를 포함하는 data-layer라는 하위 aggregate를 가져오면, 컴파일러는 aggregate 인스턴스 이름과 component 인스턴스 이름을 점으로 연결하여 평탄화된 절대 ID data-layer.main-db를 구성합니다. 이 점 경로는 다음에 나타납니다.

  • 개발자의 uses 대상: target: data-layer.public_db — 중첩된 aggregate에서 내보낸 component를 참조합니다.
  • 빌드 자체의 진단: 해당 component에 대한 중단이나 경고는 점 경로로 그 component를 지칭하므로, 읽는 이름이 곧 문서에서 검색할 수 있는 이름입니다.

구분자는 이름에 도달하지 않습니다

점 경로는 문서 내부의 주소이며, 배포 대상이 받아들이는 이름이 아닙니다. Kubernetes Service 이름은 점을 전혀 허용하지 않습니다. 더 나쁜 점은, 클러스터 주소 안의 점은 서비스와 그 서비스가 속한 네임스페이스를 구분하는 역할을 하므로, 점이 포함된 이름을 호스트로 소비자에게 넘기면 실패하는 대신 다른 서비스로 해석된다는 것입니다.

따라서 구분자는 빌드가 component의 아이덴티티에서 파생하는 모든 이름과 레이블에서 이스케이프로 기록되며, 대체되는 것이 아니라 이스케이프로 기록됩니다. data-layer.main-db는 data-layer-zdmain-db가 됩니다. 대상이 허용하는 문자로 대체하면 서로 다른 두 component가 하나의 이름에 도달할 수 있습니다. data-layer.main-db와 누군가 data-layer-main-db로 작성한 component가 그렇습니다. 두 component가 도달하는 이름은 어느 쪽도 식별하지 못합니다.

이것이 미치는 범위와 미치지 않는 범위는 다음과 같습니다.

  • 아이덴티티에서 파생된 이름과 레이블에는 미칩니다 — Aggrega가 합성하는 리소스의 metadata.name, aggrega.ai/component-id 및 app.kubernetes.io/name 레이블, 이를 매칭하는 셀렉터, 출력되는 파일 이름, {{ .context.instance_id }}, 그리고 helm release 이름처럼 provider가 스스로 파생하는 이름입니다. 이들은 함께 움직이므로, Recipe가 리소스를 명명하는 키로 구성하는 주소 — 대상이 아이덴티티를 따라 이름을 붙이는 경우 .context.instance_id, 대상이 자체 이름을 보고하는 경우 .context.rendered_name — 는 여전히 빌드가 출력하는 리소스를 가리킵니다.
  • 직접 작성한 이름에는 미치지 않습니다. 구분자가 없는 component 이름은 바이트 단위로 그대로 돌아오므로, 가져온 Aggregate가 제공하는 component만 출력에서 문서와 다르게 표기됩니다.
  • 작성자가 제공한 chart나 fragment 내부의 이름에는 미치지 않습니다. 그 이름은 작성한 사람의 것이며, 서드파티 chart에서 가져온 이름 — 점이 허용되는 <plural>.<group> 형식의 커스텀 리소스 이름 — 은 해당 chart가 작성한 그대로 출력됩니다.

🔴 마지막 항목은 Recipe가 무엇을 게시해야 하는지에 영향을 주며, 이 페이지에서 가장 틀리기 쉬운 부분입니다. 제공된 chart의 자체 템플릿은 플랫폼이 넘겨주는 아이덴티티, 즉 위의 알파벳이 아니라 그 플랫폼 자체의 알파벳으로 작성된 release 이름을 따라 리소스 이름을 붙이며, helm 대상은 자신이 합성하는 workload에도 같은 release 이름을 따라 이름을 붙입니다. 따라서 직접 제공한 소스에서 렌더링된 출력과 그러한 대상에서 합성된 workload의 경우, {{ .context.instance_id }}는 해당 리소스가 가진 이름이 아니며, 두 알파벳이 다를 때마다 이를 바탕으로 게시된 주소는 아무것도 가리키지 않습니다. 플랫폼의 이름을 담는 키와 이를 보고하는 provider는 templates/rendered-resource-names.md에 있습니다.

구분자를 이스케이프로 기록하면 문자가 늘어나며, 길이가 제한된 이름은 한도를 넘을 수 있습니다. 구분자는 단일 문자가 아니라 짧은 이스케이프로 대체되므로, 정규화된 아이덴티티는 문서에서 읽히는 것보다 기록될 때 조금 더 깁니다. 이는 그 결과 이름에 길이 제한이 있을 때만 문제가 됩니다. component를 렌더링하는 대상이 허용하는 레이블 값의 길이를 알려 주며, 기록된 아이덴티티가 이를 초과하면 빌드는 대상이 거부할 값을 출력하는 대신 중단됩니다. 중단 메시지는 아이덴티티 자체가 맞춰야 하는 길이, 즉 이스케이프로 기록되기 전의 길이를 알려 주므로 그 안에서 고른 이름은 처음부터 동작합니다. 해결 방법은 작성한 부분을 줄이는 것입니다. 가져오는 문서가 하위 aggregate에 부여한 이름이나, 그 안의 component 자체 이름입니다.

구분자는 이름이 읽히는 것보다 길게 기록되는 흔한 이유이지만 유일한 이유는 아닙니다. 작성된 이름이 합법적으로 가질 수 있는 두 가지 형태도 그대로 전달될 수 없는데, 그대로 두면 이스케이프가 모호해지기 때문입니다. 하이픈으로 끝나는 이름과, 하이픈 바로 뒤에 z가 오는 이름입니다. 각각 같은 방식, 같은 비용으로 이스케이프되어 기록됩니다. 그 밖의 모든 작성된 이름은 바이트 단위로 그대로 돌아오므로, 문자, 숫자, 밑줄, 단어 사이의 하이픈으로 만든 이름은 이 모든 것의 영향을 받지 않습니다.

컴포넌트 자체의 uses 블록에 있는 소켓 이름은 카탈로그 엔티티의 usesSchema에 있는 키(선언된 소켓)와 일치하거나, 개발자 자신의 임시 소켓을 지정합니다. 후자는 usesSchema를 전혀 선언하지 않은 엔티티에서도 빌드됩니다. 선언된 소켓과 한 글자만 다른 이름에는 두 철자를 모두 알려 주는 경고가 표시됩니다. Release의 에지별 uses와 Feature 연결의 해당 설정은 엔티티가 선언한 소켓만 지정할 수 있으며, 그 밖의 이름은 unknown-uses-socket 검증 오류로 실패합니다.

필드 대소문자 표기

DSL은 개발자용 YAML(사람이 작성)과 내부 컴파일러 계약(템플릿과 도구가 소비)을 구분합니다.

  • 개발자용 YAML(camelCase): Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin 스키마의 여러 단어로 된 필드 이름은 camelCase를 사용합니다. 예: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Kubernetes API 관례를 따릅니다.
  • 내부 계약(snake_case): IR Graph 스키마와 Template Context 스키마의 여러 단어로 된 필드 이름은 snake_case를 사용합니다. Recipe 작성자가 접하는 사용자용 예: instance_id(.context.instance_id에서 — Recipe의 식별자), inject_raw(.inject_raw에서, .context 아래의 키가 아니라 .inject와 나란히 있는 최상위 기둥 — 변경되지 않은 주입 계약), attachment_name(연결 FeatureRecipe의 컨텍스트에서 — 연결이 채우는 슬롯 또는 연결될 때 사용된 이름을 식별). JSON API 관례를 따르며 Go의 JSON 구조체 태그 생성 방식과 일치합니다.
  • 한 단어 필드: 컨텍스트와 관계없이 소문자입니다. 예: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

개발자는 작성하는 YAML에서 snake_case를 접하지 않고, 템플릿 작성자는 Go 템플릿에서 camelCase를 접하지 않습니다. 스키마에 추가되는 항목은 이 관례를 따릅니다.

한 문장에서 교차하는 세 가지 대소문자 표기

Recipe 작성에서는 한 문장 안에서 세 가지 대소문자 표기 관례가 모두 교차하는 일이 흔합니다. 스키마가 정의한 DSL 필드는 camelCase를, 사용자가 작성한 인스턴스 이름은 kebab-case 또는 snake_case를, 템플릿 컨텍스트 참조는 snake_case를 사용합니다. 이 교차를 별개의 관례로 인식하는 작성자는 결과 YAML을 깔끔하게 읽고, 대소문자 표기를 하나의 관례로 합리화하려는 작성자는 그 경계에서 어려움을 겪습니다.

대표적인 예시: 템플릿 컨텍스트를 통해 렌더링된 Component 인스턴스를 참조하는 Recipe의 valuesMapping: 템플릿입니다.

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

세 가지 대소문자 표기, 한 문장:

  • valuesMapping — camelCase. 스키마가 Recipe의 매핑 템플릿용으로 정의한 DSL 필드 이름입니다. 언어의 개발자용 YAML이 Kubernetes API 관례를 따르므로 camel입니다.
  • web-server(렌더링된 component를 통해 간접적으로 참조됨) — kebab-case. Aggregate에서 사용자가 작성한 인스턴스 이름이며, 개발자가 하이픈 형식을 선택했습니다. web_server(snake_case)여도 똑같이 가능하며, 둘 다 인스턴스 이름 패턴에 따라 유효합니다.
  • instance_id, image — snake_case. 템플릿 컨텍스트 안의 필드 이름(.context.instance_id, .values.image)입니다. IR Graph와 템플릿 컨텍스트가 JSON-API 관례를 따르고 Go의 JSON 구조체 태그 생성 방식과 일치하므로 snake입니다.

세 가지 대소문자 표기는 서로 바꿔 쓸 수 없습니다. Recipe 작성자가 {{ .context.instanceId }}(camelCase)라고 쓰면 빌드가 중단됩니다. .context는 자신의 키를 선언하며 instanceId는 그중 하나가 아니므로, 렌더링 전에 참조가 거부되고 진단은 .context가 정의하는 키를 나열합니다. errors/fatal-halts.md의 “Template references a root the render context does not define(템플릿이 렌더 컨텍스트가 정의하지 않은 루트를 참조함)”을 참조하십시오. 개발자가 web.server(점 포함)라고 쓰면 점이 경로 구분자로 예약되어 있으므로 인스턴스 이름 패턴 거부에 걸립니다. 지향할 원칙: 읽거나 작성할 때 세 가지 관례를 염두에 두고, 어떤 대소문자 표기가 적용되는지는 경계(YAML 또는 템플릿에서 현재 위치)에 의존해 파악합니다.

플랫폼 정의 식별자

위의 모든 내용은 작성 표면의 이름, 즉 직접 선택하는 인스턴스 이름, 언어가 채우도록 정의한 스키마 필드, 읽는 템플릿 컨텍스트 키를 다룹니다. 이 밖에 두 가지 레지스터가 플랫폼 자체가 정의하고 사용자는 읽거나 입력하기만 하는 식별자를 다룹니다. 두 레지스터는 하는 일이 다르기 때문에 분리되어 있으며, 그 일이 형태를 결정합니다.

서술형 레지스터: 일관되게 kebab-case. 이 레지스터의 식별자는 자신이 가리키는 대상을 말로 나타내므로, 아무것도 찾아보지 않고 읽고 바로 대응할 수 있습니다. CLI 플래그, 게시 린트 규칙 id, 진단 클래스 코드, 중단 조건이 등록된 코드가 모두 여기에 속합니다.

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

진단 클래스에 억제 플래그가 있는 경우 코드와 플래그는 같은 단어를 같은 순서로 사용합니다. unsupported-field는 --no-unsupported-field-warnings로 억제되므로, 일치시킨 클래스를 보면 바꿔 생각할 필요 없이 사용할 플래그를 알 수 있습니다. 클래스 코드는 도구가 메시지 텍스트를 파싱하지 않고 결과를 인식하기 위해 일치시키는 안정적인 이름입니다. 메시지 문구는 개선될 수 있지만 코드는 바뀌지 않습니다.

단축 코드 레지스터: 문자 E와 네 자리 숫자. 중단 조건에는 E0007 같은 단축 코드도 붙으며, 이는 kebab-case가 아닌 유일한 플랫폼 정의 식별자입니다. 그 이유는 위치에 있습니다. 이 코드는 모든 중단 진단의 맨 앞, 카테고리 옆, 곧 읽게 될 파일과 줄보다 앞에 놓입니다.

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

서술형 코드는 그 자리에 들어갈 수 없습니다. 가장 긴 코드는 그것만으로도 좁은 터미널을 채워, 어디를 봐야 하는지 알려 주는 위치보다 먼저 공간을 차지합니다. 그래서 맨 앞에는 너비를 기준으로 선택한 식별자가 오며, 이 절충은 의도된 것입니다. 네 자리 숫자는 조건에 대해 아무것도 말해 주지 않으므로, 모든 단축 코드는 오류 센티널 참조에서 해당 조건 및 그 조건이 출력하는 텍스트와 함께 게시됩니다. 보고서에는 단축 코드를 인용하고, 검색에 입력한 뒤, 그곳에서 확인하십시오.

두 레지스터는 같은 조건을 두 방향에서 명명하며, 어느 쪽도 다른 쪽을 대체하지 않습니다. 조건을 키로 삼는 도구를 작성할 때는 서술형 코드를 일치시키고, 사람에게 조건에 대해 이야기할 때는 단축 코드를 인용하십시오.

여기와 인스턴스 이름에 kebab-case가 함께 나타나는 것은 충돌이 아닙니다. 인스턴스 이름 패턴은 작성이 허용되는 것에 관한 것으로, 그곳에서는 kebab-case와 snake_case가 모두 유효하며 팀이 하나를 선택합니다. 이 레지스터는 플랫폼이 실제로 작성하는 것에 관한 것이며, 선택할 것이 없습니다. 린트 규칙 id의 철자는 사용자가 선택하지 않고, 컴포넌트 이름의 철자는 플랫폼이 선택하지 않습니다.

필드 표기법은 바뀌지 않습니다. 작성하는 스키마 필드는 camelCase, 템플릿 컨텍스트 키는 snake_case를 그대로 유지합니다. 이 레지스터의 식별자는 어느 표면의 필드도 아니며 플래그, 규칙, 결과 클래스를 위한 짧고 안정적인 이름이므로, 진단 코드가 kebab-case라는 사실은 스키마 필드의 철자에 대해 아무것도 말해 주지 않습니다.

문서 경로 명명 접미사 규율

언어 전반의 일부 필드는 문서 경로 값을 담습니다. 문서 경로 값은 다른 문서 안의 위치(렌더링된 Workload의 volumes 섹션, Component의 featuresSchema 항목, Manifest의 mappings 계층)를 가리키는 문자열입니다. 이 값은 RFC 6901 JSON Pointer 구문을 따르며, 대상 문서를 지나는 경로를 식별하는 슬래시로 구분된 토큰으로 이루어집니다.

RFC 6901은 Aggrega의 모든 문서 경로 표면에 대한 경로 문법의 기준입니다. Wasm 플러그인 계약은 경로가 RFC 6901 포인터인 RFC 6902 JSON Patch 문서를 소비합니다(plugins/plugin-contract.md의 label-transform 역할 JSONPatch 출력 참조). URI 문법의 형식 문자열 목록은 Go 템플릿 구문 및 Sprig 헬퍼와 함께 RFC 6901을 명시합니다(vocabulary/uri-grammar.md의 “Format-string inventory” 참조). Recipe별 .locals 내보내기는 RFC 6901을 사용해, Wasm Injector 플러그인이 플러그인 파이프라인에서 자기 단계의 with 페이로드를 통해 전달받는 합성된 Workload 위치를 가리킵니다. 하나의 문법을 여러 표면이 소비합니다.

명명 접미사 규율은 위의 더 넓은 필드 대소문자 표기 섹션에 맞춘 의도적인 접미사 구분을 통해 이러한 경로 값의 두 작성 측면을 구별합니다.

  • RFC 6901 JSON Pointer를 담는 스키마 필드는 camelCase *Path 접미사를 사용합니다. 이 필드는 개발자가 다루는 YAML 스키마의 일부이므로 camelCase 관례를 따릅니다. 이러한 필드를 선언하는 엔터티 스키마는 없으며, 작성자가 쓰는 문서 경로는 아래의 .locals 내보내기 키입니다.
  • RFC 6901 JSON Pointer를 담는 .locals 내보내기 키는 snake_case *_path 접미사를 사용합니다. 이 키는 Recipe의 내부 내보내기 표면의 일부로, Recipe 자신의 후속 템플릿과 .locals를 참조하는 pipeline[].with 페이로드를 통해 Wasm 플러그인 파이프라인이 읽으므로 snake_case 관례를 따릅니다. 예:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes"는 합성된 Workload의 volumes 배열 위치를 노출합니다.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers"는 containers 배열 위치를 노출합니다.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main"는 Terraform 고유의 리소스 경로를 노출합니다.
    • root_path — .locals.root_path: "/data"는 렌더러의 파이프가 소비하는 루트 경로를 노출합니다.

두 접미사 관례는 필드 대소문자 표기 섹션의 2계층 관례를 반영합니다. 스키마 정의 필드는 camelCase를 사용하고, 사용자가 작성한 식별자나 Recipe 전용 식별자는 snake_case(또는 kebab-case)를 사용합니다. *Path / *_path 접미사 규율은 값이 경로 문법이라는 성격을 식별자 수준에서 드러냅니다. 어느 접미사든 보는 독자는 값 자체를 살펴보지 않고도 그 값이 RFC 6901 구문을 따른다는 것을 알 수 있습니다.

실제 예: Recipe의 *_path 내보내기를 소비하는 Wasm Injector.

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

*_path 키는 Recipe 전용 내보내기이며, containers_path / volumes_path 값은 RFC 6901 JSON Pointer 문자열입니다. Injector 플러그인은 이 문자열을 소비해 렌더링된 Workload의 AST에 대해 JSONPatch 출력의 위치를 정합니다. 연결은 자신의 .locals 기둥에서 이 값에 접근합니다. .context.uses[].locals 필드는 없으므로, 소비자는 uses 간선을 건너 대상의 locals를 읽을 수 없습니다. 간선을 건너는 것은 대상의 provides입니다.

더 넓은 형식 문자열 목록(Go 템플릿 구문, Sprig 함수, SemVer 정규식 및 레이블 셀렉터 문법과 함께 쓰이는 JSON Pointer)은 vocabulary/uri-grammar.md의 “Format-string inventory”를 참조하십시오. RFC 6901 포인터로 주소가 지정되는 RFC 6902 패치를 소비하는 Wasm 플러그인 계약 표면은 plugins/plugin-contract.md를 참조하십시오.

주석 구문

주석 문자는 주변 언어에 따라 달라집니다.

  • YAML 컨텍스트(모든 Aggrega 엔터티의 기본 작성 표면): #를 사용합니다
  • Go 템플릿 컨텍스트(Recipe valuesMapping: 블록 스칼라, FeatureRecipe injectMapping: 블록 스칼라, MappingLibrary 매핑 항목, assertion 블록 assertions: 본문 내부): 템플릿 엔진이 인식하여 렌더링 시점에 제거하는 템플릿 주석에는 {{/* ... */}}를 사용하고, 템플릿 본문 바깥의 YAML 수준 주석에는 #를 사용합니다.

schema:, usesSchema:, featuresSchema:, parameters: 아래의 축약형 스키마는 전부 YAML입니다. 필드별 description: 주석은 인라인 필드 문서화를 위해 문서화된 표면입니다(port: { type: integer, description: "TCP listen port" }).