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

Model poświadczeń

Jedna rodzina dołączeń

Poświadczenie w Aggrega jest encją Feature. Dołącza się je na tej samej powierzchni, pod tym samym słowem kluczowym i w tym samym kształcie co każdą inną encję Feature. Tutaj programista dołącza poświadczenie bazy danych w encji Aggregate, zapisując jego lokalizator w values:

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

a operator dołącza do serwera cel zbierania metryk w encji Release, ponieważ każde wejście przyjmowane przez core/prometheus-exporter — port, ścieżka i interwał zbierania — jest operacyjne, więc zapisuje się je w infra:

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

Istnieje jedno słowo kluczowe dołączenia (features:), jeden kształt kontekstu renderowania (.features.<name> oraz ten sam kształt pod połączeniem, .context.uses.<alias>.features.<slot>, dla dołączenia zapisanego na połączeniu), jedna kolejność wykonania i jeden zestaw współrzędnych wyjściowych — dla dołączenia na komponencie: komponent, do którego jest dołączone, a następnie nazwa, pod którą jest dołączone, niezależnie od tego, czy układ celu przenosi te dwie informacje jako katalog <component>--<instance>/ obok katalogu samego komponentu, czy jako prefiks nazwy pliku <component>--<instance>--. Między dołączeniami różni się to, co wytwarzają — wstrzyknięta wartość, zasób, do którego można się odwołać, sidecar, tożsamość w chmurze — a nie powierzchnia, na której są deklarowane.

Encja Feature poświadczenia niesie na swojej encji katalogu etykietę feature.aggrega.ai/kind: secret. Ta etykieta to metadane opisowe: mówi czytelnikowi, witrynie katalogu i selektorowi etykiet, do czego służy encja Feature. Żadna gałąź kompilatora jej nie odczytuje i żadne zachowanie od niej nie zależy. Zachowanie wynika z encji FeatureRecipe, do której operator przypisuje typ encji Feature.

Model myślowy w jednym zdaniu: istnieje jeden rodzaj dołączenia; różni się to, co ono wytwarza.

Sloty i dołączenia swobodne

Encja Component lub Feature może deklarować sloty w featuresSchema:

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

Dołączenie, którego nazwa instancji odpowiada zadeklarowanemu slotowi, wypełnia ten slot. Dołączenie pod każdą inną nazwą jest dołączeniem swobodnym: encja o nie nie prosiła, a renderuje się ono obok wszystkiego, o co encja prosiła. Wygenerowany schemat dla zadeklarowanego slotu pozostaje otwarty, więc zadeklarowanie jednego slotu nigdy nie zamyka bloku dla dołączeń swobodnych. Jeden kształt zatrzymuje kompilację zamiast się renderować: dołączenie zapisane na samym komponencie, którego encja Feature spełnia selector slotu, którego nic tam nie wiąże — jest to wypełnienie zapisane pod złą nazwą, a nie dołączenie swobodne.

Dwie rzeczy, które slot może ograniczać:

  • inject — mechanizmy dostarczania, które encja Workload może wybrać dla tego, co wypełnia slot. Pusta lista oznacza slot typu czarna skrzynka: dostarcza go własna mechanika encji Recipe (na przykład opcja existingSecret chartu), a encja Workload nie może odwoływać się do niego z kontenera.
  • selector — ciąg selektora etykiet, który muszą spełniać etykiety wypełniającej encji Feature. Tu etykieta kind=secret okazuje się przydatna: autor encji, który chce, aby slot wypełniało tylko poświadczenie, wyraża to selektorem, a sprawdzenie jest oceną zbioru etykiet wykonywaną przez kompilator podczas analizy statycznej.

Trzecią rzeczą, którą slot może zrobić, jest żądanie, aby ostatecznie został powiązany. required: true sprawia, że nazwa slotu jest obowiązkowa: kompilator zatrzymuje się podczas analizy statycznej, gdy nic go nie wiąże, z diagnostyką wskazującą slot i typ komponentu, który go zadeklarował. Żądanie jest oceniane względem zbioru dołączeń, który komponent ma po kaskadowym zastosowaniu każdego zakresu, więc dołączenie wniesione powyżej komponentu wiąże slot dokładnie tak samo jak wypełnienie zapisane na komponencie.

Druga powierzchnia wyraża inne żądanie. Powtarzalna adnotacja encji Component features.aggrega.ai/requiredType.<label> deklaruje nakaz obecności: co najmniej jedno dołączenie musi nieść typ encji Feature wskazany w adnotacji, pod dowolną nazwą i w dowolnym zakresie, a nakaz, którego nic nie spełnia, zatrzymuje kompilację podczas tej samej analizy statycznej z własną diagnostyką. Te dwa mechanizmy nigdy nie odpowiadają za siebie nawzajem — slot pyta, czy jeden nazwany punkt wiązania jest powiązany, nakaz, czy jakieś dołączenie niesie nazwany typ — więc encja, której encja Recipe musi odczytać to, co dołączono, deklaruje slot, a encja, której kontrakt po prostu wymaga obecności jakiejś możliwości, deklaruje nakaz.

Co kompilator gwarantuje, a czego nie

Ta sekcja jest kluczowa. Aggrega to kompilator ahead-of-time, a jego gwarancje są węższe, niż sugeruje czytelnikowi słowo „secret”.

Kompilator nigdy nie rozwiązuje poświadczenia. Nie uwierzytelnia się w API chmury, nie czyta sejfu i nie pobiera materiału podczas aggrega build. Wartości values i infra dołączenia poświadczenia przechodzą przez graf do kontekstu renderowania jako nieprzezroczyste skalary, a encja FeatureRecipe renderuje je do artefaktu, jakiego oczekuje platforma docelowa. Rozwiązanie następuje później, w klastrze lub w menedżerze stanu IaC, względem tego, na co wskazuje wyrenderowany artefakt.

