İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Temelinin Recipe'si tarafından sunulan yayımlanmış bir sarmalayıcı

Bu örnek tek bir şey öğretir: başka bir Component’i extends ile genişleten bir Component, o temelin tüm veri sözleşmesini devralır; bu nedenle temel için yazılmış her Recipe, genişleten Component’i zaten uygular. Dolayısıyla standart kütüphanedeki bir bileşenin özelleştirilmiş bir varyantını yayımlamanın maliyeti bir katalog varlığı ve bir Manifest satırıdır; kendine ait bir Recipe gerekmez ve temelde hiçbir değişiklik yapılmaz.

Buradaki sarmalayıcı example/gateway/nginx-reviewed’dir. Katalogda, genişlettiği bileşen olan core/gateway/nginx’in yanında gelir.

Sarmalayıcının ekledikleri ve devraldıkları

Sarmalayıcının yazılmış yüzeyinin tamamı meta veri ile bir sokettir:

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited, genişleten bir Component’in bir schema: bloğu yerine yazdığı sabit işarettir. Üç veri sütununun (values, infra ve provides) temele ait olduğunu, tam olarak temelin yazdığı biçimde olduğunu belirtir. Sarmalayıcı kendine ait hiçbir sütun anahtarı bildirmez ve bildiremez: sözleşme, bir zincirin her derinliğinde temele aittir.

Sarmalayıcının değinmediği her şeyi devralır. aggrega inspect example/gateway/nginx-reviewed --resolved birleştirilmiş varlığı gösterir ve içinde dikkatle okunmaya değer iki şey vardır:

  • Üç uses soketi, bir değil: upstream ve guard (temelinkiler; upstream, component.aggrega.ai/type=server seçer) ve reviewed_upstream (sarmalayıcınınki). Genişletme bir soket ekler; kümeyi değiştirmez.
  • Temelin üç sütunu, birebir: values.upstream_path, infra.port / engine_version / compute / overrides ve provides.host / port / protocol, her biri temelin kendi açıklamalarıyla.

Tüketen bir Aggregate’in yazdıkları

aggregate-reviewed.yaml, bir veritabanı konsolunun önünde duran iki ağ geçidi katmanını sarmalayıcı olarak bildirir:

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

Dikkat edilmesi gereken anahtar upstream_path’tir. core/gateway/nginx’in values sütununda bildirilir ve sarmalayıcının dosyasında hiçbir yerde geçmez; yine de bir yazar onu bir sarmalayıcı örneğine yazar ve değer, işlenen ağ geçidi yapılandırmasına ulaşır. Sütunları bütünüyle devralmanın pratikteki anlamı budur.

Manifest diğer yarıdır ve tür başına bir satırdır:

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

Her iki ağ geçidi satırı da aynı Recipe’yi adlandırır. compose/nginx, implements: core/gateway/nginx:1.0.0 bildirir ve bir temeli adlandıran Recipe, o temeli genişleten her Component’in uygulamasıdır; bu nedenle sarmalayıcı ona hiç değişmeden hizmet eder. Burada iki olgu aynı anda geçerlidir ve birbirinden ayrıdır:

  • Recipe eşleşir. Sarmalayıcının kendi türünü uygulayan bir Recipe yoktur ve gerekmez.
  • Eşleme yine de gereklidir. Recipe seçimi tam eşleme anahtarına göre yapılır; bu nedenle sarmalayıcının kendi type girdisine ihtiyacı vardır; temelinkini devralmaz. Kendine ait girdisi olmayan bir sarmalayıcı örneği, temeli eşlenmiş olsa bile eşlenmemiş örnek tanılamasıyla durur.

Örneği oluşturun

Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.

Örneği, adını taşıyan yeni bir klasöre yazın:

Terminal window
aggrega scaffold --example extends-wrapper

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd extends-wrapper

Derleme

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

İşlenen çıktı ve kilit dosyası üretilir, birlikte gönderilmez: bu örnek girdilerini depoya işler ve geri kalan her şeyi yeniden üretir. --auto-pull, kilit dosyasını derleme sırasında çözümler; önceden bir kez aggrega pull --release release-reviewed.yaml çalıştırmak aynı işi yapar ve sonraki derlemelerin hiç bayrak olmadan çalışmasını sağlar.

Hem sarmalayıcı hem de genişlettiği temel, paylaşılan katalogda bulunur; bu katalog .aggrega-config.yaml dosyasının bildirdiği varsayılan kayıt defteri olan hub.aggrega.ai’den çözümlenir. Derleme komutunun --catalog bayrağına ihtiyacı yoktur, bu dizinden çalıştırılan aggrega inspect’in de yoktur.

Sarmalayıcı core/gateway/nginx’i genişlettiği için pull işlemi onu getirir: bir temel, onu genişleten her şeyin bir bağımlılığıdır; bu nedenle pull işlemi sarmalayıcının extends: alanını izler ve Manifest temeli adlandırsın ya da adlandırmasın, temeli kilit dosyasına sabitler. Buradaki Manifest temeli başka bir nedenle eşler — aşağıdaki kontrol sürümü temelin kendisinin bir örneğini bildirir.

