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

자격 증명 공유 — 소비자별, 공유, 그리고 둘 다 동시에

하나의 OpenAI 호환 게이트웨이 뒤에 있는 두 개의 CrewAI 에이전트입니다. 각 에이전트의 model 소켓은 credential 슬롯을 선언하므로, 에이전트가 도달하는 모델에 제시하는 키는 해당 연결에 부착됩니다. 이 워크스페이스는 카탈로그 엔티티를 하나도 바꾸지 않고 슬롯을 세 가지 방식으로 채웁니다. 연결마다 키를 하나씩 두는 방식, 모든 연결이 가리키는 하나의 Secret, 그리고 한 연결이 재정의하는 공유 기본값입니다.

핵심은 소비자가 둘이라는 점입니다. 소비자가 하나뿐이면 세 형태는 구별되지 않습니다. 차이는 각 소비자가 결국 어떤 Secret을 가리키느냐이며, 이 질문은 소비자가 둘 이상이 되기 전까지는 의미가 없습니다.

예제 생성하기

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

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

Terminal window
aggrega scaffold --example model-api-key-sharing

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

Terminal window
cd model-api-key-sharing

빌드

형태마다 하나씩, 세 개의 release가 있습니다. 실행마다 하나씩 빌드합니다:

Terminal window
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/
aggrega build --release release-shared.yaml --auto-pull # → dist/shared/
aggrega build --release release-composed.yaml --auto-pull # → dist/composed/

각 release는 자체 디렉터리에 기록하므로, 렌더링된 세 트리가 공존하며 서로 diff할 수 있습니다.

release는 빌드하기 전에 lockfile이 필요합니다. 새로 체크아웃한 경우 먼저 하나를 해석하십시오. 별도 단계로 하거나 빌드가 채우도록 할 수 있습니다:

Terminal window
aggrega pull --release release-shared.yaml # resolve, then build normally
aggrega build --release release-shared.yaml --auto-pull # or resolve during the build

release는 구성된 카탈로그에서 카탈로그 엔티티를 해석하므로 --catalog 플래그가 필요하지 않습니다.