Kompilator nie potrafi odróżnić wskaźnika od wartości materiału. Jest agnostyczny wobec tego, co oznacza skalar (zob. 05-invariants.md). Dołączenie poświadczenia, którego lokalizator niesie współrzędną magazynu (path, key, ARN), renderuje odwołanie do tej współrzędnej; dołączenie poświadczenia, którego lokalizator niesie sam materiał, renderuje materiał dosłownie do pliku wyjściowego. Oba przypadki są dozwolone, a kompilator traktuje je identycznie, ponieważ nie ma sposobu, by je rozróżnić.

Uczciwe sformułowanie gwarancji brzmi więc:

Aggrega gwarantuje, że kompilator nie wykonuje żadnego rozwiązywania. Nie gwarantuje, że wyrenderowane wyjście nie zawiera materiału — zależy to całkowicie od tego, która encja Feature poświadczenia jest dołączona i co umieścił w niej jej autor: programista w values lub operator w infra.

Dwie konsekwencje, które warto przyswoić:

  • Wyrenderowane drzewo artefaktów jest tak wrażliwe jak jego dołączenie niosące najwięcej materiału. Należy odpowiednio traktować dist/: jeśli jakiekolwiek dołączenie niesie materiał inline, drzewo zawiera materiał.
  • Własne rodziny katalogu core/secret-value i core/referenced-secret obejmują formy przyjmujące wartość bezpośrednio. Istnieją, ponieważ rzeczywiste wdrożenia potrzebują ścieżki dla lokalnego programowania, i otwarcie to przyznają: dostarczone przykłady używają oczywistych symboli zastępczych (dev-root-pw-change-me) właśnie po to, by materiał w wyrenderowanym przykładzie wyraźnie nie był prawdziwym poświadczeniem. Dla wdrożenia, które nie może nieść materiału, należy dołączyć opartą na magazynie encję Feature poświadczenia, której encja FeatureRecipe emituje zasób pobierania (ExternalSecret, zasób niestandardowy pobierający z sejfu, natywne dla dostawcy odwołanie do sekretu), a nie taki, który emituje dane.

Konwencja biblioteki standardowej polega na tym, że poświadczenie żąda się jako dołączenia, zamiast zapisywać je w bloku values, tak aby zamiana wypełnienia dla lokalnego programowania na wypełnienie oparte na magazynie była zmianą w encji Manifest, a nie edycją intencji programisty. To konwencja, której przestrzega katalog, a nie reguła egzekwowana przez kompilator.

Zadeklarowana wrażliwość

Kompilator nie potrafi odróżnić wskaźnika od wartości materiału, zgodnie z poprzednią sekcją — ale autor potrafi i może to zadeklarować. Wrażliwość w Aggrega to adnotacja na deklaracji: autor encji katalogu stwierdza, co niesie tajny materiał, a kompilator wyprowadza resztę z tego stwierdzenia oraz z okablowania, które już zbudował. Nic nie jest wnioskowane z wartości i nic nie jest zgadywane z nazwy pola.

Zapisuje się ją w dokładnie dwóch miejscach, które niosą rzeczywiście różne twierdzenia.

Na liściu schematu — ta dana jest tajnym materiałem. Liść values, infra lub provides deklaruje sensitive: true:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

Na slocie dołączenia — cokolwiek wiąże ten punkt, obsługuje tajny materiał. Slot featuresSchema deklaruje sensitive: true:

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Te dwa poziomy nie są wygodnym duplikatem jeden drugiego, a kształt poświadczenia, do którego można się odwołać, jest przykładem, który pokazuje dlaczego. Takie poświadczenie publikuje provides.name i provides.key — lokalizator zasobu i klucz danych w nim — i żaden z nich nie jest wrażliwy: nazwa obiektu Secret w Kubernetes jest publiczna, podobnie jak klucz w nim. Oba są renderowane jawnym tekstem do własnego manifestu konsumenta jako secretKeyRef. Mimo to slot, który to poświadczenie wypełnia, bez wątpienia obsługuje tajny materiał. Jeden poziom nie może wyrazić obu faktów: oznaczenie opublikowanych lokalizatorów, aby slot był odczytywany jako wrażliwy, stwierdzałoby o nich coś fałszywego i przenosiło ten błąd wszędzie, gdzie deklaracja jest odczytywana.

Z tych dwóch deklaracji kompilator wyprowadza dla każdego dołączenia, czy obsługuje ono materiał zadeklarowany jako wrażliwy — prawda, gdy dołączona encja Feature deklaruje wrażliwy liść lub gdy slot, który wiąże, deklaruje taki liść, przy czym wystarczy jedno z nich. Wyprowadza to z dołączenia w postaci, jaką ma po złożeniu wszystkich zakresów autorskich, więc deklaracja z szerszego zakresu, którą wyparło węższe wypełnienie, nie pozostaje, a żądanie slotu dotyczy wypełnienia, które faktycznie zwyciężyło. Encja Feature poświadczenia, która nie deklaruje żadnego wrażliwego liścia — ponieważ materiał należy do silnika docelowego, a autor niczego nie zapisuje — nadal daje wrażliwe dołączenie, gdy wiąże wrażliwy slot.

Granica, powiedziana wprost

