렌더링된 리소스 이름 지정
Recipe는 자체 출력이 생성한 무언가의 이름을 지정해야 하는 경우가 많습니다. provides:를 통해 게시할 호스트 이름, valuesMapping: 안의 참조, artifacts: 본문에 기록되는 식별자 등이 그렇습니다.
이를 위해 사용할 수 있는 이름은 두 개의 템플릿 컨텍스트 키가 제공하며, 두 키는 서로 다른 질문에 답합니다.
잘못된 키를 읽으면 거부되는 대신 아무 경고 없이 잘못된 출력이 만들어집니다. 즉, 아무것도 내보내지 않은 리소스를 가리키는 주소가 생깁니다. 따라서 이 페이지에서는 어떤 키가 어떤 질문에 답하는지 설명합니다.
또한 두 키가 기반으로 하는 구분도 설명합니다. **대상(target)**과 **참조(reference)**는 같은 것이 아니며, 대상은 결코 배포 플랫폼이 확인할 수 있는 이름이 아닙니다.
target은 컴포넌트를 가리키고, reference는 렌더링된 리소스를 가리킵니다
target은 작성 시의 식별자입니다. 개발자가 어떤 엣지가 어느 컴포넌트를 가리키는지 나타내기 위해 작성하는 값이며(uses 블록의 target: my_db), 빌드가 그 컴포넌트를 찾고, 진단에서 그 컴포넌트를 보고하고, 그 사실을 키로 묶는 데 사용하는 식별자입니다. 이 값은 어떤 provider에서도 똑같이 읽힙니다. 어떤 플랫폼에 관한 사실이 아니라 작성한 문서에 관한 사실이기 때문입니다.
reference는 렌더링된 한 아티팩트가 다른 아티팩트를 가리키게 하는 것입니다. reference는 각 provider 고유의 어휘로 작성됩니다. helm에서는 클러스터 내부 주소, compose에서는 서비스 이름, terraform에서는 보간식, cloudformation에서는 가져온 값입니다. 각 플랫폼이 reference를 고유한 방식으로 해석하므로 reference는 provider마다 다릅니다.
🔴 target은 렌더링된 출력에 절대 기록되지 않습니다. 모든 provider는 고유한 이름을 도출하므로, 작성된 식별자를 이름으로 플랫폼에 넘기면 두 표기가 다를 때마다 잘못됩니다. 그리고 두 표기는 정확히 target 자체의 문자 집합이 허용하지 않는 문자에서 달라집니다. 그런 문자가 없는 식별자는 그대로 유지되므로 이 실수를 저지르기 쉽습니다. 누군가 컴포넌트 이름에 밑줄이나 대문자를 쓰기 전까지는 잘못된 방식도 동작하기 때문입니다.
따라서 소비자에게 필요한 reference는 생산자가 게시합니다. 자신의 provider 어휘를 아는 것은 생산자의 Recipe이기 때문입니다. 소비자는 완전히 다른 provider를 바인딩할 수도 있으며, 자신이 렌더링하지 않는 플랫폼의 reference를 작성할 수 없습니다. 소비자는 게시된 일반 문자열을 읽습니다.
예제 쌍
생산자의 Recipe가 주소를 게시하고, 소비자는 엣지의 별칭을 통해 그 주소를 읽습니다.
# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.# It publishes an in-cluster address built from the name that chart's own# templates render their resources against.spec: capability: helm source: ./charts/postgres provides: host: "{{ .context.rendered_name }}.svc.cluster.local" port: "5432"# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an# authoring identity and stays in the documents. The uses block is keyed by the# socket the catalog entity declares, then by the alias you choose for the edge.spec: components: api: type: core/compute/api-server uses: databases: primary: target: my_db inject: env: - in: DB_HOST from: host - in: DB_PORT from: port# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.# The context keys an edge by its alias, so the socket does not reappear here.spec: capability: helm valuesMapping: | { "db_host": "{{ .context.uses.primary.provides.host }}" }helm에서 작성자가 제공한 차트의 경우, my_db라는 이름의 컴포넌트는 릴리스 이름 my-zudb로 리소스를 렌더링합니다. 따라서 생산자의 차트는 metadata.name이 my-zudb인 Service를 내보내고, 게시되는 host는 my-zudb.svc.cluster.local이며, 소비자는 값을 .context.uses.primary.provides.host로 읽든 주입된 DB_HOST로 받든 실제로 존재하는 Service에 연결합니다.
그 자리에 {{ .context.uses.primary.target }}을 쓰면 대신 my_db.svc.cluster.local이 게시됩니다. 이 값은 잘못되어 보이지 않습니다. 개발자가 작성한 식별자를 작성한 그대로 표기한 것이기 때문입니다. 단지 어떤 Service도 가리키지 않을 뿐이며, 빌드는 이를 전혀 알려 주지 않습니다.
두 키를 한 쌍으로 보기
어느 키도 단독으로는 의미가 분명하지 않습니다. 각 키는 다른 키가 아닌 것으로 정의되기 때문입니다.
| 키 | 가리키는 이름 |
|---|---|
{{ .context.instance_id }} | 노드의 아이덴티티이자, 이 노드를 위해 빌드된 리소스 중 어떤 provider도 이름을 도출하지 않는 리소스의 이름입니다. artifacts: 블록에서 배치된 아티팩트 세트, 그리고 compose처럼 아이덴티티를 따라 이름을 붙이는 provider가 workload: 블록에서 합성한 워크로드가 이에 해당합니다. 항상 존재합니다. |
{{ .context.rendered_name }} | 바인딩된 provider가 이 노드를 위해 렌더링하는 리소스에 대해 도출하는 이름입니다. 직접 제공한 소스의 경우, 제공한 템플릿이 리소스를 렌더링할 때 기준으로 삼는 이름(예: 차트가 읽는 릴리스 이름)입니다. provider가 합성하는 workload:의 경우, helm처럼 아이덴티티가 아닌 자체 이름을 따라 리소스 이름을 붙일 때 그 리소스에 부여하는 이름입니다. 해당 provider가 이름을 도출하는 경우에만 존재합니다. Feature 연결 자체의 템플릿에서는 호스트 컴포넌트의 이름입니다. 아래를 참조하십시오. |
이렇게 나뉘는 것은 이름이 어디에서 사용 가능해야 하는지에 따른 것입니다. 직접 제공한 차트나 모듈에는 템플릿이 있고, 그 템플릿은 플랫폼이 전달하는 아이덴티티를 따라 리소스 이름을 붙입니다. 따라서 그 이름은 해당 플랫폼이 사용할 이름이어야 하며, 해당 플랫폼의 문자 체계로 표기되어야 합니다. 합성된 워크로드에는 직접 작성한 템플릿이 없지만, 그 리소스도 플랫폼이 허용하는 이름을 가져야 합니다. 작성된 이름에 들어갈 수 있는 모든 문자를 이름에 허용하는 provider는 아이덴티티를 따라 이름을 붙이고, 그렇지 않은 provider는 자신이 도출한 이름을 따라 이름을 붙인 뒤 그 이름을 여기에 보고합니다. 따라서 이름을 예측할 필요가 없습니다.
제공된 소스와 workload:를 모두 선언한 노드는 두 종류의 출력을 동시에 생성하며, 세 번째 키가 필요하지 않습니다. helm에서는 두 출력 모두 하나의 릴리스 이름을 따라 이름이 붙으므로 rendered_name이 양쪽에 모두 쓰입니다. 차트 자체의 리소스는 템플릿이 어떻게 구성하든 이 이름을 가지며, 합성된 각 Service는 <rendered_name>-<service key>입니다. 합성된 워크로드에 아이덴티티를 따라 이름을 붙이는 provider에서는 해당 워크로드의 리소스 이름에 instance_id를, 제공된 출력의 리소스 이름에는 provider가 그에 대해 보고하는 값을 사용하십시오.
두 이름이 달라질 수 있는 이유는 문자 체계에 있습니다. 작성된 컴포넌트 이름에는 밑줄이나 대문자가 들어갈 수 있지만 차트의 릴리스 이름에는 들어갈 수 없습니다. 이러한 문자를 비슷한 문자로 합치면 구별 가능한 두 컴포넌트가 클러스터에서 하나의 이름이 될 수 있으므로, 도출 과정에서는 대신 그 문자를 풀어 씁니다. 해당 provider의 문자 체계와 길이 제한은 ../providers/helm.md의 “How the release name is derived”를 참조하십시오.
이름을 보고하는 provider와 나머지가 보고하지 않는 이유
helm은 하나를 보고합니다. 바로 release 이름입니다. 소스로 지정된 차트는 이를 .Release.Name으로 읽고
일반적으로 자신의 리소스 이름을 이에 따라 짓습니다. provider 역시 component에 대해 합성하는 모든 리소스의 이름을 이에 따라
짓습니다. 컨트롤러는 release 이름 그대로, 각 Service는 <release name>-<service key>로 짓습니다. 따라서 어느 종류의 출력에 대해 게시된 주소든 rendered_name으로 구성됩니다. 아티팩트 세트만 배치하는 노드에 대해서는
아무것도 보고하지 않습니다. 그 세트 안의 이름은 작성자가
쓴 이름이기 때문입니다.
# A synthesized helm Recipe publishing the address of the Service its workload# declares under the key `default`.spec: capability: helm workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "valkey/valkey:8" ports: redis: 6379 services: default: type: ClusterIP ports: redis: 6379 provides: host: "{{ .context.rendered_name }}-default" port: "6379"cache라는 이름의 component는 cache-default를 게시하고, my_cache라는 이름의 component는
my-zucache-default를 게시합니다. 두 경우 모두 빌드가 내보내는 Service의 이름입니다.
나머지 네 provider는 아무것도 보고하지 않으며, 그 이유는 서로 같지 않습니다. 그중 어느 것도 지원을 기다리고 있는 provider가 아닙니다. 각 경우에 보고할 파생 이름이 없거나, 원하는 이름에 이미 다른 방법으로 접근할 수 있습니다.
-
cloudformation과compose— 이름을 직접 작성했거나, 식별자가 곧 이름입니다. cloudformation Recipe는 리소스의 논리 id를 직접 작성하며 provider는 이를 작성된 그대로 읽습니다. 직접 제공한 compose 파일은 자체 서비스의 이름을 정하며, provider는 그 파일 안의 어떤 것도 바꾸지 않고 파일을 병합하고 레이블을 붙입니다.compose가 합성하는 workload는 노드의 식별자에 따라 이름이 지어지며, compose 파일은 이를 작성된 그대로 허용하므로{{ .context.instance_id }}가 곧 그 이름입니다. 보고할 파생이 없으며, 이름은 직접 작성한 문서에 있는 그대로입니다. 그 이름은 workload의 메인 서비스, 즉 피어가 접근하는 서비스의 이름입니다. workload가 가진 사이드카 또는 init 서비스는 사이드카 또는 init 서비스의 이름이 정해지는 방식에서 설명하듯 같은 식별자와 컨테이너 이름을--로 연결하여 이름이 지어집니다. -
terraform— 이름은 파일이 배치된 위치에 따라 결정됩니다. 기여자의module블록은 그 구성이 기록된 출력 디렉터리를 바탕으로 이름이 지어지며, 이는 노드가 렌더링될 때가 아니라 경계의 파일이 조립될 때 정해집니다. Recipe의 템플릿이 실행되는 시점에는 그 위치가 아직 존재하지 않습니다. -
helm-chart— 이 provider가 파생하는 이름은 배치된 차트 자체의 주소이며, 이는 그 차트의 템플릿이 렌더링 기준으로 삼는 이름과는 다른 것입니다. 이 provider는 벤더링한 차트의name필드를 그 차트를 기여한 대상의 인코딩된 식별자로 설정합니다. 이는 umbrella 차트가 그 하위 차트를 바인딩하는 별칭이자 그 값의 범위를 지정하는 키이기도 합니다. component의 경우 그 식별자는{{ .context.instance_id }}가 담고 있는 값이므로, 배치된 차트의 이름에는 이미 그것이 무엇인지 나타내는 키로 접근할 수 있습니다. 벤더링한 차트 자체의 템플릿이 렌더링 기준으로 삼는 이름은 release 이름이며, 이는 이 provider가 파생하는 것이 아니라 umbrella의 release가 설치 시점에 제공합니다. 따라서 여기에는 이 키가 보고할 그러한 이름이 없습니다.../providers/helm-chart.md의 “The chart name the umbrella owns”를 참조하십시오.
이름이 보고되지 않는 곳에서 키 읽기
Provider가 그러한 이름을 보고하지 않는 노드에서 {{ .context.rendered_name }}를 읽으면 빌드가 중단되며, 진단은 대신 어떤 키를 작성해야 하는지 알려 줍니다. 빈 값을 렌더링하지 않습니다. 세그먼트 하나가 빠진 주소는 배포되어 버리는 잘못된 아티팩트이며, 이는 멈추는 빌드보다 더 나쁩니다.
중단 시 어떤 해결책을 제시하는지는 참조를 작성한 위치가 아니라 노드에 따라 달라집니다.
- 자체 소스를 전혀 제공하지 않는 노드가 그 노드에 대해 이름을 보고하지 않는 provider 아래에 있으면, 그 노드의 리소스는 노드의 식별자를 따라 이름이 지정되므로 중단 시
{{ .context.instance_id }}를 제시합니다. 올바른 값이 있으며 진단이 그 값을 알려 줍니다. - 소스를 제공하는 노드가 그 노드에 대해 이름을 도출하지 않는 provider 아래에 있으면, 대체할 값이 없습니다. 이 경우 식별자를 안내하면 노드가 갖고 있지 않은 리소스를 가리키게 되므로, 중단 시 대체 값을 제시하는 대신 대체 값이 없다고 알려 줍니다.
이 거부는 provides:와 Recipe가 인라인으로 작성하는 다른 모든 템플릿에 적용됩니다. 즉 valuesMapping:, workload: 본문, 각 artifacts: 항목, 각 파이프라인 단계의 with: 및 when:입니다.
🔴 두 가지 가져오기 형식은 모두 그 범위 밖에 있습니다. $import:를 통해 제공되는 valuesMapping:, workload: 또는 artifacts: 항목은 가져오기가 로컬 파일을 가리키든 라이브러리 항목을 가리키든 렌더링이 이를 해석하기 전까지 Recipe 안에 텍스트가 없으므로, 그러한 본문 안에서 이 키를 참조해도 검사되지 않습니다.
가져오는 노드의 provider가 이름을 보고하는 경우에는 그 이름이 렌더링되고, 보고하지 않는 경우에는 중단 대신 빈 값이 렌더링됩니다. 따라서 가져온 본문은 그 본문을 가져오는 모든 Recipe가 이름을 보고하는 provider를 바인딩할 때만 이 키를 읽어야 합니다. 예를 들어 차트를 소싱하는 helm Recipes를 위해 작성되고 설명에 그렇게 명시한 라이브러리 항목이 이에 해당합니다. provider가 이름을 보고하지 않을 수 있는 가져오는 쪽을 위한 본문은 대신 가져오는 Recipe가 설정하는 값을 통해 이름을 받습니다.
Recipe의 locals: 항목은 이 키를 전혀 읽지 않습니다. local은 Recipe의 source: 템플릿과 컨텍스트를 공유하며, 노드가 소스를 제공하는지 여부는 이름이 의존하는 요소 중 하나이므로 그곳에서는 이름이 제공되지 않습니다. 따라서 local에서 {{ .context.rendered_name }}를 참조하면 provider가 무엇을 보고하든 렌더 컨텍스트가 정의하지 않는 참조에 대한 진단(E0060)과 함께 중단되며, 이 진단은 그곳에서 .context가 제공하는 유일한 키로 .context.instance_id를 나열합니다. 이 키는 그것이 필요한 provides: 항목이나 인라인 템플릿에서 읽으십시오.
Feature 어태치먼트 자체의 템플릿에서
Feature attachment의 FeatureRecipe가 작성하는 템플릿, 즉 locals:, source:, provides:,
injectMapping:, valuesMapping:, workload:, 각 artifacts: 항목, 각 파이프라인 단계의
with:와 when:에서 {{ .context.rendered_name }}은 호스트 component의 이름입니다. 즉 호스트 자체의 provider가 호스트를 위해 렌더링하는 리소스에 대해 보고하는 이름이며, 호스트 자체의 Recipe가 읽는 값입니다. 이 키는 {{ .context.instance_id }}와 짝을 이루며, 이 템플릿들에서 그 키는 호스트
component의 식별자입니다. attachment 자체는 .attachment_name입니다. component의 connection 중 하나에 작성된 attachment는 소비하는 component의 이름을 읽습니다. 그 component가 해당 attachment의 호스트이기 때문입니다.
어태치먼트 자체의 리소스 이름은 이 키로 구성합니다. Secret,
라우트 또는 정책의 이름을 연결된 컴포넌트를 따라 짓는 FeatureRecipe에는 플랫폼이 허용하는 이름이 필요하며, 작성된 그대로의 호스트 식별자는 밑줄이나 대문자를 포함하는 경우 그러한 이름이 아닙니다.
helm에서 my_db라는 컴포넌트는 my-zudb를 보고하므로, 어태치먼트 root에 대해
{{ .context.rendered_name }}-{{ .attachment_name }}라는 이름의 Secret은
my-zudb-root로 렌더링됩니다. 반면 {{ .context.instance_id }}는 클러스터가 거부하는 my_db-root를 제공합니다.
이 값은 어태치먼트가 어떤 provider를 통해 렌더링되든 호스트의 값으로 유지됩니다.
이 키는 호스트의 provider가 이름을 보고하는 모든 곳, 즉 helm에서 Recipe가 차트를 제공하거나 workload:를 선언하는 호스트에 존재하며, 이름을 보고하지 않는 곳, 즉 아티팩트 세트만 배치하는 호스트와 다른 provider의 호스트에는 없습니다. 그러한 호스트의 어태치먼트에서 이 키를 읽으면 렌더 컨텍스트가 정의하지 않는 참조에 대한 진단(E0060)과 함께 빌드가 중단되며, 이 진단은 그곳에서
.context가 정의하는 키를 나열합니다. {{ .context.instance_id }}가 그중 하나이며, 그러한 호스트에서는 호스트 자체의 리소스가 이 값을 따라 이름이 지정되므로, 이름을 보고하지 않을 수 있는 호스트를 위해 작성된 FeatureRecipe는 대신 식별자를 읽습니다.
이 거부는 FeatureRecipe가 인라인으로 작성하는 템플릿 중 injectMapping:을 제외한 템플릿에 적용됩니다.
injectMapping:, 그리고 FeatureRecipe가 $import:를 통해 제공하는 valuesMapping:, workload: 또는 artifacts: 항목은 검사되지 않습니다. 이름을 보고하지 않는 호스트에서는 그곳의 참조가 중단 대신 빈 값을 렌더링합니다.
어태치먼트가 작성자가 제공한 차트를 전달하는 경우, 그 차트의 템플릿은 의도적으로 호스트 컴포넌트의 릴리스 이름을 기준으로 렌더링됩니다. 대신 어태치먼트에서 이름을 도출하면 차트 작성자가 선언했고 이미 배포했을 수도 있는 리소스의 이름이 바뀌기 때문입니다. .attachment_name은 한 호스트의 두 어태치먼트를 구별하는 값입니다. ../providers/helm.md의
“How the release name is derived”를 참조하십시오.
connection의 attachment에서 파생되는 이름
connection이 지니는 attachment는 소비하는 component의 attachment이며, 이름은 <alias>.<slot>입니다. 예를 들어 별칭 gpt로 작성된 connection의 credential 슬롯에 대해서는 gpt.credential입니다(Aggregate의 connection 항목 참조). 이렇게 합성된 이름이 해당 FeatureRecipe가 렌더링할 때 기준으로 삼는 .attachment_name이며, 이 이름에는 점이 포함됩니다.
여기에서 두 종류의 이름이 생기며, 두 이름은 점을 서로 다르게 다룹니다.
FeatureRecipe가 합성하는 이름은 그 템플릿이 쓰는 내용을 그대로 유지합니다. 표준 라이브러리의 credential 구현은 리소스 이름을 {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}로 짓습니다. 따라서 이름이 router인 component의 gpt connection에 있는 credential은 점을 포함한 router-gpt.credential이라는 이름의 리소스로 렌더링되며, 이는 유효한 Kubernetes 객체 이름입니다. 이 종류의 이름에서 점은 템플릿이 점을 유지할 때에만 남습니다.
빌드가 attachment의 식별자에서 파생하는 이름은 점을 풀어 씁니다. 식별 레이블과 출력 파일은 host component와 attachment 이름으로부터, 식별자에서 파생되는 모든 이름이 거치는 것과 같은 인코딩을 통해 합성되며, 이 인코딩은 점을 zd로, 대문자를 그 코드 포인트의 이스케이프로 씁니다. 식별자가 레이블뿐 아니라 리소스 이름으로도 쓰이는데, Service 이름은 둘 다 허용하지 않기 때문입니다. 별칭 gptPro 아래에 작성된 연결은 cfr--router--gpt-zx000050ro-zdcredential이 됩니다. 위의 리소스에는 aggrega.ai/component-id: cfr--router--gpt-zdcredential 레이블이 붙고(app.kubernetes.io/name도 마찬가지입니다), helm provider에서는 router--gpt-zdcredential--router-secret-router-gpt-credential.yaml로 출력됩니다. 점이 대체되지 않고 풀어 쓰이는 이유는 명명 관례의 “The separator does not reach a name(구분자는 이름에 도달하지 않음)”을 참조하십시오.
관련 문서
- 템플릿 컨텍스트 계약 — 이 키들이 속한 컨텍스트의 전체 구조입니다.
- 템플릿 확장 매트릭스 — 각 템플릿 위치가 읽는 기둥입니다.
- 토폴로지 삼요소:
provides,inject,uses— 게시된 값이 에지를 건너 소비자에게 전달되는 방식입니다. - 명명 관례 — 컴포넌트 이름으로 쓸 수 있는 것과, 더 좁은 문자 집합에서 이름이 치르는 비용입니다.
errors/fatal-halts.md— 이 페이지가 설명하는 중단과 그 출력 메시지입니다.