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

실행 가능한 예제

먼저 시작하기에서 Aggrega를 설치하고 이 예제 중 두 가지를 한 단계씩 따라갑니다.

aggrega CLI로 컴파일할 수 있는 완전하고 포크 가능한 워크스페이스입니다. 각 예제는 자체 완결된 디렉터리로, 개발자가 작성한 Aggregate 하나와 하나 이상의 Release/Manifest 쌍으로 구성되며, 해당 페이지에 명시된 것 외에는 별도 설정 없이 빌드됩니다. 배포하는 제품이나 보여 주는 내용으로 예제를 찾으려면 여기의 모든 예제를 나열한 제품 및 기능별 예제를 사용하십시오.

예제는 두 가지 모드로 제공되며, 이는 하나의 커리큘럼의 양 끝입니다:

  • 소비 — 워크스페이스는 표준 라이브러리 카탈로그 엔터티를 참조하고 교육용으로 특화된 자체 콘텐츠만 로컬에서 작성합니다. --catalog 플래그 없이 빌드됩니다:

    Terminal window
    aggrega build --release release.yaml

    참조된 엔터티를 어디에서 읽는지는 워크스페이스에 따라 다릅니다. 워크스페이스 루트의 catalog/ 디렉터리는 무엇이 이를 지정하든 지정하지 않든 읽히므로, 자체 교육용 콘텐츠를 작성하는 워크스페이스는 그 콘텐츠를 그곳에 두기만 하면 됩니다. .aggrega-config.yaml을 가진 워크스페이스는 catalog_dirs 아래에 나열된 모든 디렉터리도 읽으며, 각각은 엔터티를 보관하는 디렉터리입니다. 나열된 디렉터리가 먼저 검색되고 catalog/는 마지막에 검색되며, 이 스택은 먼저 찾은 것이 우선하므로 먼저 검색된 디렉터리의 엔터티가 나중 디렉터리에 있는 같은 식별자의 엔터티를 가립니다. 어떤 로컬 디렉터리도 선언하지 않는 것, 즉 표준 라이브러리 엔터티는 구성이 default_registry로 지정하는 레지스트리인 hub.aggrega.ai에서 해석됩니다. 로컬에서 아무것도 작성하지 않는 워크스페이스에는 로컬 항목이 필요 없으며, catalog/ 디렉터리도 .aggrega-config.yaml도 없는 워크스페이스는 전적으로 구성된 레지스트리를 통해 해석됩니다. catalog_dirs를 빈 목록으로 작성하면 워크스페이스에 로컬 카탈로그가 전혀 없다는 뜻입니다. catalog_dirs의 모든 경로는 워크스페이스 안의 디렉터리를 지정하므로, 워크스페이스 전체를 다른 곳으로 복사해도 그대로 빌드됩니다.

    대상별로 별도의 카탈로그를 유지하는 다중 대상 워크스페이스는 각 대상의 디렉터리를 workspace.releases 아래에 Release 파일을 키로 하여 지정하므로, 모든 Release가 각자의 카탈로그에 대해 빌드됩니다.

  • 작성 — 워크스페이스는 카탈로그 엔터티(Components, Features, Recipes)를 로컬 catalog-*/ 디렉터리에서 처음부터 빌드합니다. mariadb-adminer가 작성 예제이며, 이 예제가 빌드하는 엔터티는 소비 예제가 소비하는 것과 같은 종류입니다.

aggrega build --release <release file>로 실행마다 release 하나를 빌드합니다. 각 예제의 페이지에 그 예제의 명령이 나와 있습니다. 워크스페이스는 위에서 설명한 대로 카탈로그를 제공합니다. 워크스페이스가 지정하지 않은 카탈로그 디렉터리에는 직접 --catalog를 전달하십시오. 필요한 페이지에 그 방법이 나와 있습니다.

Lockfile은 배포되지 않고 생성되므로 새로 클론한 저장소에는 lockfile이 없으며 첫 빌드에 lockfile이 필요합니다. aggrega build는 기본적으로 읽기 전용이므로 lockfile이 없으면 중단하고 진행할 수 있는 두 가지 방법을 알려 줍니다. 첫 빌드에서는 --auto-pull을 전달하여(aggrega build --release release.yaml --auto-pull) 빌드 중에 lockfile을 해석합니다. 미리 aggrega pull --release <release file>을 한 번 실행해도 같은 효과가 있으며, 이후의 모든 빌드를 플래그 없이 실행할 수 있습니다.