Słowo „wrażliwy” skłania czytelnika do oczekiwania mechanizmu poufności. Nie jest nim, a gwarancja jest węższa, niż sugeruje nazwa, na pięć konkretnych sposobów:

  • Nie szyfruje. Nic nie jest opakowywane, pieczętowane ani przekształcane.
  • Nie zmienia werdyktu kompilacji, z jednym wyjątkiem. Żadna kompilacja nie zatrzymuje się z powodu brakującej deklaracji, a katalog, którego encje poświadczeń nie niosą żadnej deklaracji, kompiluje się pomyślnie. Żadna wartość nie jest przyjmowana ani odrzucana dlatego, że istnieje deklaracja, z wyjątkiem sytuacji, gdy valuesMapping encji Recipe lub FeatureRecipe dla CloudFormation odczytuje wartość zadeklarowaną jako wrażliwa, aby wypełnić parametry pobranego szablonu: wtedy każdy literał wiązany przez mapowanie jest odrzucany, więc dodanie deklaracji może zamienić kompilację, która się udawała, w taką, która się zatrzymuje — zob. A secret bound to a CloudFormation parameter would be written into the template (Sekret powiązany z parametrem CloudFormation zostałby zapisany w szablonie). We wszystkich innych miejscach dodanie deklaracji do istniejącego katalogu sprawia, że każda kompilacja, która się udawała, nadal się udaje.
  • Nie gwarantuje, że wyrenderowane wyjście jest wolne od materiału. Gwarancja sformułowana powyżej pozostaje bez zmian: to, czy artefakt niesie materiał, zależy od tego, które wypełnienie dołączono i co umieścił w nim jego autor. Wartość zadeklarowana jako wrażliwa, podana inline, jest renderowana dokładnie tak samo jak niezadeklarowana wszędzie tam, gdzie kompilacja w ogóle ją renderuje — opisane wyżej odrzucenie w CloudFormation zatrzymuje literał zamiast go renderować, a funkcja wewnętrzna jest zapisywana tak, jak została podana, łącznie z jej tekstem — a dist/ pozostaje tak wrażliwe jak jego dołączenie niosące najwięcej materiału.
  • Nie wymusza mechanizmu dostarczania. Deklaracja nie może zamienić wartości inline w odwołanie do magazynu i nie zawęża tego, na co pozwala lista dozwolonych inject slotu. Wymuszenie dostarczania oznaczałoby emitowanie zasobu, którego autor nigdy nie zadeklarował, a właśnie tego zabrania niezmiennik braku infrastruktury widmo — zob. 05-invariants.md.
  • Na większości celów nie zmienia żadnego wyrenderowanego bajtu i na nich nigdy tego nie zrobi. Dwie dostarczone ścieżki renderowania reagują na deklarację w tym, co wytwarzają (dostawcy Helm, Helm-Chart i Compose również ją odczytują, wyłącznie po to, by utrzymać oznaczoną wartość poza tekstem błędu): dostawca Terraform oznacza wejście dołączonego modułu niosące materiał zadeklarowany jako wrażliwy własnym atrybutem wrażliwości Terraform — zob. language-reference/providers/terraform.md „Wejścia modułu zadeklarowane jako wrażliwe”; gdy valuesMapping encji Recipe lub encji FeatureRecipe encji Feature dołączonej do komponentu wymyśla nazwy wejść, żadne wejście nie może nieść atrybutu, a kompilacja wypisuje o tym ostrzeżenie, zob. A declared-sensitive value reaches the target through a values mapping (Wartość zadeklarowana jako wrażliwa trafia do celu przez mapowanie wartości) — a dostawca CloudFormation odrzuca opisane wyżej wiązania literałów, co zatrzymuje kompilację zamiast zmieniać jej bajty. We wszystkich innych miejscach dodanie deklaracji w istniejącym katalogu pozostawia każdy wyrenderowany artefakt identycznym. Granica poza tym ma charakter strukturalny, a nie zależy od tego, co zostało zbudowane: deklaracja może dotrzeć do wyrenderowanego artefaktu tylko na platformie docelowej, której własny język zna pojęcie wrażliwości — deklarację, którą ta platforma rozumie i która określa, jak wyświetla wartość, a nie jak ją przechowuje. Na celu bez takiego pojęcia deklaracja nie ma w co się przekształcić, więc identyczne wejście renderuje się identycznie z nią lub bez niej, na stałe.

Deklaracja zmienia natomiast to, co CLI wypisuje do przeczytania przez człowieka. Wartość zadeklarowana jako wrażliwa jest zastępowana stałym symbolem zastępczym w śladzie każdego przebiegu i w widokach inspect, przy czym klucz zostaje zachowany, a ukrywana jest tylko wartość. To decyzja dotycząca wyświetlania na powierzchniach, których nikt nie wdraża, a wyrenderowane artefakty są emitowane dosłownie, ponieważ to one są wdrażane.

Tam, gdzie kompilator może zidentyfikować wartość po kluczu — zadeklarowany liść lub klucz dostarczania niosący materiał z zadeklarowanego klucza provides — podstawienie jest dokładne. Wartość, którą szablon już zapisał w innym dokumencie, nie ma klucza, przy którym można by podstawić, ponieważ wyrenderowany dokument nie zapisuje, z której deklaracji pochodzi każdy znak, a odtworzenie tego oznaczałoby inspekcję treści. Dlatego ślad pokazuje taki dokument, oceniając ten sam szablon po raz drugi względem kontekstu, w którym dane zadeklarowane jako wrażliwe są już odczytywane jako symbol zastępczy, i oznacza wynik jako ponowne renderowanie, a nie jako to, co zostało wyrenderowane: szablon rozgałęziający się według treści wartości renderuje się inaczej względem symbolu zastępczego, a dana, której żadna deklaracja nie wskazuje, przechodzi bez zmian. Powierzchnie, to oznaczanie i jego ograniczenia opisano w language-reference/vocabulary/compact-form-authoring.md „Deklarowanie liścia jako wrażliwego”.

Uczciwe sformułowanie tego, co daje ta oś, brzmi więc:

