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

기반의 Recipe가 처리하는 게시된 래퍼

이 예제가 가르치는 것은 한 가지입니다. 다른 Component를 extends하는 Component는 그 기반의 데이터 계약 전체를 상속하므로, 기반을 위해 작성된 모든 Recipe는 이미 확장하는 Component를 구현합니다. 따라서 표준 라이브러리 컴포넌트의 특수화된 변형을 게시하는 비용은 카탈로그 엔터티 하나와 Manifest 한 줄입니다. 별도의 Recipe도 필요 없고 기반을 변경할 필요도 없습니다.

여기서 래퍼는 **example/gateway/nginx-reviewed**입니다. 이 래퍼는 카탈로그에서 자신이 확장하는 컴포넌트인 core/gateway/nginx 옆에 함께 제공됩니다.

래퍼가 추가하는 것과 상속하는 것

래퍼가 작성하는 부분 전체는 메타데이터와 소켓 하나뿐입니다.

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited는 확장하는 Component가 schema: 블록 대신 작성하는 리터럴 표시입니다. 이는 세 가지 데이터 기둥인 values, infra, provides가 기반이 작성한 그대로 기반의 것임을 나타냅니다. 래퍼는 자체 기둥 키를 선언하지 않으며 선언할 수도 없습니다. 계약은 체인의 모든 깊이에서 기반에 속합니다.

래퍼가 언급하지 않는 모든 것은 상속됩니다. aggrega inspect example/gateway/nginx-reviewed --resolved는 병합된 엔터티를 보여 주며, 그중 두 가지를 자세히 살펴볼 만합니다.

  • 하나가 아닌 세 개의 uses 소켓: upstream과 guard(기반의 것으로, upstream은 component.aggrega.ai/type=server를 선택함), 그리고 reviewed_upstream(래퍼의 것)입니다. 확장은 소켓을 추가하며, 집합을 대체하지 않습니다.
  • 기반의 세 기둥, 원문 그대로 — values.upstream_path, infra.port / engine_version / compute / overrides, provides.host / port / protocol이며, 각각 기반 자체의 설명을 가집니다.

소비하는 Aggregate가 작성하는 내용

aggregate-reviewed.yaml은 데이터베이스 콘솔 앞에 놓이는 두 개의 게이트웨이 계층을 래퍼로 선언합니다.

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

주목할 키는 upstream_path입니다. 이 키는 core/gateway/nginx의 values 기둥에 선언되어 있고 래퍼의 파일 어디에도 나타나지 않지만, 작성자가 래퍼 인스턴스에 이 키를 작성하면 렌더링된 게이트웨이 구성에 반영됩니다. 기둥을 통째로 상속한다는 것은 실제로 이런 의미입니다.

나머지 절반은 Manifest이며, 타입마다 한 줄입니다.

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

두 게이트웨이 줄은 모두 같은 Recipe를 지정합니다. compose/nginx는 implements: core/gateway/nginx:1.0.0을 선언하며, 기반을 지정하는 Recipe는 그 기반을 확장하는 모든 Component의 구현이므로 래퍼는 변경 없이 그 Recipe로 처리됩니다. 여기서는 두 가지 사실이 동시에 성립하며, 이 둘은 별개입니다.

  • Recipe가 일치합니다. 래퍼 자체 타입을 구현하는 Recipe는 존재하지 않으며, 필요하지도 않습니다.
  • 매핑은 여전히 필요합니다. Recipe 선택은 정확한 매핑 키로 이루어지므로 래퍼에는 자체 type 항목이 필요합니다. 래퍼는 기반의 항목을 상속하지 않습니다. 자체 항목이 없는 래퍼 인스턴스는 기반이 매핑되어 있더라도 매핑되지 않은 인스턴스 진단과 함께 중단됩니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example extends-wrapper

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd extends-wrapper

빌드

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

렌더링된 출력과 잠금 파일은 제공되는 것이 아니라 생성됩니다. 이 예제는 입력만 커밋하고 나머지는 모두 다시 생성합니다. --auto-pull은 빌드 중에 잠금 파일을 해석합니다. 미리 aggrega pull --release release-reviewed.yaml을 한 번 실행해도 같은 일을 하며, 이후 빌드는 플래그 없이 실행할 수 있습니다.

래퍼와 래퍼가 확장하는 기반은 모두 공유 카탈로그에 있으며, 이 카탈로그는 .aggrega-config.yaml이 선언하는 기본 레지스트리인 hub.aggrega.ai에서 해석됩니다. 빌드 명령에는 --catalog 플래그가 필요 없으며, 이 디렉터리에서 실행하는 aggrega inspect도 마찬가지입니다.

래퍼가 core/gateway/nginx를 확장하므로 pull은 이를 가져옵니다. 베이스는 그것을 확장하는 모든 것의 의존성이므로, pull은 래퍼의 extends:를 따라가며 Manifest가 베이스를 지정하는지와 관계없이 잠금 파일에 베이스를 고정합니다. 여기서 Manifest가 베이스를 매핑하는 데는 다른 이유가 있습니다 — 아래의 대조 릴리스가 베이스 자체의 인스턴스를 선언하기 때문입니다.