세 가지 모두 의도적으로 helm 타깃에서 빌드합니다. 세 형태를 구분하는 관찰 대상은 각 에이전트의 컨테이너가 참조하는 Secret의 이름이며, helm에서는 자격 증명이 컨테이너가 이름으로 참조하는 이름 있는 Kubernetes Secret입니다. 두 Manifests가 자격 증명을 바인딩합니다. 소비자별 release에서는 manifest.yaml이 k8s-secret-from-parameter에 바인딩하며, 이는 부착물이 담은 값으로 Secret을 렌더링합니다. 공유 및 조합 release에서는 manifest-existing-secret.yaml이 k8s-existing-secret에 바인딩하며, 이는 아무것도 렌더링하지 않고 각 소비자가 네임스페이스에 이미 있는 Secret을 가리키게 합니다.

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `model-api-key-sharing` 폴더가 없으면 `example`에 `model-api-key-sharing` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `model-api-key-sharing` 폴더에 작성됩니다. 그런 다음 각 Release마다 `release-per-consumer.yaml`, `release-shared.yaml`, `release-composed.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `workspace_root` 값은 `model-api-key-sharing`, `release` 값은 해당 파일, `auto_pull` 값은 true, `write` 값은 true로 설정하십시오. 각 빌드가 작성한 파일을 알려 주십시오. 파일은 `model-api-key-sharing/dist/` 아래에 있습니다.

소비자별 — 각 연결이 자체 키를 보유

aggregate-per-consumer.yaml은 각 에이전트의 연결에서 슬롯을 채우며, 에이전트마다 다른 origin을 사용합니다:

researcher:
type: core/ai-agent/crewai
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-key-change-me

연결의 부착물은 연결과 슬롯의 이름을 딴 에이전트 자체 부착물 중 하나가 됩니다. 여기서는 gateway.credential입니다. 따라서 에이전트마다 하나씩 두 개의 Secret이 생성되며, 각각 해당 에이전트 자체의 자료를 담습니다:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: researcher-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: writer-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "writer-key-change-me"

그리고 각 Deployment는 자신의 것을 참조합니다:

dist/per-consumer/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-gateway.credential
key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: writer-gateway.credential
key: OPENAI_API_KEY

한 에이전트의 키를 폐기해도 다른 에이전트는 계속 실행됩니다.

공유 — 하나의 Secret을 각 연결에서 참조

연결의 자격 증명은 그 연결에 작성됩니다. 다른 곳에 부착된 것은 그것을 채우지 않습니다. 따라서 여러 소비자는 작성을 통해 하나의 자격 증명을 공유합니다. 각 연결의 자격 증명이 같은 값을 읽고, 그 값이 하나의 Secret을 지정합니다.

aggregate-shared.yaml은 매개변수 하나를 선언하고 두 연결 모두에서 그것을 읽습니다:

parameters:
team_model_key:
type: string
default: team-model-key
components:
researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}"
writer: { ... } # the same credential, reading the same parameter

release는 자격 증명을 k8s-existing-secret에 바인딩하며, 이는 origin을 네임스페이스에 이미 존재하는 Secret의 이름으로 읽습니다. Secret은 전혀 렌더링하지 않으며 게이트웨이의 Service와 두 Deployment만 기록됩니다. 두 Deployment 모두 매개변수가 지정하는 하나의 Secret을 참조합니다:

dist/shared/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

이는 정확히 하나의 물리적 Secret으로, Release 외부에서 배포하는 사람이 생성하고 모든 소비자가 읽습니다. 키의 자료는 작성된 파일이나 렌더링된 아티팩트를 전혀 거치지 않습니다.

매개변수가 담는 것은 Manifest가 바인딩하는 실현을 따릅니다. k8s-existing-secret에서는 Secret의 이름입니다. 대신 k8s-secret-from-parameter에 바인딩하면, 하나의 매개변수를 읽는 같은 두 연결은 키 자체를 담게 되고, 빌드는 소비자마다 같은 자료를 담은 Secret을 하나씩 렌더링합니다. 렌더링은 컴포넌트별로 실행되며, 그 실현은 렌더링하는 Secret의 이름을 소비하는 컴포넌트와 연결에 따라 짓기 때문입니다. 하나의 매개변수는 소비자들이 서로 어긋나지 않게 하고, 어떤 실현이 그것을 읽는지가 소비자들이 리소스를 공유하는지를 결정합니다. 클러스터에서 생성되는 자격 증명도 같은 방식으로 공유됩니다. 요청 하나와 여러 참조입니다. 자격 증명 모델을 참조하십시오.

조합 — 공유 기본값, 한 연결이 재정의

aggregate-composed.yaml은 공유 매개변수를 기본값으로 유지하고 한 연결이 자체 Secret을 지정하게 합니다:

researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-model-key # this connection's own Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

재정의는 그 한 연결이 작성하는 것입니다. 아무것도 그 위로 전파되지 않으며, writer는 공유 Secret을 그대로 유지합니다:

dist/composed/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-model-key
key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

연결의 자격 증명은 그 자체로 완전한 부착물이므로, 재정의는 필요한 모든 필드를 다시 명시하며(여기서는 Feature 유형, key, origin) 기본값에서 아무것도 상속하지 않습니다.

슬롯이 제공하는 것

core/ai-agent/crewai는 model 소켓에 슬롯을 한 번 선언하며, 세 형태는 모두 Aggregate에서 내리는 선택입니다:

usesSchema:
model:
selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api"
required: true
inject: [env, file]
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

슬롯은 선택 사항이므로, 네 번째 형태는 아무것도 부착하지 않는 것입니다. 두 연결에서 features: 블록을 제거하면 렌더링된 트리에서 모든 OPENAI_API_KEY env 항목이 사라지고, 두 Deployment와 게이트웨이 Service만 남습니다. 빈자리를 채우기 위해 만들어지는 것은 없습니다. 카탈로그 엔티티는 모든 경우에 동일하며, 결정은 작성자가 합니다.

이것이 빌드되는 이유는 여기의 게이트웨이 core/ai-model/openai-compatible에 component.aggrega.ai/hosting 레이블이 없기 때문입니다. 카탈로그가 managed로 레이블을 지정한 타깃(예: core/ai-model/openai)에 자격 증명 없이 도달하는 연결은, 연결이 values에서 타깃이 자격 증명을 받지 않는다고(unauthenticated: true) 명시하지 않는 한 에이전트 자체의 단언에 의해 빌드를 중단시킵니다.

슬롯은 또한 패밀리에 구애받지 않으며(feature.aggrega.ai/kind=secret은 어느 자격 증명 패밀리든 허용합니다), 이 덕분에 같은 에이전트가 helm에서는 참조 가능한 Secret을, compose에서는 inject-value 자격 증명을 받을 수 있습니다. 자격 증명 전달 — secretKeyRef 엔드투엔드는 이 provider 분기를 다루며, 그 부정 release는 참조할 수 없는 자격 증명에 참조를 충족하도록 요구할 때 어떤 일이 일어나는지 보여 줍니다.

결정성

세 release 모두 --verify-determinism으로 빌드되며, 이는 모든 노드를 두 번 렌더링하고 생성된 바이트를 비교합니다:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

세 가지 중 어느 것이든 깨끗한 트리에서 다시 빌드하면 렌더링된 출력이 바이트 단위로 동일하게 재현됩니다.