Deklaracja wrażliwości to wyraz intencji autora, który podróżuje wraz z encją, aby narzędzia i polityki mogły wnioskować o tym, co obsługuje wdrożenie. Nie jest to mechanizm, który je chroni.

Ochrona materiału pozostaje zadaniem magazynu sekretów, klastra i potoku, który obsługuje wyrenderowane drzewo — jak mówi reszta tego rozdziału.

Jak poświadczenie trafia do kontenera

Dwa kształty dostarczania, wybierane przez encję FeatureRecipe dołączenia, a nie przez programistę:

Wstrzyknięta wartość. Encja FeatureRecipe deklaruje injectMapping i żadnych zasobów. Jej wyjście jest głęboko scalane z potokiem dostarczania komponentu konsumującego, zanim bazowa encja Recipe się wyrenderuje, więc encja Recipe odczytująca .context.inject.env.<KEY> otrzymuje wartość. Nic samodzielnego nie jest emitowane.

Dwa poświadczenia dostarczone pod jednym kluczem zatrzymują kompilację, wskazując oba dołączenia: mapowanie zapisujące klucz, który inna dołączona encja Feature już dostarczyła — przez własne mapowanie tej encji Feature lub jej własny blok inject: — jest odrzucane zamiast scalane, więc jedno poświadczenie nigdy nie jest przedstawiane w miejsce innego. Reguła jest taka sama dla każdego dołączenia, niezależnie od tego, gdzie je dołączono i czy wypełnia slot na komponencie, czy na połączeniu. Mapowanie zastępujące klucz dostarczony przez własny blok inject: komponentu lub jedno z jego połączeń to przechwycenie, na którym opierają się encje Features routingu, i pozostaje dozwolone.

Zasób, do którego można się odwołać. Encja FeatureRecipe deklaruje source, workload, artifacts i/lub valuesMapping, więc emituje zasób — zwykle natywny dla platformy obiekt Secret. Publikuje tożsamość tego zasobu przez swoje provides, a konsument odczytuje ją z powrotem jako .features.<name>.provides.name / .provides.key. Własna nazwa zasobu jest wyprowadzana z tych samych opublikowanych provides, więc nazwa odczytywana przez konsumenta i nazwa noszona przez zasób są jednym ocenionym ciągiem, a nie dwoma wyprowadzeniami, które mogłyby się rozjechać.

Encja Workload encji Recipe konsumuje wypełnienie, do którego można się odwołać, przez mapę attachments: kontenera:

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

Syntezator rozwiązuje odwołanie na podstawie opublikowanych provides slotu — secretKeyRef Kubernetes dla as: env, wolumin oparty na sekrecie dla as: file. Autor encji Recipe zapisuje tylko nazwę slotu i mechanizm.

Encja FeatureRecipe może robić obie rzeczy: przepisywać potok dostarczania i emitować zasób. Może też deklarować pipeline kroków Wasm, które uruchamiają się jednakowo dla każdej rodziny dołączeń — dołączenie poświadczenia może przekształcać wyrenderowane dokumenty komponentu gospodarza na zaproszenie dokładnie tak, jak może to robić dołączenie operacyjne.

Kto nadaje nazwę poświadczeniu

Lokalizator poświadczenia — nazwę sekretu, wpis magazynu do pobrania, wartość do dostarczenia — zapisuje ten, kto go zna, a nie zawsze jest to programista. Połączenie okablowane przez encję Release nie ma wpisu w encji Aggregate, a encja Release nigdzie nie zapisuje values, więc poświadczenia, które brałoby lokalizator wyłącznie z values, nigdy nie dałoby się wskazać na takim połączeniu ani na żadnym dołączeniu tworzonym przez encję Release.

Dlatego każda encja Feature poświadczenia z biblioteki standardowej, która niesie lokalizator wywołującego — core/referenced-secret, core/referenced-secret-set, core/secret-value i core/secret-provided — przyjmuje go od dowolnego z autorów: od programisty w values dołączenia, w encji Aggregate, lub od operatora w jego infra, w encji Release. Liść ma jedną nazwę, jeden kształt i jedną deklarację sensitive: true w obu filarach, a każda realizacja odczytuje ten filar, który go niesie. Zakaz values: w encji Release pozostaje nienaruszony: lokalizatorem operatora jest infra. Encje Features, które nie przyjmują lokalizatora — core/random-password, core/generated-secret — nie są objęte zmianą.

Dokładnie jeden, pilnowany przez encję Feature. Dołączenie niesie lokalizator w jednym filarze, nigdy w obu i nigdy w żadnym. Schemat żadnego filaru nie może tego wyrazić, ponieważ każdy filar jest walidowany osobno; robi to własny blok assertions każdej encji Feature, a dołączenie, które go narusza, zatrzymuje kompilację, wskazując encję Feature, dołączenie i komponent. To kontrakt encji katalogu, przestrzegany tak jak każda asercja encji Feature: kompilator ocenia szablon napisany przez autora encji Feature i nie ma żadnej własnej reguły dotyczącej poświadczeń, filarów ani lokalizatorów.

Co pozostaje na swoim miejscu. Każde inne pole zachowuje swój filar — klucz danych poświadczenia, do którego można się odwołać, nadal zapisuje się w values, więc dołączenie tworzone wyłącznie przez encję Release odczytuje jego wartość domyślną — a core/secret-provided nadal dostarcza wyłącznie przez własny blok inject: dołączenia, który zapisuje tylko encja Aggregate i którego dołączenie połączenia nigdy nie niesie.

Współdzielenie jednego poświadczenia przez wielu konsumentów

