Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Współdzielenie poświadczenia — osobne dla każdego konsumenta, wspólne i oba naraz

Dwa agenty CrewAI za jedną bramą zgodną z OpenAI. Gniazdo model każdego agenta deklaruje slot credential, więc klucz, który agent przedstawia modelowi, do którego się łączy, jest dołączany do tego połączenia. Ten obszar roboczy wypełnia slot na trzy sposoby bez zmiany żadnej encji katalogu: klucz dla każdego połączenia, jeden Secret, na który wskazuje każde połączenie, oraz wspólna wartość domyślna, którą jedno połączenie nadpisuje.

Chodzi właśnie o dwóch konsumentów. Przy jednym konsumencie trzech form nie da się odróżnić — różnica polega na tym, na który Secret ostatecznie wskazuje każdy konsument, a to pytanie nie ma treści, dopóki nie ma więcej niż jednego konsumenta.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd model-api-key-sharing

Kompilacja

Trzy wydania, po jednym na formę. W jednym uruchomieniu buduje się jedno:

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/

Każde wydanie zapisuje do własnego katalogu, więc wszystkie trzy wyrenderowane drzewa współistnieją i można je porównywać ze sobą.

Wydanie przed zbudowaniem potrzebuje swojego pliku blokady. W świeżym checkoucie należy najpierw go rozwiązać — albo jako osobny krok, albo pozwalając, by wypełniło go budowanie:

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

Wydania rozwiązują swoje encje katalogu ze skonfigurowanego katalogu, więc flaga --catalog nie jest potrzebna.

Wszystkie trzy są celowo budowane na celu helm. Obserwowalną cechą odróżniającą trzy formy jest nazwa obiektu Secret, do którego odwołuje się kontener każdego agenta, a w helm poświadczenie jest nazwanym obiektem Secret Kubernetes, do którego kontener odwołuje się po nazwie. Poświadczenie wiążą dwa Manifests: manifest.yaml z k8s-secret-from-parameter, który renderuje Secret z wartości niesionej przez dołączenie, dla wydania z osobnymi kluczami; oraz manifest-existing-secret.yaml z k8s-existing-secret, który nic nie renderuje i kieruje każdego konsumenta do obiektu Secret już istniejącego w przestrzeni nazw, dla wydania wspólnego i złożonego.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `model-api-key-sharing`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `model-api-key-sharing` i bez `dir`: zapisuje ono przykład w nowym folderze `model-api-key-sharing`. Następnie wywołaj narzędzie `build` raz dla każdego pliku Release, w tej kolejności — `release-per-consumer.yaml`, `release-shared.yaml` i `release-composed.yaml` — za każdym razem z `workspace_root` ustawionym na `model-api-key-sharing`, `release` ustawionym na ten plik, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj, które pliki zapisała każda kompilacja; znajdują się w `model-api-key-sharing/dist/`.

Osobne dla każdego konsumenta — każde połączenie ma własny klucz

aggregate-per-consumer.yaml wypełnia slot na połączeniu każdego agenta, z innym origin dla każdego agenta:

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

Dołączenie na połączeniu staje się jednym z własnych dołączeń agenta, nazwanym od połączenia i slotu — tutaj gateway.credential — więc emitowane są dwa obiekty Secret, po jednym na agenta, każdy z materiałem własnym tego agenta:

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"

a każdy Deployment odwołuje się do własnego:

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

Unieważnienie klucza jednego agenta pozostawia drugiego działającego.

Wspólne — jeden Secret, do którego odwołuje się każde połączenie

Poświadczenie na połączeniu jest zapisywane na tym połączeniu: nic dołączonego gdzie indziej go nie wypełnia. Dlatego wielu konsumentów współdzieli jedno poświadczenie przez sposób autorstwa: poświadczenie każdego połączenia odczytuje tę samą wartość, a ta wartość wskazuje jeden Secret.

aggregate-shared.yaml deklaruje jeden parametr i odczytuje go na obu połączeniach:

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