문서 저장소의 체크아웃에서는 대부분의 워크스페이스에 build-release.sh 헬퍼도 들어 있으며, 저장소 자체의 점검은 이를 통해 빌드합니다. 이 헬퍼는 release 하나에 대해 aggrega build를 실행하고, 먼저 그 명령을 출력하며, 사용한 aggrega 바이너리와 그 출처를 보고합니다. 바이너리를 선택하려면 AGGREGA_BIN을 설정하십시오. aggrega scaffold --example로 작성된 사본에는 헬퍼가 들어 있지만 헬퍼가 호출하는 공유 스크립트는 없으므로, 그런 사본은 aggrega build로 직접 빌드하십시오.

여기의 예제가 표준 라이브러리 카탈로그의 체크아웃을 언급하는 경우, 그것을 어디에서 얻는지는 가져오기에서 설명합니다.

이 예제들은 예제 개요에 설명된 개념 페이지를 보완합니다. 개념 페이지는 하나의 개념을 설명하고 그것을 보여 주는 워크스페이스에 링크합니다. 여기의 워크스페이스는 빌드하고 읽고 응용할 수 있는 완전한 스택입니다.

페이지에 빌드 결과가 출력되어 있는 경우, 그 블록은 실제 실행에서 복사한 것이므로 자신의 출력과 비교할 수 있으며, 생략된 줄은 표시되어 있습니다. 이 페이지의 출력 읽기에서 그 관례와 사용하는 표시를 설명합니다.

여기 있는 모든 디렉터리가 하나의 워크스페이스인 것은 아닙니다. 빠른 시작 예제는 단계마다 워크스페이스를 하나씩 두고, 가져오기 예제는 다음 단락에서 설명하듯 가져오기의 단계마다 하나씩 둡니다. 한 디렉터리에는 워크스페이스가 전혀 없습니다. policy-in-ci에는 빌드 출력 디렉터리를 읽고 규칙을 위반하면 이를 거부하는 규칙 스크립트 두 개가 각각의 파이프라인 단계와 함께 들어 있습니다. 이 스크립트는 여기 있는 워크스페이스의 출력과 여러분의 출력에 대해 실행됩니다.

각 import-* 예제는 제품 및 기능별 예제의 import 기능 아래에 나열되어 있으며, 다른 형식으로 작성된 프로젝트를 aggrega import가 받는 그대로 두 폴더에 보관합니다. source/는 프로젝트, 이를 워크스페이스로 만드는 .aggrega-config.yaml, 그리고 어떤 소스에도 담을 수 없는 값을 가져오기가 읽어 들이는 응답 파일이고, draft/는 가져오기가 작성한 파일을 변경 없이 담은 것으로서 작성된 그대로 빌드되는 워크스페이스이며, 표준 출력(stdout.txt)과 표준 오류(import.txt)에 출력한 내용도 함께 담습니다. 가져오기 아래의 연습 안내가 각 단계를 설명합니다. 그 check.sh는 이 저장소의 공유 스크립트 scripts/check-import-example.sh를 실행하는데, 이 스크립트는 다시 가져오기를 수행해 작성하고 출력한 내용을 draft/와 비교하고 연습 안내가 인용하는 블록을 예제의 파일과 비교한 다음, 초안으로 작성된 Release를 검증하고 빌드합니다.

학습 순서

여기 있는 모든 예제는 헤더의 tier와 position으로 정해지는 단일 학습 순서 안에서 하나의 자리를 차지합니다. 티어 목록이 제시하는 순서대로 티어별로, 각 티어 안에서는 가장 간단한 것부터 배치됩니다. 학습 순서대로는 모든 예제를 이 방식으로 나열하며, 사이드바의 예제 섹션도 같은 순서를 따릅니다. 티어를 위에서 아래로 읽거나, 지금 하는 작업에 맞는 티어로 바로 이동할 수 있습니다. 대신 배포하는 대상이나 보여 주는 내용으로 예제를 찾으려면, 같은 페이지에서 제품별, 기능별 목록을 볼 수 있습니다.

빌드는 렌더링한 결과에 대해 플러그인을 실행할 수도 있습니다. 파이프라인 단계를 사용해야 할 때를 참조하십시오.

각 예제의 헤더

각 예제의 README는 YAML front matter로 작성된 짧은 헤더로 시작하며, 예제가 무엇인지, 즉 수준, 학습 순서에서의 위치, 배포하는 제품, 보여 주는 내용을 밝힙니다. 제품 및 기능별 예제는 이 헤더들로부터 생성됩니다.

---
example:
level: start
tier: catalog-only
position: 1
products: [core/datastore/mariadb, core/devtool/adminer]
shows: [connections, credentials]
---