Poświadczenie może przechowywać konsument. Slot należy do tej encji, która potrzebuje poświadczenia, a często jest nią wywołujący, a nie to, co jest wywoływane: komponent, który przedstawia klucz, gdy nawiązuje połączenie, deklaruje slot na ten klucz we własnej encji katalogu, na gnieździe, przez które nawiązuje połączenie, dzięki czemu klucz jest przechowywany na połączeniu, na którym jest przedstawiany — i nic w krawędzi uses nie zobowiązuje celu do jego dostarczenia. core/ai-agent/crewai jest dostarczonym przykładem tego kształtu — jego gniazdo model deklaruje opcjonalny slot credential z selektorem feature.aggrega.ai/kind=secret, inject: [env] i sensitive: true, a encja Aggregate wypełnia go pod połączeniem, w uses.model.<alias>.features.credential. To, co komponenty modeli z biblioteki standardowej publikują do odczytu przez konsumenta, to lokalizacja serwowania i nazwa modelu, a nie poświadczenie, więc klucz, który agent przedstawia przy wywołaniu tego punktu końcowego, jest deklarowany przez agenta i przechowywany na jego połączeniu. Slot jest opcjonalny, ale połączenie z modelem, który jego katalog oznacza etykietą component.aggrega.ai/hosting: managed, i które nie niesie żadnego poświadczenia, zatrzymuje build, chyba że jego własne values stwierdzają, że model żadnego nie wymaga, unauthenticated: true — jest to asercja, którą niesie encja katalogu agenta i którą kompilator ocenia tak jak każdą asercję, odczytując etykietę jako ciąg znaków. Komponent modelu, z którym się łączy, może przechowywać własny klucz dla własnych wywołujących — core/ai-model/vllm deklaruje w tym właśnie celu slot api_key — i są to dwa odrębne punkty wiązania: załącznik wiąże slot po nazwie tam, gdzie jest on zadeklarowany, na komponencie lub na połączeniu, więc wypełnienie jednego nic nie mówi o drugim.

To właśnie to umiejscowienie sprawia, że dwie poniższe formy w ogóle są decyzjami wdrożeniowymi: gdy slot znajduje się u konsumenta, jeden build może dać każdemu konsumentowi własny klucz, a inny może dać im wszystkim ten sam, bez zmiany żadnej encji katalogu między nimi.

Ta sama encja katalogu obsługuje oba kształty, a to autor wybiera, który:

  • Na konsumenta. Każdy konsument wypełnia własny slot własnym załącznikiem poświadczenia — na komponencie albo na swoim połączeniu, gdy slot należy do gniazda. Każdy otrzymuje własny wyrenderowany zasób.
  • Współdzielone. W przypadku slotu deklarowanego przez komponent jedno poświadczenie dołącza się raz we współdzielonym zakresie — podsystemie w encji Aggregate, granicy w encji Release — i spływa ono kaskadowo do każdego komponentu w tym zakresie. Slot deklarowany przez gniazdo wypełnia się dla każdego połączenia osobno, a nic nie spływa kaskadowo do wnętrza połączenia, więc tam współdzielony kształt zapisuje się na każdym połączeniu: poświadczenie każdego połączenia odczytuje jeden parametr. Gdy konsumenci muszą odwoływać się do jednego fizycznego zasobu, ten parametr go wskazuje — core/referenced-secret powiązany z realizacją existing-Secret kieruje każde połączenie do jednego obiektu Secret po nazwie, a wygenerowane poświadczenie to jedno żądanie i wiele odwołań, jak opisano poniżej.

Sposób renderowania współdzielonej formy trzeba określić precyzyjnie, bo łatwo założyć coś innego: współdzielony załącznik renderuje jeden zasób na konsumenta, każdy z tym samym materiałem z jednej deklaracji. Renderowanie przebiega dla każdego komponentu, a nazwa zasobu wyprowadzona z {{ .context.instance_id }}-{{ .attachment_name }} różni się zatem dla każdego konsumenta. Współdzielona jest pojedyncza deklaracja; emitowane zasoby nie są deduplikowane do jednego. Jeden parametr odczytywany na każdym połączeniu renderuje się tak samo w realizacji, która renderuje zasób — jeden na połączenie, przy czym nazwą załącznika jest alias połączenia, kropka i slot.

Jeśli wdrożenie potrzebuje dokładnie jednego fizycznego obiektu Secret odczytywanego przez kilku konsumentów, należy to wyrazić za pomocą encji Feature poświadczenia, której encja FeatureRecipe działa w zakresie granicy (executionScope: boundary), dzięki czemu renderuje się raz dla granicy, a nie raz dla każdego komponentu.

Klucz przechowywany przez oba końce połączenia

Serwer, który sprawdza klucz, i komponent, który go wywołuje, przechowują ten klucz każdy po swojej stronie. Serwer przechowuje klucz, który weryfikuje, w slocie własnej encji Component — core/ai-model/vllm, core/ai-model/tei i core/ai-model/tgi deklarują każdy api_key, podobnie jak model i brama LiteLLM dla klucza, który LiteLLM nazywa kluczem głównym — a jego encja Recipe dostarcza to, co wypełnia slot, jako zmienną, którą odczytuje serwer. Wywołujący przechowuje klucz, który przedstawia, po swojej stronie: na połączeniu, na którym go przedstawia, w slocie deklarowanym przez jego gniazdo — tak jak gniazdo model encji core/ai-agent/crewai deklaruje credential — albo, gdy jego encja Component deklaruje klucz na sobie, w tym slocie, dla każdego nawiązywanego połączenia. Żaden koniec nie widzi załączników drugiego: załącznik na połączeniu trafia wyłącznie do wywołującego, a wyrenderowane wyjście serwera jest takie samo bez względu na to, co niosą docierające do niego połączenia. Serwer nigdy nie dowiaduje się, jaki klucz przechowuje wywołujący, a wywołujący odczytuje tylko to, co publikuje serwer — adres i nazwę modelu. Oba końce są zgodne, ponieważ encja Aggregate zasila je z jednego parametru:

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