Wydanie wiąże poświadczenie z k8s-existing-secret, który odczytuje origin jako nazwę obiektu Secret już istniejącego w przestrzeni nazw. Nie renderuje on żadnego obiektu Secret — zapisywane są tylko Service bramy i dwa obiekty Deployment — a oba obiekty Deployment odwołują się do jednego obiektu Secret wskazanego przez parametr:

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

To dokładnie jeden fizyczny Secret, tworzony poza encją Release przez tego, kto ją wdraża, i odczytywany przez każdego konsumenta. Materiał klucza nigdy nie przechodzi przez autorski plik ani wyrenderowany artefakt.

To, co niesie parametr, zależy od realizacji, którą wiąże Manifest. Przy k8s-existing-secret jest to nazwa obiektu Secret. Po powiązaniu zamiast tego z k8s-secret-from-parameter te same dwa połączenia odczytujące jeden parametr niosłyby sam klucz, a budowanie wyrenderowałoby jeden Secret na konsumenta, każdy z tym samym materiałem: renderowanie przebiega dla każdego komponentu osobno, a ta realizacja nazywa renderowany Secret od konsumującego komponentu i połączenia. Jeden parametr sprawia, że konsumenci się nie rozchodzą; to, która realizacja go odczytuje, decyduje, czy współdzielą zasób. Poświadczenie generowane w klastrze jest współdzielone w ten sam sposób — jedno żądanie i wiele odwołań; zob. Model poświadczeń.

Złożone — wspólna wartość domyślna, jedno połączenie ją nadpisuje

aggregate-composed.yaml zachowuje wspólny parametr jako wartość domyślną i pozwala jednemu połączeniu wskazać własny 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

Nadpisanie jest tym, co zapisuje autor tego jednego połączenia; nic na nie nie spływa kaskadowo, a writer zachowuje wspólny Secret bez zmian:

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

Poświadczenie połączenia jest całym, odrębnym dołączeniem, więc nadpisanie powtarza każde potrzebne pole — tutaj typ encji Feature, key i origin — i nie dziedziczy żadnego z wartości domyślnej.

Co daje slot

core/ai-agent/crewai deklaruje slot raz, na swoim gnieździe model, a wszystkie trzy formy są wyborami dokonanymi w encji 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]

Slot jest opcjonalny, więc czwarty wariant to niedołączanie niczego: po usunięciu bloku features: z obu połączeń wyrenderowane drzewo traci każdy wpis env OPENAI_API_KEY, pozostawiając dwa obiekty Deployment i Service bramy. Nic nie jest wymyślane, by wypełnić lukę. Encja katalogu jest identyczna w każdym przypadku; decyduje autor.

To się buduje, ponieważ brama w tym przykładzie, core/ai-model/openai-compatible, nie ma etykiety component.aggrega.ai/hosting. Połączenie bez poświadczenia z celem, który katalog oznacza jako managed — na przykład core/ai-model/openai — zatrzymuje budowanie na asercji samego agenta, chyba że połączenie stwierdza w swoich values, że cel go nie przyjmuje: unauthenticated: true.

Slot jest też agnostyczny wobec rodziny (feature.aggrega.ai/kind=secret dopuszcza dowolną rodzinę poświadczeń), dzięki czemu ten sam agent może przyjąć Secret, do którego można się odwołać, w helm i poświadczenie wstrzykiwane jako wartość w compose. Dostarczanie poświadczeń — secretKeyRef od początku do końca omawia ten podział między dostawcami, a jego negatywne wydanie pokazuje, co się dzieje, gdy poświadczenie, do którego nie można się odwołać, ma spełnić odwołanie.

Determinizm

Wszystkie trzy wydania budują się z --verify-determinism, który renderuje każdy węzeł dwukrotnie i porównuje wyemitowane bajty:

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

Ponowne zbudowanie dowolnego z trzech z czystego drzewa odtwarza jego wyrenderowany wynik bajt po bajcie.