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

git 저장소에 있는 차트

Helm 차트가 반드시 차트 레지스트리에서 와야 하는 것은 아닙니다. 이 예제는 git 저장소에 있는 차트, 즉 Helm 프로젝트 자체의 hello-world 예제 차트를 가져와 Kubernetes 매니페스트로 빌드합니다.

개발자의 Aggregate는 이에 대해 아무것도 말하지 않습니다. Aggregate는 하나의 core/compute/server를 선언할 뿐이며, 그 서버의 패키징을 어디서 가져올지는 Recipe에서 결정되고 Manifest가 바인딩합니다.

source 블록

catalog/recipe/helm/hello-world-git/1.0.0/recipe.yaml
source:
kind: git-repository
url: https://github.com/helm/examples.git
ref: hello-world-0.1.0
module_subdir: charts/hello-world

세 개의 좌표가 있으며, 각각 서로 다른 질문에 답합니다.

  • url — 복제할 저장소입니다. https://, ssh://, git://를 모두 받아들입니다. 비공개 저장소에는 SSH 에이전트를 통해 SSH로 도달하거나, netrc 파일에 해당 호스트 항목(machine github.com login <user> password <token>)을 두고 HTTPS로 도달합니다. URL 자체에 기록된 자격 증명은 인증에서 설명하는 대로 거부됩니다.
  • ref — 저장소를 읽을 참조로, 태그, 브랜치 또는 커밋입니다. 저장소 작성자가 붙인 이름 그대로이며, 항상 단순한 버전인 것은 아닙니다. 여기서는 태그에 차트 이름도 함께 들어 있습니다.
  • module_subdir — 저장소 안에서 차트에 해당하는 디렉터리입니다. 이 저장소는 그 자체가 차트가 아니라 이 경로 아래에 차트를 담고 있으며, 디렉터리는 아티팩트를 구별하는 요소의 일부입니다. 한 커밋에서 한 저장소의 두 디렉터리는 하나가 아니라 두 개의 아티팩트입니다.

source 종류는 형식이 아니라 전송 방식과 위치를 나타냅니다. 같은 종류로 차트, Terraform 모듈 또는 다른 어떤 파일 디렉터리든 가져올 수 있으며, 디렉터리에 무엇이 들어 있는지는 이를 소비하는 provider가 다룰 일입니다.

lockfile에 기록되는 내용

변경될 수 없는 콘텐츠를 가리키는 것은 커밋뿐입니다. 태그나 브랜치는 저장소가 다른 커밋으로 다시 가리킬 수 있는 이름이므로, aggrega pull은 참조를 해석하여 작성한 참조와 그 참조가 해석된 커밋을 모두 기록합니다.

# release-chart.lock
source_artifacts:
- kind: git-repository
url: https://github.com/helm/examples.git
module_subdir: charts/hello-world
pinned_version: f3dc419e558e6ccebce2ed447384e5d2e11de2f9
digest: sha256:2bee62cfc2efccc61d8e17efeb72f9f77ad7bd87f3ea4e50b1e4219c8d5a2c78
mediatype: application/gzip
referenced_by:
- entity: recipe
uri: helm/hello-world-git:1.0.0
field: spec.source
requested_ref: hello-world-0.1.0

두 값은 모두 제 역할이 있습니다. 커밋은 빌드가 가져오는 대상이므로 빌드를 재현할 수 있습니다. 참조는 빌드가 항목을 조회하는 기준이며, 덕분에 Recipe에 계속 ref: hello-world-0.1.0이라고 쓰면서도 lockfile이 작성될 때 그 태그가 가리키던 정확한 커밋으로 해석할 수 있습니다.

예제 생성하기

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

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

Terminal window
aggrega scaffold --example chart-from-git-repository

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

Terminal window
cd chart-from-git-repository

빌드

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

이 예제에는 release가 두 개 있으므로 빌드할 release를 지정합니다. 첫 빌드에는 lockfile이 필요하므로 여기서는 --auto-pull을 전달합니다. 미리 aggrega pull --release release-chart.yaml을 한 번 실행해도 같은 효과가 있으며, 이후의 모든 빌드는 플래그 없이 실행할 수 있습니다.

렌더링된 Deployment에는 Release가 제공한 값이 차트 자체의 값 이름에 매핑되어 들어 있습니다.

