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

Nazywanie wyrenderowanego zasobu

Encja Recipe rutynowo musi nazwać coś, co wytworzyło jej własne wyjście: nazwę hosta publikowaną przez provides:, odwołanie wewnątrz valuesMapping:, identyfikator zapisany w treści artifacts:. Nazwy dostępne do tego celu niosą dwa klucze kontekstu szablonu, a odpowiadają one na różne pytania. Odczytanie niewłaściwego daje wyjście, które jest po cichu błędne, a nie odrzucone — adres wskazujący zasób, którego nic nie wyemitowało — dlatego ta strona wyjaśnia, który klucz odpowiada na które pytanie.

Wyjaśnia też rozróżnienie, na którym opierają się oba klucze: cel (target) i odwołanie (reference) to nie to samo, a cel nigdy nie jest nazwą, którą rozwiąże platforma wdrożeniowa.

Cel nazywa komponent; odwołanie nazywa wyrenderowany zasób

Cel to tożsamość nadana przy tworzeniu dokumentów. Jest to wartość, którą programista zapisuje, aby wskazać, na który komponent wskazuje krawędź — target: my_db w bloku uses — i jest to tożsamość, której kompilacja używa, aby odnaleźć ten komponent, raportować o nim w diagnostyce i indeksować jego fakty. Brzmi tak samo w przypadku każdego dostawcy, ponieważ jest faktem dotyczącym dokumentów autora, a nie jakiejkolwiek platformy.

Odwołanie to coś, co sprawia, że jeden wyrenderowany artefakt wskazuje na inny. Zapisuje się je we własnym słownictwie danego dostawcy: jako adres wewnętrzny klastra w helm, nazwę usługi w compose, interpolację w terraform, wartość importowaną w cloudformation. Odwołanie jest inne w przypadku każdego dostawcy, ponieważ każda platforma rozwiązuje odwołania na swój sposób.

🔴 Cel nigdy nie jest zapisywany w wyrenderowanym wyniku. Każdy dostawca wyprowadza własne nazwy, więc tożsamość nadana przez autora, przekazana platformie jako nazwa, jest błędna zawsze, gdy obie pisownie się różnią — a różnią się dokładnie w tych znakach, których alfabet celu nie dopuszcza. Tożsamość niezawierająca takiego znaku pozostaje niezmieniona i właśnie dlatego łatwo tu o błąd: pomyłka działa, dopóki ktoś nie nazwie komponentu z podkreśleniem lub wielką literą.

Odwołanie potrzebne konsumentowi publikuje zatem producent, ponieważ to Recipe producenta zna słownictwo własnego dostawcy — konsument może powiązać zupełnie innego dostawcę i nie potrafi zapisać odwołania dla platformy, dla której nie renderuje. Konsument odczytuje zwykły opublikowany ciąg znaków.

Przykładowa para

Recipe producenta publikuje adres; konsument odczytuje go z powrotem przez alias krawędzi.

# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.
# It publishes an in-cluster address built from the name that chart's own
# templates render their resources against.
spec:
capability: helm
source: ./charts/postgres
provides:
host: "{{ .context.rendered_name }}.svc.cluster.local"
port: "5432"
# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an
# authoring identity and stays in the documents. The uses block is keyed by the
# socket the catalog entity declares, then by the alias you choose for the edge.
spec:
components:
api:
type: core/compute/api-server
uses:
databases:
primary:
target: my_db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.
# The context keys an edge by its alias, so the socket does not reappear here.
spec:
capability: helm
valuesMapping: |
{
"db_host": "{{ .context.uses.primary.provides.host }}"
}

W przypadku wykresu dostarczonego przez autora w helm komponent o nazwie my_db renderuje swoje zasoby pod nazwą wydania my-zudb. Wykres producenta emituje więc Service, którego metadata.name to my-zudb, opublikowany host to my-zudb.svc.cluster.local, a konsument łączy się z istniejącym Service — niezależnie od tego, czy odczytuje wartość przez .context.uses.primary.provides.host, czy otrzymuje ją jako wstrzyknięte DB_HOST.

