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

자격 증명 Features

이 페이지는 한 가지 개념, 즉 표준 라이브러리의 자격 증명 Features와 Manifest가 각각을 무엇으로 구현할지 선택하는 방식을 설명하며, 실행 가능한 작업 공간이 아닙니다. 하나의 개발자 의도, 두 가지 자격 증명 전달 형태는 같은 자격 증명의 두 가지 구현을 대상으로 하나의 Aggregate를 빌드합니다. 다음과 같이 자신의 폴더에 작성할 수 있습니다:

Terminal window
aggrega scaffold --example credential-shape-per-target

그런 다음 이어서 실행할 명령을 출력합니다:

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

자격 증명은 Component가 자신의 featuresSchema에서 선언하는 슬롯을 채웁니다(entities/component.md 참조). 슬롯, 그 슬롯을 채우는 Feature, Manifest가 바인딩하는 FeatureRecipe가 작성자의 연결에서 실행 중인 워크로드까지의 전체 경로를 이룹니다.

자격 증명 Feature 계열

자격 증명 Feature에는 feature.aggrega.ai/kind: secret 레이블이 붙습니다. 이 레이블은 연결이 무엇을 생성하는지 설명하는 카탈로그 메타데이터이며, 이를 읽는 컴파일러 분기는 없고, 자격 증명 Feature는 다른 Feature와 마찬가지로 features: 아래에 연결됩니다. 개발자는 Aggregate에서, 운영자는 Release에서 연결합니다.

표준 라이브러리는 자격 증명 Features를 구현이 시크릿으로 무엇을 하는지에 따라 나눕니다.

  • **core/secret-value**는 값을 컴포넌트의 주입 파이프로 전달하며, 그 컴포넌트의 Recipe가 거기서 값을 읽습니다. 차트 값이나 환경 변수가 그 예입니다.
  • **core/secret-provided**도 값을 내놓지만, 대신 이를 provides 키로 게시하므로, 투명 슬롯에서 연결 자체의 inject: 블록이 값이 어디로 갈지 지정합니다.
  • **core/referenced-secret**는 시크릿 리소스(Kubernetes Secret, AWS Secrets Manager 시크릿, Vault 항목)를 지정합니다. 이 리소스는 해당 구현이 생성하거나 이미 존재하는 것이며, 그 리소스의 name과 key를 게시하고, 소비자는 이를 .features.<slot>.provides.name 및 .features.<slot>.provides.key로 읽습니다.
  • **core/referenced-secret-set**는 작성자가 제공한 데이터 키 집합을 담은 그러한 리소스 하나를 구체화하고, 그 위치 지정자만 게시합니다. 이는 대상이 읽을 키 이름을 이미 정해 둔 소비자를 위한 것입니다. Docker Compose에는 그러한 리소스가 없으므로, 그곳에서는 구현이 아래에 설명된 대로 키를 대신 값으로 전달합니다. MariaDB(Bitnami 차트) — 여러 키를 가진 하나의 자격 증명 Secret에서 이를 사용합니다.
  • **core/generated-secret**는 아무것도 생성하지 않습니다. 관리형 데이터베이스가 관리자 비밀번호를 다루듯이 대상 엔진이 자격 증명을 직접 생성하고 관리합니다. 운영자는 Release에서 이를 연결합니다. 엔진이 자격 증명을 소유하는지는 Manifest가 선택하는 Recipe에 따라 결정되기 때문입니다. Terraform RDS(인라인 HCL 아티팩트)는 이 방식으로 필수 슬롯을 바인딩합니다.
  • **core/random-password**는 대상이 비밀번호를 생성하여 시크릿 리소스에 넣도록 하는 요청을 렌더링하고, core/referenced-secret와 마찬가지로 그 리소스의 위치 지정자를 게시합니다. 누구도 자격 증명을 작성하지 않으며 렌더링된 출력에도 자격 증명이 포함되지 않습니다.