level은 다음 수준 중 하나입니다:

  • start — “카탈로그 전용” 수준: 카탈로그 엔터티로 조립되며, Aggregate, Manifest, Release 외에는 아무것도 작성하지 않습니다.
  • authoring — “작성” 수준: Component, Feature 또는 Recipe를 작성하거나 그 형태를 보여 줍니다.
  • advanced — “고급” 수준: 경계, 거버넌스 정책, 어노테이션 기반 Features, 조립된 클라우드 스택.

tier는 예제가 속한 학습 순서의 부분으로, 다음 단계 중 하나이며 이 순서대로 다룹니다:

  • start-here — 여기서 시작: “시작하기” 가이드가 한 단계씩 확장하는 두 예제와, 그다음 클라우드용 시작 예제 두 개입니다.
  • catalog-only — 카탈로그 전용: 카탈로그 엔터티로 조립되며, Aggregate, Manifest, Release 외에는 아무것도 작성하지 않습니다.
  • authoring — 작성: 자체 Component, Feature 또는 Recipe를 작성하거나, 그 구성 방식을 보여 줍니다.
  • advanced — 고급: 경계, 거버넌스 정책, 어노테이션 기반 Features, 조립된 클라우드 스택을 다루며, 그중 여러 가지를 하나의 빌드에서 결합합니다.
  • importers — 임포터: 다른 형식으로 작성된 프로젝트를 aggrega import로 Aggrega 파일 초안으로 작성한 뒤 검토하고 빌드합니다.

position은 단계 안에서 예제가 차지하는 자리로, 그 단계의 다른 어떤 예제도 쓰지 않는 양의 정수입니다. 단계는 예제를 가장 낮은 위치부터 위로, 가장 간단한 것부터 나열합니다.

products는 예제가 배포하는 각 카탈로그 Component를 해당 카탈로그 항목이 가진 이름으로 나열합니다. 일반 컴퓨팅 컴포넌트(예: core/compute/server)와 예제가 자체적으로 선언한 엔터티는 나열하지 않으므로, 아무것도 나열하지 않는 예제도 있을 수 있습니다.

shows는 예제가 보여 주는 내용을 나열하며, 각 항목은 다음 목록에서 가져옵니다:

  • multi-target — 둘 이상의 대상용으로 빌드되거나 둘 이상의 방식으로 실현되는 하나의 Aggregate.
  • recipe-selection — 어떤 Recipe가 컴포넌트를 실현할지, 또는 어떤 FeatureRecipe가 첨부를 실현할지를 Manifest가 선택하는 것: 유형별, 인스턴스별 또는 대상별.
  • modules — 모듈로 가져온 카탈로그 Aggregate.
  • connections — uses 소켓으로 연결되고 각 엣지를 따라 값이 전달되는 컴포넌트.
  • credentials — 자격 증명 첨부와 각 대상이 이를 전달하는 방식.
  • parameters — 매개변수로 끌어올려져 Release가 채우는 값.
  • features — 라우팅, 모니터링, 예산, 캐시, 마스킹처럼 자격 증명 이외의 목적으로 첨부되는 Features.
  • boundaries — 경계에 배치된 컴포넌트나 모듈, 그리고 그 사이를 넘나드는 것.
  • policy — 빌드 중에 또는 빌드 출력에 대해 빌드를 수락하거나 거부하는 거버넌스 정책.
  • guardrails — 중단되도록 의도된 Release와 중단 시의 메시지.
  • catalog-authoring — 예제를 위해 작성되어 예제 옆에 두거나 카탈로그에 게시한 Component, Feature 또는 Recipe.
  • cloud-infrastructure — 관리형 클라우드 서비스를 위한 Terraform 또는 CloudFormation 출력.
  • external-sources — 렌더링할 것을 가져오는 Recipe: 업스트림 차트, git 저장소 또는 모듈.
  • import — 다른 형식으로 작성된 프로젝트를 aggrega import로 Aggrega 파일 초안으로 작성한 뒤 검토하고 빌드합니다.

예제는 인덱스가 배치할 수 있도록 제품이나 기능을 최소 하나 나열합니다. 그 README에는 ## Scaffold the example 섹션도 있으며, 그 첫 번째 명령 블록에는 aggrega scaffold --example <name>이, 두 번째 명령 블록에는 cd <name>이 들어 있고 바로 뒤에 ## Build 섹션이 이어집니다. 이 섹션의 첫 번째 명령 블록은 aggrega scaffold --example이 그 cd 다음에 실행할 것으로 출력하는 내용입니다. 이 저장소의 루트에서 실행하는 scripts/gen-examples-index.sh --check는 모든 헤더를 이 목록과 대조하고, 두 섹션 중 하나라도 없는 예제와 실행 가능한 check.sh도 build-release.sh도 없는 예제를 거부하며, 인덱스가 최신인지 확인합니다. 인덱스를 다시 쓰려면 --check 없이 실행하십시오.