dist/app/helm/web-deployment-web-hello-world.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-hello-world
[… omitted: the chart's own labels, and the labels and annotations every rendered document carries]
spec:
replicas: 2
[… omitted: the selector and the pod template's own labels]
spec:
serviceAccountName: web-hello-world
securityContext: {}
containers:
- name: hello-world
securityContext: {}
image: "nginx:1.27.3"
imagePullPolicy: IfNotPresent
[… omitted: the container port and the two probes]

빌드할 때마다 경고가 하나 출력됩니다.

warning: node "web": .infra key "compute" is read by no template in recipe "hello-world-git" — correct the spelling, or remove the key

이 경고는 정확하며, 숨기기보다 읽어 볼 가치가 있습니다. core/compute/server Component는 CPU 및 메모리 크기 조정 항목을 제공하지만, 이 차트는 이에 해당하는 값을 노출하지 않으므로 Recipe는 여기에 아무것도 매핑하지 않습니다. 소스를 가져오는 Recipe는 그 차트가 실제로 받아들이는 값을 매핑하며, 컴파일러는 어디에도 도달하지 못한 값을 적용된 것처럼 꾸미는 대신 보고합니다.

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `chart-from-git-repository` 폴더가 없으면 `example`에 `chart-from-git-repository`를 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `chart-from-git-repository` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `chart-from-git-repository`, `release`에 `release-chart.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `chart-from-git-repository/dist/` 아래에 있습니다.

참조가 이동할 때

태그는 저장소에서 다른 커밋을 가리키도록 변경될 수 있습니다. 그러면 다음 일반 aggrega pull은 참조가 기록된 커밋과 다른 곳으로 해석되는 것을 발견하고, 이를 채택하는 대신 중단합니다.

# aggrega pull --release release-chart.yaml
#
# [E0130]
# lockfile: out of date; it no longer matches what its Release resolves to
# ---
# source-artifact kind=git-repository url=https://github.com/helm/examples.git
# module_subdir=charts/hello-world: reference "hello-world-0.1.0" moved — the
# lockfile pins 03f4a18d3c2b77b7ecd91d0324a95910d4f04152, and it now resolves to
# f3dc419e558e6ccebce2ed447384e5d2e11de2f9; adopt where it now points with
# `aggrega pull --upgrade --release <release>`

두 커밋을 모두 표시하므로 결정하기 전에 정확히 무엇이 바뀌었는지 확인할 수 있습니다. lockfile은 그대로 유지되며(무엇이든 기록되기 전에 중단됩니다), 새 커밋을 채택하는 것은 의도적인 작업입니다.

Terminal window
aggrega pull --upgrade --pin-sources --release release-chart.yaml

이동한 참조가 바로 --upgrade가 필요한 경우입니다. 일반 pull은 lockfile에 기록된 커밋을 유지하며, upgrade만이 참조가 현재 가리키는 곳을 채택합니다. 단독 --upgrade는 기록된 모든 핀을 삭제하므로 먼저 확인을 요청합니다. --pin-sources도 필요합니다. 이 Recipe는 옆의 entity.lock에도 소스의 커밋을 기록하기 때문입니다. upgrade는 그 핀을 새 커밋으로 다시 쓰며, 이 플래그가 없으면 pull은 lock에서 중단되고 aggrega pin을 안내합니다. 다시 쓰인 entity.lock을 Recipe와 함께 커밋하십시오.

이 워크스페이스에서 이루어진 편집, 예를 들어 Aggregate나 Release의 편집은 다른 종류의 드리프트입니다. 다음 빌드가 이를 보고하며, 일반 aggrega pull --release release-chart.yaml로 해소됩니다.

ref:에 태그 대신 커밋을 고정하는 것도 같은 보장을 얻는 또 다른 방법이지만, 사람이 읽을 수 없는 좌표라는 대가가 따릅니다.

가드레일 release

release-negative.yaml은 실패하도록 의도된 것이며, 정상 경로에서만 실행된 가져오기 경로로는 그 보호 장치에 대해 아무것도 알 수 없기 때문에 포함되어 있습니다. 이 release는 같은 Aggregate를 manifest-negative.yaml을 통해 배포하며, 이 매니페스트는 참조만 제외하고 정상 동작하는 것과 동일한 Recipe를 바인딩합니다. 그 참조는 저장소에 없는 태그를 가리킵니다.

Terminal window
aggrega build --release release-negative.yaml --auto-pull
# exits non-zero
# [E0137]
# auto-pull: resolving the source of each Recipe and FeatureRecipe the Release
# uses: resolve: resolve source for recipe
# "helm/hello-world-git-missing-ref:1.0.0": sourceresolver: kind=git-repository
# url=https://github.com/helm/examples.git version=: oci: artifact not found at
# remote source (cause: reference not found)
[… omitted: the rest of that line, a remediation naming the URL and version to check]

저장소에 접근할 수 있고 클론도 성공합니다. 단지 그 안에 해당 참조가 없으므로 고정할 커밋도, 보관할 것도 없습니다.

이 예제가 네트워크에 요구하는 것

여기 있는 대부분의 워크스페이스와 달리, 이 워크스페이스는 첫 빌드에서 실제 저장소를 클론하므로, 그 빌드에는 url에 지정된 호스트로의 외부 접근이 필요합니다. lockfile과 해석 캐시가 생기면 이후 빌드는 캐시에서 읽으며 네트워크 없이 실행됩니다. aggrega build --release release-chart.yaml --offline은 동일한 바이트를 다시 빌드합니다.