이들은 동등합니다. 같은 레이블, 같은 연결 표면, 같은 슬롯을 가지므로 슬롯은 항상 채워져 있고, Releases 사이에서 바뀌는 것은 그 슬롯을 무엇이 채우는가입니다. provides 계약을 선언하는 자격 증명 Feature는 이를 구현하는 모든 FeatureRecipe가 해당 키를 게시하도록 강제하며, 하나라도 그렇게 하지 않으면 빌드가 중단됩니다. 이것이 소비자의 읽기를 안전하게 만듭니다.

빌드는 값을 생성하지 않으므로 core/random-password에는 대상 측에서 값을 생성할 무언가가 필요합니다. Kubernetes에서는 Release가 infra.control_plane_present: true로 존재를 확인하는 컨트롤러(External Secrets Operator 또는 kubernetes-secret-generator), Terraform에서는 random_password 리소스, CloudFormation에서는 자체 문자열을 생성하는 Secrets Manager 시크릿입니다. Docker Compose용 구현은 제공되지 않으므로, 거기서 이를 바인딩하는 빌드는 중단됩니다. 요청마다 자체 값을 생성하므로, 두 컴포넌트가 생성된 비밀번호 하나를 공유하려면 name을 고정하여 한 번만 연결하고, 다른 곳에서는 helm/k8s-existing-secret에 바인딩된 core/referenced-secret을 통해 읽습니다.

자격 증명을 지정하는 주체: values 또는 infra 중 정확히 하나

core/secret-value, core/secret-provided, core/referenced-secret, core/referenced-secret-set는 어느 작성자로부터든 자격 증명의 로케이터를 받습니다. 개발자는 Aggregate에서 연결의 values에, 운영자는 Release에서 연결의 infra에 작성합니다. 리프는 양쪽에서 동일하며(origin, 세트의 경우 entries), 모든 구현은 로케이터를 담은 쪽의 필러를 읽습니다.

운영자의 형식은 개발자가 자격 증명을 작성할 수 없는 곳에서 자격 증명을 사용할 수 있게 합니다. 즉 Release가 배선하는 커넥션과, Release만이 만드는 연결입니다. Release는 어디에도 values를 작성하지 않기 때문입니다.

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

둘 중 정확히 하나. 각 필러는 독립적으로 검증되므로 어느 스키마도 로케이터를 필수로 요구할 수 없습니다. 대신 각 Feature 자체의 assertions가 이 규칙을 담으며, 로케이터를 두 필러 모두에 담거나 어느 쪽에도 담지 않은 연결은 Feature, 연결, 컴포넌트를 지목하며 빌드를 중단시킵니다(E0033). 이것은 카탈로그 엔터티의 계약입니다. 컴파일러는 다른 Feature의 assertion을 평가하듯 이 assertion을 평가합니다.

나머지는 모두 자기 필러에 그대로 남습니다. key는 values 리프로 남으므로, Release만이 만드는 연결은 기본 데이터 키인 value를 읽습니다. origin을 두 필러 모두에 선언하는 것은 정확히 필러 중복 권고가 찾는 대상이므로, 이 Features를 로드하면 LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars가 보고됩니다. 여기서는 중복이 계약이며, 이 권고는 판정도, 렌더링된 바이트도 바꾸지 않습니다.

Manifest가 선택하는 구현

같은 대상에 대해 여러 FeatureRecipes가 하나의 Feature를 구현할 수 있으며, Manifest가 선택합니다. core/referenced-secret에는 Kubernetes용이 세 개 있으며, 그중 무엇을 고를지는 자격 증명이 어디에 있는지에 따라 결정됩니다:

  • **helm/k8s-secret-from-parameter**는 작성자가 제공한 값을 자신이 출력하는 Secret에 기록하므로, 비밀 자료가 렌더링된 출력에 들어갑니다. 평가 및 로컬 작업용입니다.
  • **helm/k8s-external-secret**는 시크릿 저장소의 항목을 지정하는 ExternalSecret를 렌더링하며, 클러스터의 External Secrets Operator가 이를 Secret으로 조정(reconcile)합니다.
  • **helm/k8s-existing-secret**는 아무것도 출력하지 않습니다. origin을 이미 존재하는 Secret의 이름으로 읽고, 작성된 그대로 게시합니다.