Zapisanie w tym miejscu {{ .context.uses.primary.target }} opublikowałoby zamiast tego my_db.svc.cluster.local. Ta wartość nie wygląda na błędną: to tożsamość zapisana przez programistę, dokładnie w jego pisowni. Po prostu nie nazywa żadnego Service i nic w kompilacji o tym nie informuje.

Dwa klucze jako para

Żaden z kluczy nie jest zrozumiały sam w sobie, ponieważ każdy definiuje to, czym nie jest drugi.

KluczCo nazywa
{{ .context.instance_id }}Tożsamość węzła oraz nazwa zasobów zbudowanych dla tego węzła, dla których żaden provider nie wyprowadza nazwy — zestawu artefaktów umieszczonego na podstawie bloku artifacts: oraz workloadu syntetyzowanego z bloku workload: przez providera, który nazywa go według tożsamości, jak robi to compose. Zawsze obecny.
{{ .context.rendered_name }}Nazwa, którą powiązany provider wyprowadza dla zasobów renderowanych dla tego węzła — dla źródła dostarczonego przez autora jest to nazwa, według której własne dostarczone szablony renderują swoje zasoby, na przykład nazwa release odczytywana przez chart; dla syntetyzowanego przez niego workload: jest to nazwa nadawana tym zasobom tam, gdzie nazywa je według własnej nazwy, a nie tożsamości, jak robi to helm. Obecny tylko tam, gdzie dany provider ją wyprowadza. We własnych szablonach dołączenia encji Feature jest to nazwa komponentu hosta — zob. niżej.

Podział wynika z tego, gdzie nazwa musi być użyteczna. Chart lub moduł dostarczony przez autora ma szablony, a te szablony nazywają swoje zasoby według tożsamości, jaką przekaże im platforma — dlatego nazwa musi być tą, której użyje platforma, zapisaną w jej własnym alfabecie. Syntetyzowany workload nie ma szablonów autora, ale jego zasoby nadal muszą nosić nazwy akceptowane przez platformę: provider, którego nazwy dopuszczają wszystko, co może zawierać nazwa autorska, nazywa je według tożsamości, a provider, którego nazwy tego nie dopuszczają, nazywa je według wyprowadzonej nazwy — i zgłasza tę nazwę tutaj, aby nigdy nie trzeba było jej przewidywać.

Węzeł deklarujący zarówno dostarczone źródło, jak i workload: emituje oba rodzaje wyjścia jednocześnie i nie potrzebuje trzeciego klucza. W helm oba są nazywane według jednej nazwy release, więc rendered_name obsługuje każdy z nich: własne zasoby chartu noszą ją niezależnie od tego, jak składają ją jego szablony, a każdy syntetyzowany Service to <rendered_name>-<service key>. W providerze, który nazywa syntetyzowany workload według tożsamości, zasoby tego workloadu należy nazywać za pomocą instance_id, a zasoby dostarczonego wyjścia — nazwą, którą provider dla niego zgłasza.

To alfabety sprawiają, że oba klucze w ogóle mogą się różnić. Autorska nazwa komponentu może zawierać podkreślenie lub wielką literę; nazwa release chartu nie może, a zamiast sprowadzać taki znak do podobnego — co pozwoliłoby dwóm rozróżnialnym komponentom trafić pod jedną nazwę w klastrze — wyprowadzenie zapisuje go jawnie. Alfabet i limit długości tego providera opisuje ../providers/helm.md, „How the release name is derived”.

Które dostawcy zgłaszają nazwę i dlaczego pozostali tego nie robią

helm zgłasza jedną: nazwę wydania. Pobrany chart odczytuje ją jako .Release.Name i zwykle nazywa od niej swoje zasoby, a dostawca również nazywa od niej każdy zasób, który syntetyzuje dla komponentu — kontroler samą nazwą wydania, a każdy Service jako <release name>-<service key>. Adres publikowany dla dowolnego z tych rodzajów wyjścia jest więc budowany z rendered_name. Dla węzła, który umieszcza wyłącznie zestaw artefaktów, nie zgłasza żadnej: nazwy w tym zestawie są tymi, które zapisał jego autor.

