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

aggrega pin

aggrega pin <entity-path>은 Recipe 또는 FeatureRecipe 옆의 entity.lock에, 엔터티가 자신의 문서 밖에서 읽는 모든 입력에 대한 콘텐츠 고정값을 기록합니다. 이는 엔터티 작성자가 수행하는 단계입니다. 엔터티가 사용되거나 게시되기 전에 실행하고, 이 명령이 작성한 lock을 커밋합니다.

aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml

기록하는 내용

엔터티는 자체 문서 외부의 바이트에 의존할 수 있으며, 락은 그 각각에 대해 하나의 고정값을 보관합니다.

  • 좌표를 완전히 작성한 원격 source: — kind, url, chart, module_subdir, version, ref 어디에도 템플릿이 없는 경우입니다. 이 단계는 소스를 가져와서 해석된 버전(git 소스의 경우 ref가 가리킨 커밋)과 가져온 내용의 콘텐츠 다이제스트를 기록합니다.
  • artifacts 항목이 $import로 가져오는 파일. 이 단계는 워크스페이스에 있는 그대로의 파일에 대한 다이제스트를 계산합니다.
  • 엔터티 옆의 디렉터리나 파일을 가리키는 source:의 각 파일. 아무것도 가져오지 않습니다. 이 단계는 소스가 엔터티의 게시물에 포함시키는 각 파일, 즉 소스가 가리키는 디렉터리 아래에서 엔터티의 무시 규칙이 유지하는 모든 파일 또는 그 하나의 파일에 대한 다이제스트를 계산하고, 엔터티 기준의 경로로 기록합니다. Recipe 옆에 있지만 소스가 포함시키지 않는 파일(예: README)은 고정되지 않습니다. ./charts/{{ .values.flavour }}처럼 템플릿으로 작성된 소스는 Release가 값을 채워야만 디렉터리가 정해지므로, 엔터티 디렉터리에서 규칙이 유지하는 모든 파일을 포함시키며 그 각각이 고정됩니다. 빌드는 provider가 소스를 읽기 전에 소스를 이 고정값과 비교하므로, 고정 이후 파일이 추가, 변경 또는 삭제되면 빌드가 중단됩니다 — A local source no longer matches the pins recorded beside its Recipe (로컬 소스가 Recipe 옆에 기록된 고정값과 더 이상 일치하지 않음).
  • 디렉터리인 source:의 경우, 무시 규칙 자체. 이 단계는 엔터티의 capability를 제공한 플러그인과 그 플러그인이 구성한 정확한 규칙을 기록하며, 이는 다음 섹션에서 설명합니다.

기록하지 않는 내용: 좌표가 템플릿으로 채워지는 원격 소스(Release가 값을 채워야만 아티팩트가 정해지며, aggrega pull이 각 Release의 lockfile에 고정합니다), 그리고 인라인 artifacts 항목이나 ArtifactLibrary에서 가져온 항목입니다. 파일 자체는 엔터티 락 스키마에서 필드별로 설명합니다.

Release가 필요하지 않습니다. 완전히 작성된 소스는 엔터티를 사용하게 될 모든 Release에 대해 동일한 아티팩트를 가리키므로, 이를 해석하는 데 Release가 제공하는 것은 필요하지 않습니다. 이 덕분에 작성자는 Release가 전혀 없는 워크스페이스에서도 엔터티를 고정할 수 있습니다.

엔터티 파일은 절대 쓰이지 않습니다. 이 단계가 도출한 내용은 엔터티 옆에 저장되며, 직접 입력한 내용은 입력한 그대로 유지됩니다. 입력이 변경되지 않은 상태에서 다시 실행하면 락은 바이트 단위로 동일하게 유지되며, 락이 기록하는 대상을 더 이상 읽지 않는 엔터티는 락이 제거됩니다. Component, Feature 또는 그러한 입력을 읽지 않는 다른 종류는 고정할 것이 없다고 보고되며, 그 옆의 어떤 것도 변경되지 않습니다.

엔터티와 함께 배포되는 파일