To, czy jest to jeden sekret, czy dwa, wynika z tego, gdzie oba końce rozwiązują sekrety. Dostawca rozwiązuje sekret przez odwołanie w obrębie zakresu sekretów: przestrzeni nazw Kubernetes w helm, projektu Compose w compose, konfiguracji głównej granicy w terraform, a w cloudformation stosu, na koncie i w regionie AWS, w których jest wdrażany. Gdy oba końce znajdują się w jednym zakresie, odwołują się do jednego zasobu sekretu. Gdy znajdują się w różnych zakresach, każdy koniec przechowuje własny zasób sekretu, zrealizowany z tego samego wpisu magazynu. Encja Manifest wybiera realizację każdego końca — według typu Feature albo, dla pojedynczego załącznika, według jego nazwy, która dla załącznika połączenia ma postać <alias>.<slot> (local.credential powyżej). Ponieważ oba zasila jeden parametr, obie realizacje odczytują origin jako ten sam rodzaj lokalizatora: obie jako nazwę obiektu Secret, obie jako klucz wpisu magazynu albo obie jako samą wartość.

W helm, gdy oba końce są w jednej przestrzeni nazw, powiązanie core/referenced-secret z helm/k8s-existing-secret i wypełnienie parametru nazwą obiektu Secret istniejącego w tej przestrzeni nazw, model-keys, sprawia, że oba końce odwołują się do niego po nazwie, i nie renderuje żadnego obiektu Secret. Kontener serwera zawiera:

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

a encja Recipe routera odczytuje tę samą nazwę i ten sam klucz ze swojego połączenia, w .context.uses.local.features.credential.provides. Gdy oba końce są w różnych przestrzeniach nazw, powiązanie go z helm/k8s-external-secret i wypełnienie parametru kluczem wpisu magazynu daje każdemu końcowi własny ExternalSecret we własnej przestrzeni nazw, a oba pobierają ten jeden wpis. W compose oba końce niosą to samo odwołanie ${VAR}, które Docker Compose podstawia ze środowiska, z jakim uruchamiany jest ten jeden projekt. To umiejscowienie jest konwencją, której przestrzega katalog biblioteki standardowej; kompilator niczego nie porównuje między oboma końcami.

Jeden klucz obsługuje każdego wywołującego. vLLM, TEI i TGI sprawdzają każdy jeden klucz, więc każdy wywołujący przedstawia ten sam klucz, a serwer nie potrafi odróżnić jednego wywołującego od drugiego, niezależnie od liczby docierających do niego połączeń. To ograniczenie samego serwera. TGI porównuje swój klucz bez uwzględniania wielkości liter, więc dwa klucze różniące się tylko wielkością liter są dla niego jednym kluczem. Model i brama LiteLLM akceptują też klucze, które same wystawiają, dopóki dołączona jest ich baza danych do rozliczeń.

Poświadczenie generowane przez cel

Gdy encja Release nie dostarcza poświadczenia, encja katalogu często sięga po wartość domyślną do celów deweloperskich — wartość wpisaną bezpośrednio w encji Recipe, wartość domyślną parametru modułu. Ta wartość jest taka sama dla każdego czytelnika katalogu, co jest do przyjęcia przy ewaluacji i w żadnym innym przypadku. core/random-password eliminuje tę potrzebę: nikt nie zapisuje poświadczenia, ponieważ generuje je cel.

Build nie może być miejscem, w którym powstaje hasło. Jego wyjście jest czystą funkcją wejścia i nigdy nie niesie wartości sekretu, więc hasło wylosowane w czasie buildu zmieniałoby się przy każdym buildzie i trafiałoby do wyrenderowanych plików. Encja FeatureRecipe renderuje zamiast tego żądanie — zasób generatora wskazujący zasób sekretu, który wypełnia — a cel losuje wartość w czasie wdrożenia:

  • w helm, kontroler w klastrze: generator haseł External Secrets Operator, uzgadniany za pomocą ExternalSecret, lub kontroler kubernetes-secret-generator, uzgadniający StringSecret;
  • w terraform, random_password dostawcy random, losowane przy stosowaniu konfiguracji;
  • w cloudformation, sekret Secrets Manager, który generuje własny ciąg znaków, gdy stos go tworzy.

W każdym przypadku wyrenderowane wyjście wskazuje generator i zasób sekretu i nie niesie żadnej wartości. Jest to właściwość tego, czym dysponuje build, a nie ochrona, którą dodaje: wartość nie istnieje, dopóki cel jej nie utworzy. To, gdzie cel przechowuje ją później, jest sprawą celu — Terraform przechowuje ją w planie i stanie, klaster w obiekcie Secret.

Co musi działać w celu. Żądanie zostaje spełnione tylko tam, gdzie coś je spełnia. W helm jest to kontroler, a kompilator nie może sprawdzić klastra, aby wiedzieć, czy jakiś działa, więc encje FeatureRecipes dla helm zatrzymują build, chyba że encja Release potwierdzi wymaganie wstępne za pomocą infra.control_plane_present: true na załączniku. W terraform i cloudformation wartość generuje samo apply lub stos i nic nie musi działać wcześniej.

Gdzie nie można tego użyć. Compose nie uruchamia żadnego kontrolera i nie ma zasobu generującego wartość, więc żadna encja FeatureRecipe nie realizuje tam core/random-password, a build, który wiąże go w compose, zatrzymuje się z braku takiej encji. Encja Release kierowana na compose dostarcza poświadczenie za pomocą core/secret-value, zwykle jako odwołanie do zmiennej, które Docker Compose podstawia przy uruchamianiu stosu.