앞의 두 가지는 호스트의 렌더링된 이름과 슬롯의 이름으로부터 같은 방식으로 Secret의 이름을 도출하므로, 소비자는 어느 쪽에서든 같은 로케이터를 읽고 렌더링된 참조도 바뀌지 않습니다. 예제가 보여 주는 것이 바로 이 점입니다. 세 번째는 기존 Secret 자체의 이름을 게시하므로, 이를 바인딩하면 소비자의 참조가 의도적으로 바뀝니다.

core/secret-value는 Docker Compose에서 compose/dotenv-secret로 구현되며, 이는 값을 작성된 그대로 서비스의 환경에 기록합니다. ${DB_PASSWORD}처럼 작성된 origin은 그 참조 그대로 들어가며, Docker Compose가 스택 시작 시 셸이나 .env 파일에서 이를 채웁니다. Kubernetes에서는 helm/env-secret가 값을 주입 파이프로 전달하고, helm/k8s-secret-from-value는 값을 Secret에도 기록하고 그 위치 지정자를 게시하여, 자격 증명을 참조로 읽는 소비자가 쓸 수 있게 합니다. 어느 Kubernetes 구현도 Compose 변수 참조를 받지 않습니다. 그곳에서는 그것을 채울 것이 없기 때문입니다.

core/referenced-secret은 Docker Compose에서 compose/dotenv-referenced-secret으로 구현됩니다. Compose에는 참조할 시크릿 리소스가 없으므로 origin은 Secret의 이름이 아니라 자격 증명 그 자체입니다. 이 값은 첨부의 key 아래에서 inject 파이프로 전달되고, 슬롯을 읽는 Compose Recipe가 이를 작성된 그대로 출력 파일에 기록하므로, ${DB_PASSWORD}로 작성된 origin은 그 참조 그대로 들어갑니다. 리소스를 만들지 않으므로 게시하는 이름은 비어 있고 게시하는 키는 values.key입니다.

core/referenced-secret-set은 Docker Compose에서 compose/dotenv-secret-set으로 구현됩니다. 이는 각 항목을 그 키 이름을 가진 변수로 inject 파이프에 전달하고 작성된 그대로 서비스 환경에 기록하므로, 값이 ${GITHUB_TOKEN}인 항목은 그 참조 그대로 들어갑니다. 리소스를 만들지 않으므로 게시하는 위치 지정자는 비어 있습니다. Compose의 소비자는 Secret을 이름으로 참조하는 대신 자신의 inject 파이프에서 항목을 읽으며, 1.1.0부터 compose/mcp와 compose/mcp-stdio-bridge가 Model Context Protocol 서버의 server_env에 대해 이렇게 합니다.

provided-secret처럼 둘 이상의 대상용으로 제공되는 FeatureRecipe 이름은 Manifest에서 대상과 함께 compose/provided-secret:1.0.0처럼 지정합니다. 접두사 없는 이름은 둘 다와 일치하기 때문입니다.

한 번만 게시되는 하나의 이름

소비자의 Recipe는 자격 증명이 생성하는 Secret의 이름을 결코 직접 도출하지 않습니다. 자격 증명이 게시하는 위치 지정자를 읽습니다: existingSecret: "{{ .features.root_password.provides.name }}". 이름은 FeatureRecipe의 provides에서 한 번만 작성되므로, 이름의 구성 방식을 바꾸려면 그곳만 수정하면 됩니다. 자격 증명 전달 — secretKeyRef 엔드투엔드는 Kubernetes에서 참조 가능한 경로를, Docker Compose에서 주입되는 경로를 빌드하며, 자격 증명 공유 — 소비자별, 공유, 그리고 둘 다 동시에는 여러 소비자가 각자의 키를 갖거나 하나를 공유하는 모습을 보여 줍니다.