source:가 자신 옆의 디렉터리(같은 위치에 둔 차트나 모듈)를 지정하는 Recipe 또는 FeatureRecipe는 게시될 때 그 디렉터리의 파일을 함께 가져갑니다. 그 안의 모든 파일이 여기에 속하는 것은 아닙니다. 버전 관리 디렉터리, 의존성 캐시, 편집기가 남긴 파일 등이 그렇습니다. 어떤 파일이 속하는지는 .gitignore와 같은 구문의 ignore 규칙으로 결정되며, 이 규칙은 사용자가 제어합니다. 규칙은 두 곳에서 옵니다.

  • 엔터티의 capability를 렌더링하는 플러그인은 자신의 생태계에서 절대 배포하지 않는 것을 선언합니다. 차트 플러그인은 버전 관리 디렉터리(.git/, .hg/, .svn/, .bzr/)와 차트의 templates/ 아래 숨김 파일을 제외하며, 차트 자체의 .helmignore를 따릅니다. 소스를 순회하다가 이 파일을 만나면 그 줄들을 해당 파일이 있는 디렉터리에 대한 추가 규칙으로 읽습니다. Terraform 플러그인은 버전 관리 디렉터리와 .terraform/ 작업 디렉터리를 제외하고(모듈과 함께 이동하도록 의도된 의존성 잠금 파일은 제외하지 않습니다), .terraformignore를 같은 방식으로 따릅니다. 아무것도 선언하지 않는 플러그인은 모든 파일을 포함합니다.
  • 사용자 자신의 .aggregaignore: 엔터티 문서 옆에 두는 파일 하나로, 같은 구문을 사용합니다. 이 파일의 줄은 플러그인의 규칙과 플러그인이 지정하는 모든 ignore 파일 다음에 적용되므로, 지정한 경로에 대해서는 사용자가 최종 결정권을 가집니다. .venv/ 같은 줄은 플러그인이 알지 못하는 디렉터리를 제외하고, !.git/ 같은 줄은 플러그인이 제외한 디렉터리를 다시 포함합니다. 파일 자체는 함께 이동하지 않으며, 그 규칙이 lock 안에 담겨 이동합니다.
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

각 규칙은 그 규칙이 속한 디렉터리를 기준으로 읽힙니다. 플러그인이 선언한 규칙은 소스 디렉터리의 루트를 기준으로, .helmignore의 줄은 그 파일이 있는 디렉터리를 기준으로, .aggregaignore의 줄은 엔터티 자신의 디렉터리를 기준으로 읽힙니다. 슬래시가 없거나 끝에만 슬래시가 있는 규칙은 어느 깊이에서든 이름과 일치하고, 끝의 슬래시는 디렉터리에만 일치하며, 앞의 !는 앞선 규칙이 제외한 것을 다시 포함합니다. 규칙이 제외한 디렉터리에는 들어가지 않으므로, 그 안의 파일은 디렉터리 자체가 다시 포함되어야만 돌아옵니다. .git/가 제외된 동안에는 !.git/HEAD만으로는 파일이 돌아오지 않고, !.git/를 쓰면 돌아옵니다.