Jak odczytuje je konsument. core/random-password publikuje te same provides.name i provides.key co core/referenced-secret i niesie tę samą etykietę feature.aggrega.ai/kind: secret, więc slot wybierający rodzinę poświadczeń go dopuszcza, a konsument odczytuje wygenerowane poświadczenie dokładnie tak samo jak takie, które już istnieje.

Jak kilku konsumentów współdzieli jedno. Generator losuje nową wartość dla każdego żądania, więc zasada współdzielenia z poprzedniej sekcji obowiązuje tu z większą ostrością: wygenerowane poświadczenie dołączone we współdzielonym zakresie — lub na każdym konsumencie — renderuje jedno żądanie na konsumenta, a każde żądanie losuje inne hasło, którego baza danych i jej klienci nie mogą użyć. Jedno wygenerowane poświadczenie współdzielone przez kilku konsumentów wyraża się jako jedno żądanie i wiele odwołań: core/random-password na jednym komponencie, z wartością name ustalającą obiekt Secret, który wypełnia, oraz core/referenced-secret na pozostałych, powiązany z realizacją existing-Secret i wskazujący tę samą nazwę. Zapisane na podstawie jednego parametru, oba nie mogą się rozjechać, a render niesie dokładnie jedno żądanie, do którego odwołuje się każdy konsument.

core/random-password to nie core/generated-secret. Tamta encja Feature przekazuje poświadczenie silnikowi, który już zarządza całym jego cyklem życia — zarządzanej bazie danych, kontrolerowi bazy danych — i niczego nie renderuje. core/random-password renderuje samo żądanie, dla obciążenia, którego encja Recipe oczekuje przekazania poświadczenia.

Pierwszeństwo załączników

Załącznik może być zadeklarowany jednocześnie w kilku zakresach. Własność spornego pola rozstrzygają trzy zasady, stosowane w tej kolejności:

  1. Pochodzenie. Pole zapisane jawnie wygrywa z polem wniesionym przez rozwinięcie sterowane adnotacjami, niezależnie od tego, z jakiego zakresu pochodzi każde z nich.
  2. Autorytet kompozycji. Deklaracja w encji Aggregate, którą się wdraża, wygrywa z deklaracją wewnątrz encji Aggregate, którą ta komponuje, nawet gdy skomponowany dokument zadeklarował ją w węższym zakresie.
  3. Szczegółowość. W obrębie jednego poziomu tworzenia węższy zakres doprecyzowuje szerszy pole po polu: wypełnienie na poziomie komponentu nadpisuje załącznik o tej samej nazwie instancji obejmujący cały podsystem lub całą granicę tylko w polach, które wymienia, a pola, które pomija, zachowują wartości szerszego zakresu.

Strona dewelopera dostarcza values, a strona operatora dostarcza infra, więc obie nigdy nie spierają się o to samo pole. Encja Feature poświadczenia przyjmująca lokalizator z dowolnej strony deklaruje go jako dwa pola, po jednym na filar, a jej własna asercja odrzuca załącznik niosący oba, więc i tam pierwszeństwo nie ma remisu do rozstrzygnięcia. Pierwszeństwo dotyczy wyłącznie wartości pól; nie zmienia kolejności ewaluacji, która podąża za sekwencją kaskady opisaną w 10-compilation-pipeline.md.

Starsze charty wymagające sformatowanego ciągu znaków

Chart czasem wymaga pojedynczego ciągu połączenia z osadzonym materiałem — oracle://admin:PASSWORD@HOST:1521/DB. Kompilator ahead-of-time nie może zbudować tego ciągu ze współrzędnej magazynu, ponieważ nigdy nie przechowuje materiału. Dwie obsługiwane ścieżki:

Szablonowanie po stronie klastra. Encja FeatureRecipe poświadczenia emituje zasób, który formatuje ciąg w klastrze, korzystając z własnego mechanizmu szablonów operatora sejfu. Aplikacja odwołuje się następnie po nazwie do wynikowego obiektu Secret platformy, a kompilator powiązał tę relację, nigdy nie przechowując materiału:

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

Wynoszenie parametrów. Encja Aggregate deklaruje typowany parametr, a otaczający potok CI dostarcza wartość w czasie buildu przez parameters: encji Release — na przykład plik, który zapisuje potok, a encja Release importuje za pomocą parameters: { $import: ./ci-parameters.yaml }. To jawna furtka, która uwidacznia kompromis: materiał przepływa teraz przez build, więc wyrenderowane wyjście go niesie i należy je odpowiednio traktować.

Rozwój lokalny

Wzorcowa ścieżka rozwoju lokalnego pozostawia intencję dewelopera bez zmian i wymienia powiązanie. Encja Aggregate nadal dołącza ten sam typ Feature poświadczenia; lokalna encja Manifest mapuje ten typ na lokalną encję FeatureRecipe zamiast na tę opartą na magazynie. Kompilator nadal niczego nie pobiera — lokalna encja FeatureRecipe po prostu dostarcza natywną składnię dostawcy, którą rozwiązuje lokalne środowisko uruchomieniowe: dla Compose jest to odwołanie do zmiennej, takie jak ${SECRET_NAME}, zapisane w środowisku usługi, które Docker Compose podstawia ze środowiska powłoki lub z pliku .env przy uruchamianiu stosu. Zmiana środowiska to edycja encji Manifest.

Zarządzanie danymi wokół poświadczeń

