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

Features poświadczeń

Ta strona wyjaśnia jedną ideę, Features poświadczeń z biblioteki standardowej i to, jak encja Manifest wybiera, co realizuje każdą z nich, i nie jest uruchamialnym obszarem roboczym. Jedna intencja programisty, dwa kształty dostarczania poświadczeń buduje jedną encję Aggregate względem dwóch realizacji tego samego poświadczenia; można go zapisać we własnym folderze w następujący sposób:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności:

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

Poświadczenie wypełnia slot, który encja Component deklaruje w swoim featuresSchema (zob. entities/component.md); slot, wypełniająca go encja Feature i encja FeatureRecipe, którą wiąże Manifest, tworzą całą ścieżkę od dołączenia autora do działającego obciążenia roboczego.

Rodzina Feature poświadczeń

Feature poświadczenia nosi etykietę feature.aggrega.ai/kind: secret. Etykieta to metadane katalogu opisujące, co tworzy dołączenie; żadna gałąź kompilatora jej nie odczytuje, a Feature poświadczenia dołącza pod features:, jak każdą inną encję Feature, programista w encji Aggregate albo operator w encji Release.

Biblioteka standardowa dzieli Features poświadczeń według tego, co realizacja robi z sekretem:

  • core/secret-value dostarcza wartość do potoku wstrzykiwania komponentu, gdzie odczytuje ją jego encja Recipe — wartość chartu, zmienna środowiskowa.
  • core/secret-provided również daje wartość, ale zamiast tego publikuje ją jako klucz provides, więc to własny blok inject: dołączenia w przezroczystym slocie określa, dokąd ona trafia.
  • core/referenced-secret wskazuje zasób sekretu — Secret w Kubernetes, sekret w AWS Secrets Manager, wpis w Vault — tworzony przez jego realizację albo już istniejący, i publikuje name oraz key tego zasobu, które konsument odczytuje jako .features.<slot>.provides.name i .features.<slot>.provides.key.
  • core/referenced-secret-set materializuje jeden taki zasób zawierający zbiór kluczy danych dostarczony przez autora i publikuje wyłącznie jego lokalizator, dla konsumenta, którego cel już ustala odczytywane nazwy kluczy. Docker Compose nie ma takiego zasobu, więc tam jego realizacja dostarcza klucze zamiast tego jako wartości, jak opisano poniżej. Używa go MariaDB (chart Bitnami) — jeden wielokluczowy Secret poświadczeń.
  • core/generated-secret niczego nie tworzy: silnik docelowy sam generuje poświadczenie i nim zarządza, tak jak zarządzana baza danych robi to ze swoim hasłem administratora. Operator dołącza go w encji Release, ponieważ to, czy poświadczenie należy do silnika, wynika z encji Recipe wybranej przez Manifest; Terraform RDS (wbudowany artefakt HCL) w ten sposób wiąże wymagany slot.
  • core/random-password renderuje żądanie, aby cel wygenerował hasło do zasobu sekretu, i publikuje lokalizator tego zasobu tak jak core/referenced-secret. Nikt nie zapisuje poświadczenia, a wyrenderowany wynik go nie zawiera.

Są one równorzędne — ta sama etykieta, ta sama powierzchnia dołączania, ten sam slot — więc slot jest zawsze wypełniony, a między encjami Releases zmienia się to, co go wypełnia. Feature poświadczenia deklarujący kontrakt provides zobowiązuje każdy implementujący go FeatureRecipe do opublikowania tych kluczy, a build zostaje zatrzymany, jeśli któryś tego nie zrobi; to właśnie czyni odczyt konsumenta bezpiecznym.

core/random-password potrzebuje czegoś po stronie celu, co wylosuje wartość, ponieważ build nigdy tego nie robi: w Kubernetes kontrolera (External Secrets Operator lub kubernetes-secret-generator), którego obecność encja Release potwierdza za pomocą infra.control_plane_present: true; w Terraform zasobu random_password; w CloudFormation sekretu Secrets Manager, który generuje własny ciąg. Dla Docker Compose nie jest dostarczana żadna realizacja, więc build, który go tam wiąże, zostaje zatrzymany. Każde żądanie losuje własną wartość, więc dwa komponenty współdzielą jedno wygenerowane hasło, gdy dołącza się go raz, z przypiętym name, a w innym miejscu odczytuje przez core/referenced-secret powiązany z helm/k8s-existing-secret.

Kto nazywa poświadczenie: values albo infra, dokładnie jedno

core/secret-value, core/secret-provided, core/referenced-secret i core/referenced-secret-set przyjmują lokalizator poświadczenia od dowolnego z autorów: programista zapisuje go w values dołączenia w encji Aggregate, operator w infra dołączenia w encji Release. Liść jest taki sam w obu — origin lub entries dla zestawu — a każda realizacja odczytuje ten filar, który go przenosi.

Forma operatora pozwala użyć poświadczenia tam, gdzie programista nie może go zapisać: na połączeniu, które łączy encja Release, oraz na dołączeniu tworzonym wyłącznie przez encję Release, ponieważ Release nigdzie nie zapisuje 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