규칙을 읽는 플러그인은 pin하는 시점에 워크스페이스에서 해당 capability를 제공하는 플러그인입니다. 즉 그 capability에 대한 워크스페이스의 provider 바인딩, 또는 그것이 없으면 aggrega에 내장된 플러그인입니다. 이 단계는 그 플러그인을 provider/terraform처럼 버전 없이 이름으로만 기록하고, 플러그인이 구성한 정확한 규칙과 함께 entity.lock에 기록합니다. 같은 규칙을 선언하는 플러그인을 가진 더 새로운 aggrega로 다시 pin해도 lock은 변경되지 않습니다. 그 이후로 디렉터리를 읽을 때는 항상 기록된 규칙만 적용합니다. 엔터티의 게시, pull 또는 push가 lock과 대조하는 비교, lockfile의 엔터티 행, 빌드의 비교, 디렉터리를 provider에 넘기는 렌더링, aggrega pull --verify가 모두 그렇습니다. 따라서 게시하는 내용은 자신의 빌드가 렌더링하는 내용과 정확히 같으며, 바인딩이 바뀌거나 .aggregaignore를 수정하거나 aggrega가 새 버전이 되어도 다시 pin하기 전까지는 아무것도 바뀌지 않습니다. 다시 pin하면 lock의 diff에 무엇이 바뀌었는지 나타납니다. .helmignore처럼 플러그인이 ignore 파일로 지정하는 파일은 그 자체로 소스의 파일 중 하나이므로, 규칙이 제외하지 않는 한 다른 파일과 마찬가지로 pin됩니다. 따라서 다시 pin하지 않고 이 파일을 수정하면 다음 pull이나 빌드에서 감지됩니다. 규칙을 기록하지 않은 lock은 디렉터리 아래의 모든 파일을 유지합니다.

소비자는 사용자의 규칙이 유지한 파일을 렌더링합니다. 플러그인은 같은 ABI 버전을 사용하고, 그 계약이 엔터티의 주장과 일치하며, 게시된 파일 집합 밖의 파일이 필요하지 않을 때 자신의 capability용으로 게시된 Recipe를 렌더링할 수 있습니다. 집합이 제외한 파일이 필요한 플러그인은 빌드를 명시적으로 실패시키고 그 파일을 지정해야 합니다. 호스트는 집합에 없는 파일의 pack이나 읽기를 거부하고 그 파일을 지정합니다. 소비자의 워크스페이스가 capability에 바인딩한 플러그인이 lock에 기록된 규칙과 다른 규칙을 선언하면, 소비자의 aggrega pull은 두 플러그인과 그 차이를 지정하는 경고를 표시하고 계속 진행합니다.

엔터티의 파일 중 심볼릭 링크는 거부됩니다. 링크가 어디를 가리키든, 해석되든 되지 않든 마찬가지입니다. A symbolic link sits among the files an entity carries (엔터티가 가져가는 파일 중에 심볼릭 링크가 있음)을 참조하십시오. 규칙이 제외하는 링크는 규칙이 제외하는 다른 파일과 마찬가지로 건너뜁니다. 엔터티가 지정하는 경로가 엔터티 디렉터리 밖으로 이어지는 링크인 디렉터리를 거치는 경우에도, 무엇이든 pin되기 전에 거부됩니다. A path names content outside the entity’s own directory (경로가 엔터티 자신의 디렉터리 밖의 콘텐츠를 지정함)을 참조하십시오.

잠금 파일이 놓이는 위치

잠금 파일은 지정한 문서 옆, 같은 디렉터리에 기록되므로 엔터티에는 쓰기 가능한 위치, 즉 사용자 소유 디렉터리에 있는 문서가 필요합니다. pull이 콘텐츠 캐시에서 해석한 엔터티에는 그러한 위치가 없으며, 어떤 방법으로도 고정되지 않습니다.

디렉터리 하나에 엔터티 하나. 디렉터리 하나에는 entity.lock 하나가 들어가므로, 이 단계는 다른 엔터티와 디렉터리를 공유하는 Recipe 또는 FeatureRecipe를 거부합니다. 어느 쪽에 고정할 것이 있는지와 관계없이 거부하며, 걸림돌이 되는 각 엔터티의 이름을 밝힙니다. 이 거부는 An entity shares its directory with another entity (엔터티가 다른 엔터티와 디렉터리를 공유합니다)입니다. Aggregate, Release, Manifest는 나란히 놓일 수 있지만, 그 밖의 모든 종류는 각자의 디렉터리를 가집니다. push도 게시하는 엔터티에 같은 규칙을 적용하며, 이는 디렉터리당 엔터티 하나에서 설명합니다. 이 단계는 잠금 파일을 기록하는 대상만 판단하므로, Component나 고정할 것이 없는 다른 종류는 고정할 것이 없다고 보고되며, 거부는 해당 엔터티가 게시될 때 적용됩니다. 엔터티 옆에 있지만 엔터티 문서가 아닌 파일(차트 파일, 가져온 파일 자체 등)은 걸림돌이 되지 않습니다. 엔터티 옆의 각 문서는 워크스페이스 내부에서만 읽히며, 워크스페이스 밖에서 지정한 문서라면 잠금 파일도 함께 놓이는 그 문서 자체의 디렉터리 내부에서만 읽힙니다. 따라서 밖으로 이어지는 링크인 문서가 있으면, 워크스페이스 경계에서 설명하듯 이 단계는 그 링크를 읽지 않은 채 이름을 밝히며 중단됩니다.