Aggrega nie modeluje schematów danych — wiersze, kolumny i pliki są sprawą aplikacji. Modeluje tożsamość zarządczą danych za pomocą etykiet, a konwencja biblioteki standardowej jest następująca:

  • Dane znajdują się w komponentach, których etykieta ontologii oznacza je jako stanowe lub zasobopodobne (component.aggrega.ai/type: stateful-server, resource). Broker komunikatów przechowujący zakolejkowane ładunki również do nich należy: niesie stateful-server, gdy posiada własny dysk, i resource, gdy encja Release podłącza hostowany broker, a półka messaging, pod którą się go przegląda, to osobna oś component.aggrega.ai/category.
  • compliance.aggrega.ai/data-class (public, internal, restricted) nadaje tym danym tożsamość semantyczną. Konwencja ustala klucz i jego wartości, a nie to, które komponenty go niosą: żadna encja Component biblioteki standardowej go nie niesie, ponieważ klasa danych przechowywanych przez komponent jest stwierdzeniem o tym, jak dana organizacja używa komponentu, a nie właściwością produktu, więc organizacja określa ją na własnych encjach Components. To zwykła etykieta: selektory etykiet ją oceniają, a wtyczka zarządcza dołączona przez operatora może ją odczytać i odrzucić build. Sam kompilator jej nie interpretuje i nie stawia żadnej klasy wyżej od innej — jakie klasy istnieją i jak się szeregują, to własne ustawienia dołączonej polityki, jak w ../language-reference/examples/policy-data-class-route/.

data-class i sensitive to dwie osie, a ich połączenie powoduje utratę informacji. Leżą obok siebie i łatwo pomylić je z jedną powierzchnią, dlatego należy pamiętać o tym rozróżnieniu:

compliance.aggrega.ai/data-classsensitive
Kształtstopniowana — public / internal / restrictedlogiczna
Szczegółowośćcały węzełjeden liść schematu lub jeden slot załącznika
Określajaką tożsamość zarządczą mają dane przechowywane przez komponentże ta dana jest materiałem tajnym albo że ten punkt wiązania go obsługuje
Zapisywana jakoetykieta w metadata.labelssłowo kluczowe w deklaracji

Żadna nie zastępuje drugiej: wtłoczenie wrażliwości w stopniowaną etykietę narzuciłoby uporządkowanie faktowi, który go nie ma, a wtłoczenie klasy danych na liść narzuciłoby szczegółowość, której klasyfikacja nie ma. Encja może nieść obie, a komponent przechowujący dane restricted, którego slot poświadczenia jest zadeklarowany jako sensitive, stwierdza dwie odrębne prawdziwe rzeczy. Słowa kluczowe dla liścia i slotu omówiono w ../language-reference/vocabulary/compact-form-authoring.md „Deklarowanie liścia jako wrażliwego” i ../language-reference/entities/component.md „Deklarowanie slotu jako wrażliwego”.

Szyfrowanie danych w spoczynku celowo pozostaje poza intencją dewelopera i poza kompilatorem. Należy do encji Recipe Ops dla komponentu stanowego oraz do wtyczki renderującej, która odczytuje etykiety węzła i emituje konfigurację zaszyfrowanego magazynu. To umiejscowienie jest wskazówką projektową co do tego, gdzie należy ta kwestia — kompilator nie sprawdza, czy jakakolwiek encja Recipe ją respektuje.

Co jest tu wyróżniające, a co nie

Publiczne pozycjonowanie warto wyrazić prosto i wąsko, aby czytelnik mógł je właściwie ocenić.

Wyróżniające: kontrakt socketu jest publikowany, a nie deklarowany inline. Kontrakt, który musi spełnić poświadczenie — slot, jego lista dozwolonych sposobów dostarczenia, jego selektor etykiet — jest tworzony na encji katalogu przez tego, kto ją opublikował, i znajduje się w katalogu utrzymywanym przez stronę trzecią. Konsument nie opisuje kontraktu inline we własnej konfiguracji; wypełnia kontrakt opublikowany przez kogoś innego, a kompilator sprawdza to wypełnienie względem opublikowanej deklaracji. Konsument i autor kontraktu to różne osoby, pracujące w różnych repozytoriach, w różnych cyklach wydawniczych.

Wyróżniające: wypełnianie jest ograniczone selektorem etykiet. Slot może określić, jaki rodzaj rzeczy może go wypełnić (selector: "feature.aggrega.ai/kind=secret"), zamiast wskazywać konkretną implementację. Sprawdzenie jest ewaluacją zbioru etykiet, więc encja może zaakceptować rodzinę wypełnień, o których nigdy nie słyszała, a nowe wypełnienie staje się dopuszczalne, gdy ma właściwe etykiety.

Niewyróżniające: mapowanie wstrzykiwania. Mapowanie „ta nazwa lokalnej zmiennej środowiskowej otrzymuje tę wytworzoną wartość” to dobrze znany wzorzec; kilka narzędzi konfiguracyjnych i wdrożeniowych wyraża tę samą ideę we własnej składni. Wersja Aggrega to mapowanie ewaluowane z wyprzedzeniem i scalane z potokiem dostarczania, ale idea należy do ekosystemu, nie do nas.

Niewyróżniające: statyczne generowanie z wyprzedzeniem. Statyczne generowanie artefaktów wdrożeniowych z opisu wyższego poziomu, bez dostępu do działającego klastra w czasie generowania, nie jest wynalazkiem Aggrega. Robią to inne narzędzia i robiły to, zanim powstała Aggrega. To, co dodaje Aggrega, to warstwa opublikowanych kontraktów nad tym, a nie samo statyczne generowanie.

To nie jest granica bezpieczeństwa. Nic w tym rozdziale nie jest mechanizmem poufności. Model poświadczeń jest modelem okablowania: decyduje, skąd pochodzi wskaźnik lub wartość, kto może go ograniczać i jak dociera do kontenera. Ochrona materiału to zadanie magazynu sekretów, klastra i potoku, który przetwarza wyrenderowane drzewo.

Odsyłacze