İşlenen dist/compose/docker-compose.yaml kanıtı taşır:

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

Kanıtladıkları sırayla üç okuma:

  • aggrega.ai/recipe-uri: nginx:1.0.0: bu servise temelin Recipe’si biçim verdi. Bir sarmalayıcı örneğindeki köken etiketi temelin Recipe’sini adlandırır, çünkü onu işleyen Recipe odur.
  • location /api/: yalnızca temelin bildirdiği bir anahtar olan values.upstream_path, bir sarmalayıcı örneğine yazılmış ve işlenmiş.
  • proxy_pass http://internal:8081: reviewed_upstream kenarı çözümlendi. Hedefin provides.host ve provides.port değerleri, temelin Recipe’sinin okuduğu teslim anahtarları altında enjeksiyon bağlamına ulaştı; böylece sarmalayıcının eklediği bir soket, onu hiç duymamış bir Recipe’den geçer.

Derlemenin çözümlediği kilit dosyası aynı olguyu çözümleyicinin tarafından kaydeder: tek bir özette tek bir compose/nginx:1.0.0 girdisi, her iki eşleme anahtarından da başvurulan: temelin türü ve sarmalayıcınınki.

Sarmalayıcının etiketleri ve ek açıklamaları çözümlenmiş kenarla birlikte taşınır: tüketen bir düğümün işleme bağlamı her hedefin provides, labels ve ek açıklamalarını taşır; böylece edge’in bağlamı, upstream’inin audit-tier=reviewed olduğunu ve onu kimin incelediğini bilir. Bunlardan herhangi birinin işlenen bir yapıtta görünüp görünmeyeceği Recipe’nin seçimidir; bu etiketler ve ek açıklamalar, seçicilerin ve politikanın okuması için bileşen kimliğidir, derleyicinin bastığı çıktı değildir.

Bir yapay zekâ asistanıyla

Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.

Yalnızca Aggrega araçlarını kullanın ve kendiniz klasör oluşturmayın. Çalışma alanı klasöründe henüz bir `extends-wrapper` klasörü yoksa `scaffold` aracını `example` değeri `extends-wrapper` olacak şekilde ve `dir` olmadan bir kez çağırın: araç örneği yeni bir `extends-wrapper` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `extends-wrapper`, `release` değeri `release-reviewed.yaml`, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `extends-wrapper/dist/` altındadır.

Kontrol: eklenen etiket ne işe yarar

aggregate-unreviewed.yaml, tek bir düzenlemeyle aggregate-reviewed.yaml’dir: iç katman, sarmalayıcı yerine yalın core/gateway/nginx temeli olarak bildirilir; ve başarısız olması beklenir:

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

Durma, dersin kendisidir. Temel kendi upstream soketini karşılar ( component.aggrega.ai/type=server’dır ve iç katman o sokete tam olarak aynı şekilde bağlanır), ancak hiçbir audit-tier etiketi taşımaz; bu nedenle sarmalayıcının daha katı soketi onu reddeder. Sarmalayıcının eklediği etiket, bir örneğini seçilebilir kılan şeydir ve bunun görüldüğü yer seçicidir.

Bilinmeye değer iki durma daha vardır ve ikisi de şemanın işini yapmasıdır:

  • extends bildiren ve schema: altında sütun içeriği yazan bir Component, belge yüklenirken kısıtı adlandırarak reddedilir. schema:’yı tamamen atlayan da reddedilir. Kabul edilen tek biçim schema: inherited’dır ve bir okuyucunun devralınmış bir sütun bloğunu unutulmuş bir blokla asla karıştıramaması için ima edilmek yerine yazılır.
  • Temelin bildirmediği bir values anahtarı, bir sarmalayıcı örneğinde yazıldığı yolda reddedilir, çünkü uygulanan sözleşme temelinkidir.

Bu neden yararlıdır

Standart kütüphanedeki bir bileşen için incelenmiş bir biçimde karar kılmış bir kuruluşun, onu saklayacağı bir yere ihtiyacı vardır. Düz metin olarak saklandığında etiketler, ek açıklamalar ve soketler onlara ihtiyaç duyan her Aggregate’te yeniden yazılır ve bu sırada birbirinden uzaklaşır. Temeli genişleten bir Component olarak yayımlandığında biçim, adı olan, sürümlenmiş ve incelenebilir bir katalog varlığına dönüşür: onu tüketen bir ekip type: example/gateway/nginx-reviewed ve bir Manifest satırı yazar; temelin tüm sözleşmesini, ona karşı zaten yazılmış her Recipe ile birlikte, temelin desteklediği her hedefte devralır.

Bunu işe yarar kılan, sarmalayıcının maliyetidir: yapı ve meta veri ekler, başka hiçbir şey eklemez. Hiçbir sütun bildirmediği için sarmalayıcının bir örneği ile temelin bir örneği tek bir sözleşmeye göre doğrulanır ve temel için yazılmış bir Recipe, onun bir özelleştirmesiyle asla şaşırtılamaz.