누가, 언제 고정하는가

고정은 작성자의 의무입니다. 입력이 고정되지 않은 엔터티는 아직 사용될 준비가 되지 않은 것이므로, 기본적으로 pull은 고정을 기록하지 않습니다. 대신 Release가 빌드하는 Recipe 또는 FeatureRecipe가 사용자의 카탈로그 디렉터리 중 하나에 있으면, 이 단계가 기록할 내용과 lock에 담긴 내용을 비교하고, 고정이 누락되었거나 더 이상 입력과 일치하지 않으면 중단합니다. 이 중단은 엔터티, 각 입력과 그 입력이 원격 소스인지, 가져온 파일인지, 로컬 소스의 파일인지, 그리고 이 명령을 알려 줍니다. 이는 An entity reads an input the lock beside it records no pin for (엔터티가 옆의 lock에 고정이 기록되지 않은 입력을 읽습니다)입니다. push는 게시하는 엔터티에 동일한 비교를 적용하며 같은 중단으로 거부하므로, 고정이 기록되지 않은 엔터티는 aggrega push를 통해 레지스트리에 도달할 수 없습니다. 자세한 내용은 게시 전 고정에서 설명합니다. 로컬 소스는 하나의 파일 집합으로 취급됩니다. 그중 어느 파일도 기록하지 않은 lock은 pull이나 push를 중단시키며, 고정 이후 추가, 변경 또는 제거된 파일도 다른 누락되거나 오래된 고정과 마찬가지로 중단시킵니다.

첫 pull에서의 중단은 소비자가 아니라 게시자가 해결할 문제입니다. 다른 사람이 작성한 카탈로그를 사용하는 경우(예를 들어 자신의 디렉터리에 체크아웃한 경우) 그 안의 엔터티가 고정되어 있지 않다면, 작성자가 이 단계를 실행하지 않은 것입니다. 해결 방법은 그 디렉터리를 직접 편집하는 것이 아니라, 아래의 워크스페이스 키를 설정하여 pull이 직접 고정을 기록하도록 하는 것입니다.

두 명령이 사용자를 대신해 이 같은 단계를 실행하며, 동일한 바이트를 기록합니다.

  • aggrega pull --pin-sources는 중단하는 대신 Release가 빌드하는 엔터티에 대해 이 단계를 실행합니다.
  • aggrega push --pin-sources는 거부하는 대신 엔터티를 번들링하기 전에 이 단계를 실행하므로, 기록된 lock이 게시되는 내용의 일부가 됩니다.

각 명령에는 고정을 기본 동작으로 만드는 워크스페이스 키가 있습니다. pin_sources_at_pull과 pin_sources_at_push이며, 둘 다 기본적으로 꺼져 있고 각각 자신의 명령에만 적용됩니다. 플래그는 양방향으로 키를 재정의합니다. --pin-sources는 키 설정과 관계없이 한 번의 실행 동안 고정하고, --pin-sources=false는 고정하지 않습니다. 따라서 고정하도록 구성된 워크스페이스에서도 한 번의 pull에 대해 중단을 다시 받을 수 있습니다. 자체 lockfile을 채우는 빌드는 pull이므로 pin_sources_at_pull을 따릅니다. 키에 대한 설명은 구성 참조에 있습니다.

게시된 엔터티 변경