렌더링된 dist/compose/docker-compose.yaml에 그 증거가 담겨 있습니다.

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

증명하는 내용 순서대로 세 가지를 읽어 봅니다.

  • aggrega.ai/recipe-uri: nginx:1.0.0 — 기반의 Recipe가 이 서비스를 만들었습니다. 래퍼 인스턴스의 출처 레이블이 기반의 Recipe를 가리키는 것은 그것이 인스턴스를 렌더링한 Recipe이기 때문입니다.
  • location /api/ — 기반만 선언하는 키인 values.upstream_path가 래퍼 인스턴스에 작성되어 렌더링되었습니다.
  • proxy_pass http://internal:8081 — reviewed_upstream 엣지가 해석되었습니다. 대상의 provides.host와 provides.port가 기반의 Recipe가 읽는 전달 키 아래로 주입 컨텍스트에 도착했으므로, 래퍼가 추가한 소켓은 그 소켓을 전혀 모르는 Recipe를 통해 흐릅니다.

빌드가 해석하는 잠금 파일은 리졸버 측에서 같은 사실을 기록합니다. 하나의 다이제스트에 있는 하나의 compose/nginx:1.0.0 항목이 기반의 타입과 래퍼의 타입, 두 매핑 키 모두에서 참조됩니다.

래퍼의 레이블과 어노테이션은 해석된 엣지와 함께 전달됩니다. 소비하는 노드의 렌더 컨텍스트는 각 대상의 provides, labels, 어노테이션을 담고 있으므로, edge의 컨텍스트는 업스트림이 audit-tier=reviewed이며 누가 검토했는지를 압니다. 그중 어떤 것이 렌더링된 아티팩트에 나타날지는 Recipe가 선택합니다. 이 레이블과 어노테이션은 셀렉터와 정책이 읽는 컴포넌트 식별 정보이지, 컴파일러가 찍어 내는 출력이 아닙니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `extends-wrapper` 폴더가 없으면 `example`을 `extends-wrapper`로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `extends-wrapper` 폴더에 씁니다. 그런 다음 `workspace_root`를 `extends-wrapper`로, `release`를 `release-reviewed.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 쓴 파일을 알려 주십시오. 파일은 `extends-wrapper/dist/` 아래에 있습니다.

대조군: 추가된 레이블의 용도

aggregate-unreviewed.yaml은 aggregate-reviewed.yaml에서 한 가지만 수정한 것으로, 내부 계층을 래퍼 대신 기본 core/gateway/nginx 기반으로 선언합니다. 이 파일은 실패하는 것이 예상됩니다.

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

이 중단이 바로 교훈입니다. 기반은 자체 upstream 소켓을 충족합니다. 기반은 component.aggrega.ai/type=server이며, 내부 계층은 그 소켓을 통해 정확히 같은 방식으로 연결됩니다. 하지만 기반에는 audit-tier 레이블이 없으므로 래퍼의 더 엄격한 소켓이 이를 거부합니다. 래퍼가 추가하는 레이블이 래퍼의 인스턴스를 선택 가능하게 만들며, 이는 셀렉터에서 드러납니다.

알아 둘 만한 중단이 두 가지 더 있으며, 둘 다 스키마가 제 역할을 하는 것입니다.

  • extends를 선언하면서 schema: 아래에 기둥 내용을 작성하는 Component는 문서를 로드할 때 해당 제약을 명시하며 거부됩니다. schema:를 완전히 생략하는 Component도 마찬가지입니다. schema: inherited만 허용되는 형식이며, 이를 암시하지 않고 명시적으로 작성하게 하므로 독자는 상속된 기둥 블록을 잊어버린 블록과 혼동할 수 없습니다.
  • 기반이 선언하지 않는 values 키는 래퍼 인스턴스에서 작성된 경로에서 거부됩니다. 적용되는 계약이 기반의 것이기 때문입니다.

이것이 유용한 이유

표준 라이브러리 컴포넌트에 대해 검토된 형태를 정한 조직은 그것을 보관할 곳이 필요합니다. 글로만 남겨 두면 레이블, 어노테이션, 소켓이 필요한 모든 Aggregate에서 반복해서 기술되고, 그러면서 서로 어긋나게 됩니다. 기반을 확장하는 Component로 게시하면 그 형태는 이름을 가진, 버전이 관리되고 검토 가능한 카탈로그 엔터티가 됩니다. 이를 소비하는 팀은 type: example/gateway/nginx-reviewed와 Manifest 한 줄을 작성하고, 기반이 지원하는 모든 대상에서 기반의 계약 전체와 그에 대해 이미 작성된 모든 Recipe를 함께 상속합니다.

이것이 작동하는 이유는 래퍼의 비용에 있습니다. 래퍼는 구조와 메타데이터만 추가하고 그 외에는 아무것도 추가하지 않습니다. 기둥을 선언하지 않으므로 래퍼의 인스턴스와 기반의 인스턴스는 하나의 계약에 대해 검증되며, 기반을 위해 작성된 Recipe는 기반의 특수화 때문에 예상치 못한 상황을 맞을 일이 없습니다.