Dokładnie jeden z dwóch. Każdy filar jest walidowany osobno, więc żaden ze schematów nie może wymagać lokalizatora; regułę przechowują zamiast tego własne assertions każdej encji Feature, a dołączenie zawierające lokalizator w obu filarach lub w żadnym zatrzymuje kompilację (E0033), podając encję Feature, dołączenie i komponent. Jest to kontrakt encji katalogu: kompilator ocenia ich asercję tak, jak ocenia asercję dowolnej encji Feature.

Wszystko inne zachowuje swój filar. key pozostaje liściem values, więc dołączenie tworzone wyłącznie przez encję Release odczytuje domyślny klucz danych, value. Zadeklarowanie origin w obu filarach jest dokładnie tym, czego szuka ostrzeżenie o nakładaniu się filarów, więc wczytanie tych encji Features je zgłasza — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Tutaj nakładanie się jest kontraktem; ostrzeżenie nie zmienia żadnego werdyktu ani żadnego wyrenderowanego bajtu.

Encja Manifest wybiera realizację

Kilka FeatureRecipes może implementować jedną encję Feature dla tego samego celu, a wybiera encja Manifest. core/referenced-secret ma trzy w Kubernetes, a o wyborze między nimi decyduje miejsce, w którym znajduje się poświadczenie:

  • helm/k8s-secret-from-parameter zapisuje wartość podaną przez autora w emitowanym przez siebie obiekcie Secret, więc materiał znajduje się w wyrenderowanym wyniku: do ewaluacji i pracy lokalnej.
  • helm/k8s-external-secret renderuje ExternalSecret wskazujący wpis w magazynie sekretów, który External Secrets Operator w klastrze uzgadnia do obiektu Secret.
  • helm/k8s-existing-secret niczego nie emituje: odczytuje origin jako nazwę obiektu Secret, który już istnieje, i publikuje ją w zapisanej postaci.

Pierwsze dwa wyprowadzają nazwę obiektu Secret w ten sam sposób, z wyrenderowanej nazwy hosta i nazwy slotu, więc konsument odczytuje z każdego z nich ten sam lokalizator, a jego wyrenderowane odwołanie się nie zmienia; to właśnie pokazuje przykład. Trzeci publikuje własną nazwę istniejącego obiektu Secret, więc powiązanie go celowo zmienia odwołanie konsumenta.

core/secret-value jest realizowany w Docker Compose przez compose/dotenv-secret, który zapisuje wartość w środowisku usługi dokładnie w postaci podanej przez autora: origin zapisany jako ${DB_PASSWORD} trafia tam jako to odwołanie, które Docker Compose wypełnia z powłoki lub z pliku .env przy uruchamianiu stosu. W Kubernetes helm/env-secret dostarcza wartość do potoku wstrzykiwania, a helm/k8s-secret-from-value dodatkowo zapisuje ją w obiekcie Secret i publikuje jego lokalizator, dla konsumenta, który odczytuje poświadczenie przez odwołanie. Żadna z realizacji dla Kubernetes nie przyjmuje odwołania do zmiennej Compose, którego nic by tam nie wypełniło.

core/referenced-secret jest realizowany w Docker Compose przez compose/dotenv-referenced-secret. Compose nie ma zasobu sekretu, do którego można by się odwołać, więc origin jest samym poświadczeniem, a nie nazwą obiektu Secret: jest dostarczany do potoku wstrzykiwania pod kluczem key dołączenia, a encja Recipe dla Compose, która odczytuje slot, zapisuje go w emitowanym pliku dokładnie w zapisanej postaci, więc origin zapisany jako ${DB_PASSWORD} trafia jako to odwołanie. Nie tworzy żadnego zasobu, więc publikowana nazwa jest pusta, a publikowany klucz to values.key.

core/referenced-secret-set jest realizowany w Docker Compose przez compose/dotenv-secret-set, który dostarcza każdy wpis do potoku wstrzykiwania jako zmienną nazwaną od jego klucza, zapisaną w środowisku usługi dokładnie w zapisanej postaci, więc wpis o wartości ${GITHUB_TOKEN} trafia jako to odwołanie. Nie tworzy żadnego zasobu, więc publikowany lokalizator jest pusty: konsument w Compose odczytuje wpisy z własnego potoku wstrzykiwania zamiast odwoływać się do obiektu Secret po nazwie, jak robią to compose/mcp i compose/mcp-stdio-bridge od wersji 1.1.0 dla server_env serwera Model Context Protocol.

Nazwę FeatureRecipe dostarczanego dla więcej niż jednego celu, np. provided-secret, podaje się w encji Manifest wraz z celem, compose/provided-secret:1.0.0, ponieważ sama nazwa pasuje do obu.

Jedna nazwa, publikowana raz

Encja Recipe konsumenta nigdy nie wyprowadza nazwy obiektu Secret tworzonego przez poświadczenie: odczytuje lokalizator, który publikuje poświadczenie, existingSecret: "{{ .features.root_password.provides.name }}". Nazwa jest zapisywana raz, w provides encji FeatureRecipe, więc zmiana sposobu jej składania to edycja wyłącznie w tym miejscu. Dostarczanie poświadczeń — secretKeyRef od początku do końca buduje ścieżkę z odwołaniem w Kubernetes i ścieżkę ze wstrzykiwaniem w Docker Compose, a Współdzielenie poświadczenia — na konsumenta, współdzielone i oba naraz pokazuje kilku konsumentów mających własny klucz lub współdzielących jeden.