# A synthesized helm Recipe publishing the address of the Service its workload
# declares under the key `default`.
spec:
capability: helm
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: "valkey/valkey:8"
ports:
redis: 6379
services:
default:
type: ClusterIP
ports:
redis: 6379
provides:
host: "{{ .context.rendered_name }}-default"
port: "6379"

Komponent o nazwie cache publikuje cache-default, a komponent o nazwie my_cache publikuje my-zucache-default — w każdym przypadku jest to nazwa obiektu Service emitowanego przez kompilację.

Pozostałe cztery nie zgłaszają żadnej, a powody nie są takie same. Żaden z nich nie jest dostawcą oczekującym na obsługę — w każdym przypadku albo nie ma pochodnej nazwy do zgłoszenia, albo potrzebna nazwa jest już dostępna w inny sposób.

  • cloudformation i compose — nazwy zostały napisane przez autora albo tożsamość jest nazwą. W encji Recipe dla cloudformation autor określa logiczne identyfikatory zasobów, a dostawca odczytuje je dokładnie tak, jak zostały zapisane; dostarczony plik compose sam nazywa swoje usługi, a dostawca scala i etykietuje ten plik, niczego w nim nie przemianowując. Obiekt workload syntetyzowany przez compose otrzymuje nazwę od tożsamości węzła, którą plik compose przyjmuje w zapisanej postaci, więc {{ .context.instance_id }} jest tą nazwą. Nie ma żadnego wyprowadzenia do zgłoszenia, a nazwy są tymi, które widnieją we własnych dokumentach autora. Ta nazwa to główna usługa obiektu workload, ta, do której dociera usługa równorzędna; usługa sidecar lub init, którą ten obiekt zawiera, otrzymuje nazwę od tej samej tożsamości i nazwy kontenera, połączonych przez --, jak opisano w Jak nazywana jest usługa sidecar lub init.

  • terraform — nazwa jest funkcją miejsca, w którym umieszczono pliki. Blok module kontrybutora otrzymuje nazwę od katalogu wyjściowego, do którego zapisano jego konfigurację, a ten jest ustalany podczas składania plików granicy, a nie podczas renderowania węzła. W chwili uruchomienia szablonów encji Recipe ta pozycja jeszcze nie istnieje.

  • helm-chart — wyprowadzana przez niego nazwa jest własnym adresem umieszczonego chartu, a to coś innego niż nazwa, względem której renderują się szablony tego chartu. Ten dostawca ustawia pole name dołączonego chartu na zakodowaną tożsamość tego, co go wniosło; jest to również alias, pod którym chart nadrzędny wiąże ten podchart, i klucz, w którego zakresie znajdują się jego wartości. Dla komponentu tę tożsamość niesie {{ .context.instance_id }}, więc nazwa umieszczonego chartu jest już dostępna pod kluczem, który mówi, czym ona jest. Nazwą, względem której renderują się własne szablony dołączonego chartu, jest nazwa wydania, którą dostarcza wydanie chartu nadrzędnego w czasie instalacji, a nie ten dostawca — nie ma więc tu takiej nazwy, którą ten klucz mógłby zgłosić. Zob. ../providers/helm-chart.md, „The chart name the umbrella owns”.

Odczyt klucza tam, gdzie żadna nazwa nie jest zgłaszana

Odczyt {{ .context.rendered_name }} w węźle, którego dostawca nie zgłasza takiej nazwy, zatrzymuje budowanie, a diagnostyka wskazuje, który klucz należy zapisać zamiast niego. Nie jest renderowana pusta wartość: adres krótszy o jeden segment to błędny artefakt, który się wdraża, a to gorsze niż budowanie, które się zatrzymuje.