모범 사례: 이미 게시한 엔터티에 대한 수정은 새 버전에 담고 그다음에 고정해야 하며, 이미 배포된 버전을 다시 고정해서는 안 됩니다. 엔터티를 새 버전 디렉터리로 복사하고, 그곳에서 변경한 다음, 새 버전에 대해 aggrega pin을 실행합니다. 게시된 버전은 게시될 때의 바이트를 정확히 그대로 계속 기술하며, 새 버전으로 옮겨 가는 소비자는 의도적으로 옮겨 가게 됩니다.

제품은 이 중 절반을 강제합니다. 이미 게시된 버전으로 변경된 내용을 게시하는 것은 거부되므로, 게시된 버전이 조용히 대체될 수 없습니다. 나머지 절반은 사용자의 워크스페이스 안에서 강제하지 않습니다. 수정 후 기존 버전을 다시 고정하는 것이 정확히 옳은 경우도 있습니다. 예를 들어 하나의 애플리케이션 안에서 소비하며 게시하지 않은 엔터티가 그렇습니다. 따라서 이를 막는 것은 없으며, 이 원칙을 지키는 것은 사용자의 몫입니다.

다른 인터페이스에서의 같은 단계

데몬은 이 단계를 aggrega/pin(aggrega serve)으로, 도구 프로토콜은 pin 도구(aggrega mcp)로 제공합니다. 둘 다 이 명령이 쓰는 것과 같은 바이트를 씁니다. HTTP 리스너를 통해 호출하면 이 도구는 워크스페이스 안에 쓰고 엔터티의 소스가 지정하는 호스트에 접속하므로, 호출자가 이를 호출하려면 workspace-write 스코프가 필요합니다. 이는 pull에 필요한 것과 같은 권한입니다.

참고 항목

  • aggrega-pull.md — 엔터티 잠금, 빌드가 이와 비교하는 대상, 그리고 중단.
  • aggrega-push.md — 엔터티 게시와 버전을 한 번만 게시하는 방식.
  • configuration.md — pin_sources_at_pull 및 pin_sources_at_push.

개요

aggrega pin <entity-path> [flags]

설명

Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input
the entity reads from outside its own document: a remote source: whose coordinates you wrote out
in full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before you
publish it, and after every change to one of its inputs — and commit the entity.lock it writes
beside the entity. A pull over an entity whose lock does not record these pins halts and names
this command, and so does a push of it; so does one whose local source has had a file added,
changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for every
Release that uses the entity, so it is resolved and pinned here, with nothing supplied. A remote
source whose coordinates are filled in from a template is not pinned here: which artifact it names is
decided by each Release, and each identity it resolves to is pinned in that Release's lockfile.
A source that names a directory beside the entity is not fetched: each file it contributes to what
a publication of the entity carries is digested as it stands and pinned by its path, so a build
refuses a file added, changed or removed after the pin. A local source written as a template
contributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads the
ignore rules the plugin serving the entity's capability declares — this workspace's provider binding
for that capability, or else the plugin built into aggrega — together with the ignore files that
plugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside the
entity, in gitignore syntax, whose lines come last and so have the final say. It records the plugin
and the composed rules in the entity.lock, and every publication, pull, build and render of the
entity applies the recorded rules and no others, so a changed binding or a newer binary moves
nothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name is
read from its own directory and the lock lands next to it. The entity file itself is never
written to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that reads
nothing a lock records has its lock removed. A Component, a Feature or any other kind that reads
no such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares its
directory with any other entity, naming the entity in the way, whether or not either has anything
to pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sit
side by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, and
write the same bytes.

플래그

플래그기본값설명
--dry-runfalse엔터티의 입력을 해석하고, 이 단계가 쓸 entity.lock을 쓰는 대신 출력합니다. 해당 경로와 담길 내용이 stdout으로 출력되며 디스크에서는 아무것도 바뀌지 않습니다. 이 단계가 바이트 단위로 동일하게 남길 잠금은 출력되지 않습니다. 해석은 다른 경우와 정확히 동일하게 실행되므로 콘텐츠 캐시는 여전히 채워집니다