To, jakie rozwiązanie proponuje zatrzymanie, zależy od węzła, a nie od miejsca, w którym zapisano odwołanie:

  • Węzeł, który nie dostarcza własnego źródła, pod dostawcą niezgłaszającym dla niego nazwy, ma zasoby nazwane według swojej tożsamości, więc zatrzymanie wskazuje {{ .context.instance_id }} — istnieje poprawna wartość i komunikat to mówi.
  • Węzeł, który dostarcza źródło, pod dostawcą niewyprowadzającym dla niego nazwy, nie ma zamiennika. Zatrzymanie to stwierdza, zamiast go proponować, ponieważ odesłanie do tożsamości nazwałoby tu zasoby, których węzeł nie zawiera.

Odmowa obejmuje provides: i każdy inny szablon, który Recipe zapisuje bezpośrednio — jego valuesMapping:, treść workload:, każdy wpis artifacts: oraz with: i when: każdego kroku potoku.

🔴 Obie formy importu są poza jej zakresem. Wpis valuesMapping:, workload: lub artifacts: dostarczony przez $import: — niezależnie od tego, czy import wskazuje plik lokalny, czy wpis biblioteki — nie zawiera żadnego tekstu w encji Recipe, dopóki renderowanie go nie rozwiąże, więc odwołanie do tego klucza wewnątrz takiej treści nie jest sprawdzane. Renderuje ono nazwę zgłaszaną przez dostawcę importującego węzła, jeśli ten dostawca ją zgłasza, a pustą wartość zamiast zatrzymania, jeśli nie zgłasza żadnej. Importowana treść może więc odczytywać klucz tylko wtedy, gdy każda encja Recipe, która ją importuje, wiąże dostawcę zgłaszającego nazwę — np. wpis biblioteki napisany dla encji Recipes helm, które pobierają chart, i informujący o tym w swoim opisie. Treść przeznaczona dla importujących, których dostawca może nie zgłaszać nazwy, przyjmuje nazwę zamiast tego przez wartość ustawianą przez importującą encję Recipe.

Wpisy locals: encji Recipe w ogóle nie odczytują tego klucza. Zmienna lokalna współdzieli kontekst z szablonem source: encji Recipe, a to, czy węzeł dostarcza źródło, jest jednym z czynników, od których zależy nazwa, dlatego nazwa nie jest tam udostępniana. Odwołanie do {{ .context.rendered_name }} w zmiennej lokalnej zatrzymuje więc budowanie niezależnie od tego, co zgłasza dostawca, z diagnostyką dla odwołania, którego kontekst renderowania nie definiuje (E0060), wymieniającą .context.instance_id jako jedyny klucz, jaki .context tam udostępnia. Klucz należy odczytywać we wpisie provides: lub w szablonie bezpośrednim, który go potrzebuje.

Własne szablony dołączenia encji Feature

W szablonach, które zapisuje FeatureRecipe dołączenia encji Feature — jej locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, każdy wpis artifacts: oraz with: i when: każdego kroku potoku — {{ .context.rendered_name }} jest nazwą komponentu-hosta: tą, którą własny dostawca hosta zgłasza dla zasobów renderowanych dla hosta, czyli wartością, którą odczytuje własna encja Recipe hosta. Tworzy parę z {{ .context.instance_id }}, który w tych szablonach jest tożsamością komponentu-hosta; samo dołączenie to .attachment_name. Dołączenie zapisane na jednym z połączeń komponentu odczytuje nazwę komponentu konsumującego, ponieważ to on jest jego hostem.

To z tego klucza należy budować nazwy własnych zasobów dołączenia. FeatureRecipe, która nazywa obiekt Secret, trasę lub politykę od komponentu, do którego jest dołączona, potrzebuje nazwy akceptowanej przez platformę, a tożsamość hosta w zapisanej postaci nie jest taką nazwą, gdy zawiera podkreślenie lub wielką literę. W helm komponent o nazwie my_db zgłasza my-zudb, więc Secret o nazwie {{ .context.rendered_name }}-{{ .attachment_name }} dla dołączenia root renderuje się jako my-zudb-root, podczas gdy {{ .context.instance_id }} dałby my_db-root, który klaster odrzuca. Wartość pozostaje wartością hosta niezależnie od dostawcy, przez którego renderuje się dołączenie.

Klucz jest obecny wszędzie tam, gdzie dostawca hosta zgłasza nazwę — w helm dla hosta, którego Recipe dostarcza chart lub deklaruje workload: — i nieobecny tam, gdzie żadnej nie zgłasza: dla hosta umieszczającego wyłącznie zestaw artefaktów oraz dla hosta u każdego innego dostawcy. Odczytanie go w dołączeniu takiego hosta zatrzymuje budowanie z diagnostyką dla odwołania, którego kontekst renderowania nie definiuje (E0060), wymieniającą klucze, które .context tam definiuje. {{ .context.instance_id }} jest wśród nich i to od niego nazywane są własne zasoby takiego hosta, dlatego FeatureRecipe pisana dla hostów, które mogą nie zgłaszać nazwy, odczytuje zamiast tego tożsamość.

Odmowa obejmuje szablony, które FeatureRecipe zapisuje bezpośrednio, z wyjątkiem jej injectMapping:. injectMapping: oraz wpis valuesMapping:, workload: lub artifacts: dostarczany przez FeatureRecipe za pomocą $import: nie są sprawdzane: na hoście niezgłaszającym nazwy odwołanie w nich renderuje pustą wartość zamiast zatrzymania.

Gdy dołączenie dostarcza chart podany przez jego autora, szablony tego chartu renderują się celowo względem nazwy wydania komponentu-hosta: wyprowadzenie jej z dołączenia zmieniłoby nazwy zasobów, które autor chartu zadeklarował i mógł już wdrożyć. .attachment_name jest wartością, która odróżnia dwa dołączenia na jednym hoście — zob. ../providers/helm.md, „How the release name is derived”.

Nazwy wyprowadzane z dołączenia połączenia

Dołączenie, które niesie połączenie, jest dołączeniem komponentu konsumującego i nosi nazwę <alias>.<slot> — gpt.credential dla slotu credential połączenia zapisanego pod aliasem gpt (zob. wpis połączenia w encji Aggregate). Ta złożona nazwa jest wartością .attachment_name, względem której renderuje się jego FeatureRecipe, i zawiera kropkę.

Wynikają z niej dwa rodzaje nazw, które traktują kropkę różnie.

Nazwa składana przez FeatureRecipe zachowuje to, co zapisuje jej szablon. Realizacje poświadczeń z biblioteki standardowej nazywają swój zasób {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, więc poświadczenie na połączeniu gpt komponentu o nazwie router renderuje się jako zasób o nazwie router-gpt.credential, wraz z kropką, co jest prawidłową nazwą obiektu Kubernetes. Kropka przetrwa w nazwie tego rodzaju dokładnie wtedy, gdy zachowa ją szablon.

Nazwa wyprowadzana przez build z tożsamości dołączenia zapisuje kropkę słownie. Etykiety tożsamości i emitowany plik są składane z komponentu hosta i nazwy dołączenia za pomocą tego samego kodowania, przez które przechodzi każda nazwa wyprowadzana z tożsamości, a kodowanie to zapisuje kropkę jako zd, a wielką literę jako sekwencję ucieczki jej punktu kodowego, ponieważ tożsamość służy zarówno jako nazwa zasobu, jak i etykieta, a nazwa Service nie dopuszcza żadnego z tych znaków: połączenie zapisane pod aliasem gptPro dałoby cfr--router--gpt-zx000050ro-zdcredential. Powyższy zasób otrzymuje etykietę aggrega.ai/component-id: cfr--router--gpt-zdcredential (podobnie app.kubernetes.io/name), a w providerze helm jest emitowany jako router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Zob. Konwencje nazewnictwa, „Separator nie trafia do nazwy”, aby dowiedzieć się, dlaczego kropka jest zapisywana słownie, a nie zastępowana.