Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Thành phần đầu vào của Recipe — ba loại đầu vào, Workload, artifact

Một Recipe tạo ra các tệp manifest cho provider đích của nó. Chương này trình bày cách các Recipes kết hợp đầu ra từ ba loại đầu vào trực giao — sourced, synthesized và artifacts —, cấu trúc của từng loại đầu vào, và provider nào tạo ra đầu ra nào. Vai trò khái niệm của thực thể Recipe (template dịch do Ops viết, ánh xạ ý định của nhà phát triển sang một provider vật lý duy nhất) nằm trong 04-entity-taxonomy.md; bề mặt authoring của Recipe ở cấp từ khóa nằm trong ../language-reference/entities/recipe.md.

Lý do

Công cụ render gốc của mỗi provider — Helm, Docker Compose — đã biết cách render các manifest gốc của provider. Nhiệm vụ của một Recipe là khai báo NHỮNG GÌ các manifest đó cần nêu: image container nào, cổng nào, biến môi trường nào, volume nào, dịch vụ nào, giới hạn tài nguyên nào.

Một Recipe phải biểu đạt nhiều hơn những gì một tập khóa cố định (ví dụ image, environment, ports, replicas) được ánh xạ lên một Deployment và một Service có thể mang, trong đó có:

  • resources (request/limit CPU/bộ nhớ)
  • Probe liveness, readiness hoặc startup
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • Pod nhiều container, sidecar
  • Tài nguyên ConfigMap / Secret / PVC / CRD
  • Service không phải ClusterIP (LoadBalancer, NodePort, Headless)

Lớp trừu tượng cần mô tả đầy đủ hình dạng của một khối lượng công việc, chứ không phải một tập khóa cố định. Ba loại đầu vào được mô tả dưới đây chính là lớp trừu tượng đó: một Recipe kết hợp đầu ra của mình theo kiểu cộng dồn từ một chart hoặc module được tải từ bên ngoài (source:), một đặc tả Workload trừu tượng mà provider tổng hợp thành các manifest gốc của provider (workload:), và các manifest gốc của provider dựa trên template mà Recipe phát ra trực tiếp (artifacts:).

Ba loại đầu vào

Kết hợp bằng cộng dồn

Có ba cách để tạo ra các tệp manifest gốc của provider từ một Recipe, và chúng kết hợp bằng cách cộng dồn thay vì loại trừ lẫn nhau:

  1. source: — một artifact được tải từ bên ngoài (Helm chart, tệp compose) mà provider render theo cách gốc, với valuesMapping: cung cấp các giá trị overlay.
  2. workload: — một đặc tả Workload trừu tượng (loại do nền tảng sở hữu) mà provider tổng hợp thành các manifest gốc của provider. Trường này chấp nhận một block scalar YAML inline hoặc một $import: trỏ đến một tệp cục bộ duy nhất hay một mục thư viện; việc điều phối dựa trên hình dạng nội dung.
  3. artifacts: — một map gồm các manifest gốc của provider, inline hoặc được tải bằng $import:, được xử lý như template Go dựa trên toàn bộ ngữ cảnh pillar. Mỗi mục có thể được viết inline (giá trị của mục là một block scalar) hoặc qua $import: trỏ đến một tệp duy nhất hay nội dung thư viện.

Cả ba đều tạo ra các tệp mà trình biên dịch phát ra vào thư mục đầu ra của boundary. Cả ba có thể cùng tồn tại trong một Recipe, tuân theo các quy tắc xác thực bên dưới. Ngữ nghĩa hợp nhất chỉ ở cấp cao nhất: mỗi loại đầu vào tạo ra các tệp hoàn chỉnh; các tệp được phát ra cạnh nhau; xung đột tên tệp đầu ra là lỗi nghiêm trọng.

Tên chế độ mang tính mô tả

Ba “chế độ” là từ vựng mô tả dùng cho tài liệu và chẩn đoán. Tác giả Recipe không khai báo chế độ; họ viết các từ khóa mình cần. Một Recipe được đặc trưng bởi đầu vào chiếm ưu thế của nó:

(Các) từ khóa chiếm ưu thếTên chế độ mô tả
source: + valuesMapping: (không có workload:, không có artifact)sourced
workload: (không có source:, không có artifact)synthesized
artifacts: (không có source:, không có workload:)artifacts-only (gọi không chính thức: “inline”)
Bất kỳ tổ hợp nào gồm hai loại trở lênđược mô tả rõ ràng (ví dụ “sourced kèm artifacts”, “synthesized kèm artifacts”)

Không có từ khóa nào tên là mode: và cũng không có enum. Chế độ là một thuộc tính phát sinh từ việc những đầu vào nào hiện diện.

Tổng quan hình dạng của Recipe

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

Mọi trường ở trên đều được schema của Recipe chấp nhận, và trình biên dịch tiêu thụ cả ba loại đầu vào — render sourced, tổng hợp Workload và phát ra artifacts. Điểm khác biệt là mức hỗ trợ theo từng provider — provider nào render loại đầu vào nào — được ghi lại trong ma trận khả năng của Provider ở cuối chương này.

Quy tắc xác thực khi tải

Schema của Recipe và bước xác thực khi tải áp đặt các quy tắc kết hợp sau:

  1. valuesMapping: yêu cầu source:. Không có source: để overlay thì không có gì nhận các giá trị đã ánh xạ. Một Recipe có valuesMapping: mà không có source: là lỗi khi tải. (Một source: không có valuesMapping: được phép — chart hoặc module được render với các giá trị mặc định của chính nó.)
  2. workload: chấp nhận một nguồn — inline hoặc $import:, không phải cả hai. Một Recipe chỉ định Workload hoặc dưới dạng block scalar inline, hoặc dưới dạng $import: trỏ đến một tệp duy nhất. Dạng $import: là một nguồn duy nhất theo bộ từ vựng nhập tệp thống nhất; việc hợp nhất nhiều nguồn không được hỗ trợ ở workload:. Việc điều phối sai dạng là lỗi khi tải.
  3. workload: yêu cầu một provider có khả năng tổng hợp. Hỗ trợ tổng hợp là thuộc tính của chính provider, không phải của bất kỳ trường được khai báo nào. Một Recipe workload: gắn với một provider không thể tổng hợp sẽ bị từ chối khi node được render — thông qua cổng kiểm tra khả năng của provider (xem ma trận khả năng của Provider) — kèm một chẩn đoán rõ ràng. Danh mục thư viện chuẩn khai báo workloadSchema trên các provider có khả năng tổng hợp theo quy ước, như hợp đồng dịch được ghi chép, nhưng cổng kiểm tra dựa trên khả năng do chính provider báo cáo chứ không dựa trên sự hiện diện của trường đó.
  4. Phải có ít nhất một loại đầu vào. Một Recipe không có source:+valuesMapping:, workload: hay artifacts: sẽ không tạo ra đầu ra nào và là lỗi khi tải.
  5. Các mục artifact inline và $import: có thể cùng tồn tại. Một Recipe có thể khai báo một số mục artifacts: inline và những mục khác qua chỉ thị $import: cho từng mục. Khóa của mỗi mục đặt tên cho đầu ra của chính nó, nên các mục của hai dạng không bao giờ xung đột với nhau (xem Điều gì đặt tên cho mỗi tệp đầu ra).
  6. Xung đột tên tệp giữa các loại đầu vào là lỗi khi render. Nếu hai loại đầu vào của một Recipe — đầu ra render từ nguồn, đầu ra tổng hợp từ khối lượng công việc hoặc đầu ra phát ra từ artifact — tạo ra một tệp trùng tên, trình biên dịch phát ra một lỗi nghiêm trọng xác định mọi bên đóng góp. Bước kiểm tra này chạy sau khi dịch Workload, nên nó diễn ra khi render chứ không phải khi tải.

Loại Workload

Quyền sở hữu và vị trí

Workload là một loại do nền tảng sở hữu tại apiVersion: aggrega.ai/v1beta1. Khai báo JSON Schema 2020-12 của nó được nhúng vào tệp nhị phân của trình biên dịch lúc build; tác giả danh mục không chỉnh sửa schema của Workload, và cũng không viết các tệp YAML Workload độc lập làm thực thể danh mục. Ngữ pháp Workload được tiêu thụ bên trong trường workload: của một Recipe hoặc FeatureRecipe (inline, hoặc qua $import: trỏ đến một tệp duy nhất hay một mục WorkloadLibrary) và không ở đâu khác.

Workload là một loại của nền tảng và một khái niệm của trình biên dịch, không phải một thực thể riêng trong Phân loại thực thể. Recipe là thực thể authoring; Workload là hình dạng mà đầu vào được tổng hợp của Recipe mang.

Một Workload cho mỗi Recipe

Một Recipe khai báo tối đa một workload:. Workload đại diện cho đơn vị tính toán duy nhất gắn với Component mà Recipe này hiện thực. Tương tự, một FeatureRecipe khai báo tối đa một workload: của riêng nó — một đơn vị tính toán do Feature sở hữu, được tổng hợp qua cùng loại Workload — xem FeatureRecipe. Các trường hợp sử dụng cần thêm khối lượng công việc phụ được biểu đạt qua:

  • artifacts: — các manifest bổ sung bên cạnh khối lượng công việc, trong cùng Recipe (inline hoặc qua $import: cho từng mục).
  • Features có Tạo tài nguyên — các khối lượng công việc phụ xuyên suốt (ví dụ một sidecar sao lưu gắn vào cơ sở dữ liệu) được khai báo thành các thực thể danh mục riêng, trong đó FeatureRecipe tổng hợp workload: của riêng nó (hoặc render qua source: / artifacts:). Xem 14-extensibility.md về Tạo tài nguyên của FeatureRecipe.

Điều này giữ nguyên mô hình một đơn vị tính toán cho mỗi tác giả: một Recipe tổng hợp khối lượng công việc của Component; một FeatureRecipe tổng hợp khối lượng công việc của riêng nó.

Toàn bộ bề mặt

Tập trường của Workload lớn và không ngừng tăng. Thay vì nhắc lại ở đây, nơi một bản sao sẽ tụt lại sau hợp đồng mà không có gì báo hiệu điều đó, chương này trỏ đến hai bề mặt chứa toàn bộ tập trường:

  • Tài liệu tham chiếu schema Workload được tạo tự động — mọi trường, kiểu, giá trị mặc định và ràng buộc của nó, được tạo từ JSON Schema đã công bố và được đối chiếu với schema đó ở mỗi lần build, nên không thể mô tả một hình dạng mà trình biên dịch không chấp nhận.
  • Trang authoring của Workload — hướng dẫn authoring ở cấp trường: mỗi trường có ý nghĩa gì, mỗi provider render nó thành gì và những tổ hợp nào bị build từ chối.

Khai báo JSON Schema 2020-12 của Workload là nguồn có thẩm quyền và được phát hành nhúng trong tệp nhị phân của trình biên dịch. Các provider helm và compose tổng hợp workload: của một Recipe, dù inline hay tải bằng $import:; xem ma trận khả năng của Provider để biết mức hỗ trợ theo từng provider.

Tích hợp secret với featuresSchema

Khối containers.<name>.attachments của Workload tham chiếu đến các slot được khai báo bởi featuresSchema của Component; nó không khai báo slot mới. Xem ../language-reference/entities/component.md về bề mặt authoring của featuresSchema.

Hợp đồng xác thực:

  • Mọi giá trị attachments.<KEY>.from phải khớp với một tên slot được khai báo trong featuresSchema của Component — hoặc, với một mục nêu tên một kết nối bằng connection: <alias>, khớp với một slot mà socket của kết nối đó khai báo trong usesSchema.<socket>.featuresSchema. Một mục như vậy được viết lại thành tên mà liên kết của kết nối mang trên thành phần (<alias>.<slot>) trước khi bất kỳ quy tắc nào trong số này chạy, nên mọi quy tắc bên dưới đọc nó giống như đọc một mục nêu tên slot của chính Component.
  • Cơ chế phân phối as: (env hoặc file) phải nằm trong danh sách cho phép của mảng inject: của slot đó.
  • Các slot được đánh dấu inject: [] (hộp đen) trong featuresSchema của Component không được xuất hiện trong các khối attachments: của Workload — các slot đó được phân phối bởi cơ chế nội bộ của Recipe (ví dụ qua existingSecret của Helm), chứ không qua việc phơi bày trong Workload.

Ví dụ:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

Probe sức khỏe: ý định, không phải cơ chế

Probe của Kubernetes và healthcheck của Docker Compose có hình dạng khác nhau. Một hình dạng ý định trừu tượng duy nhất được dịch gọn gàng sang cả hai:

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Các Providers dịch mỗi ý định sang dạng gốc của mình:

Ý địnhHelm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

Việc phân giải cổng cho http: khi không có cổng tường minh sẽ lấy tên cổng đứng đầu theo thứ tự chữ cái mà container khai báo dưới containers.<name>.ports, trên cả hai đích. Một container không khai báo cổng có tên nào thì không thể mang probe HTTP, và build dừng lại, nêu tên probe đó.

Compose hạ cấp các probe HTTP/TCP thành lệnh shell healthcheck, và một dịch vụ compose chỉ mang một healthcheck: khi khai báo nhiều hơn một probe, chỉ một probe được dịch và một cảnh báo nêu tên các probe bị loại bỏ.

Các loại volume

Năm loại volume; không có loại kết hợp:

LoạiNgữ nghĩaK8s (helm)Compose
ephemeralTmpfs / emptyDir; mất đi cùng podemptyDir: { sizeLimit }mount tmpfs:, không mang kích thước (một cảnh báo báo cáo sizeLimit được viết)
configmapTệp cấu hình chỉ đọcTham chiếu volume ConfigMaptham chiếu configs: cấp dịch vụ đến một config cấp cao nhất mà artifacts: của Recipe khai báo
secretTệp secret chỉ đọcTham chiếu volume Secrettệp secret chỉ đọc được bind-mount
persistentMột PVC duy nhất; tồn tại qua các lần khởi động lại podTài nguyên PVC + volume.persistentVolumeClaimvolume có tên
persistentTemplatePVC cho mỗi bản sao; đi kèm form: statefulStatefulSet.volumeClaimTemplatesvolume có tên (bị hạ cấp; phát ra cảnh báo)

Compose không thể biểu đạt template cho từng bản sao. Khi persistentTemplate được dịch sang compose, nó bị hạ cấp thành một volume có tên duy nhất được mọi bản sao dùng chung, và một cảnh báo báo cáo việc hạ cấp. Một volume persistentTemplate yêu cầu form: stateful; khai báo nó trên bất kỳ dạng nào khác sẽ dừng build.

Phơi bày nhiều dịch vụ

Mỗi dịch vụ là một điểm phơi bày độc lập. Một mẫu phổ biến: một dịch vụ HTTP trên cổng 8080 (ClusterIP nội bộ) + một dịch vụ số liệu trên cổng 9090 (ClusterIP) + một endpoint quản trị trên cổng 9901 (LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

Mỗi dịch vụ trở thành một đối tượng Service Kubernetes riêng khi được render bằng provider helm, còn provider này sẽ dừng lại khi gặp một mục Loopback. Trong compose, các dịch vụ NodePort và LoadBalancer công bố cổng của chúng trên mọi giao diện host của dịch vụ compose, các dịch vụ Loopback chỉ trên địa chỉ loopback của host, còn các dịch vụ ClusterIP và Headless không công bố gì.

Tên dịch vụ trong đầu ra K8s được thêm tiền tố là instance_id của thành phần để đảm bảo tính duy nhất. Tên cổng phải khớp với tên cổng container được khai báo trong containers.<name>.ports.

Hợp đồng dịch phía Provider: workloadSchema

Một Plugin render cho provider (pluginType: provider) khai báo một spec.provider.workloadSchema — một khai báo JSON Schema 2020-12 ghi lại cách các trường Workload được dịch sang đầu ra gốc của provider đó. Đây là hợp đồng dịch tự mô tả. Xem ../language-reference/entities/plugin.md về bề mặt authoring của Plugin, bao gồm khối spec.provider.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

Trường workloadSchema truyền đạt ý định dịch tới tác giả danh mục và công cụ IDE. Nó là hợp đồng dịch được ghi chép, được khai báo theo quy ước trên các provider có tổng hợp — nhưng hỗ trợ tổng hợp do chính provider quyết định, không phải do sự hiện diện của trường này. Một Recipe nhắm, bằng workload:, tới một provider không thể tổng hợp sẽ bị từ chối khi node được render — thông qua cổng kiểm tra khả năng của provider — kèm một lỗi rõ ràng, bất kể provider có khai báo workloadSchema hay không.

Schema của Plugin khai báo spec.provider.workloadSchema — phần thân của nó được biên dịch thành JSON Schema 2020-12 khi Plugin được tải — và việc tiêu thụ workload: ở phía Recipe đã được phát hành. Hỗ trợ tổng hợp được thực thi lúc render bởi cổng kiểm tra khả năng của provider, dựa trên khả năng mà provider được gắn báo cáo; workloadSchema là hợp đồng được ghi chép mà danh mục thư viện chuẩn giữ đồng bộ với khả năng đó, chứ bản thân nó không phải đầu vào của cổng kiểm tra. Ngoài ra, aggrega validate, khi chạy trên toàn bộ danh mục, sớm phát hiện, trước khi build, một Recipe workload: gắn với một provider không tổng hợp, nếu danh mục chứa thực thể Plugin của provider đó.

Tài nguyên phụ trợ nằm ngoài Workload

Đặc tả Workload không có trường additionalResources, không có extras, không có khai báo inline ConfigMap/Secret/CRD. Workload chỉ mô hình hóa hình dạng khối lượng công việc: container, volume, dịch vụ, bản sao, lập lịch, ngữ cảnh bảo mật, service account — mọi thứ mô tả cách đơn vị tính toán duy nhất vận hành.

Tài nguyên phụ trợ có hai nơi hợp lệ bên ngoài Workload:

  1. Features + FeatureRecipes — cơ chế cho các mối quan tâm xuyên suốt. Một ServiceMonitor gắn vào “bất kỳ máy chủ nào có phơi bày số liệu” là core/prometheus-exporter dưới dạng một Feature. Tài nguyên định tuyến công bố một máy chủ tại một hostname cũng là một Feature, và dạng định tuyến quyết định là Feature nào: core/public-ingress khi đích đối soát một Ingress, core/http-route khi đích chạy Gateway API — mỗi cái được hiện thực bởi một FeatureRecipe mà Manifest chọn cho từng Release. Một NetworkPolicy được áp dụng trên mọi khối lượng công việc production là một Feature mà Release production gắn trên toàn bộ ranh giới. Các Features kết hợp theo cách trực giao và có thể được tái sử dụng giữa các Recipes. Xem 14-extensibility.md về Tạo tài nguyên của FeatureRecipe.
  2. artifacts: cấp Recipe — dành cho các tài nguyên thuộc về phần hiện thực của chính Recipe cụ thể này và không đáng để tạo một Feature. Một lần đăng ký CRD duy nhất mà Recipe cần. Một PodDisruptionBudget riêng của Recipe chỉ áp dụng khi Recipe này được dùng. Một ConfigMap mà Workload của Recipe tham chiếu. Mỗi mục là inline hoặc được tải bằng $import:; xem phần Cơ chế artifact bên dưới.

Ranh giới giữa Feature và artifact là một quy ước xã hội. Nếu một tài nguyên phụ trợ mang tính xuyên suốt (áp dụng cho nhiều Recipes, hoặc được gắn có điều kiện qua bộ chọn), thì nó là một Feature. Nếu nó gắn liền với riêng Recipe này (Recipe không thể làm việc của mình mà không phát ra tài nguyên đó), thì nó là một artifact. Tác giả lựa chọn dựa trên khả năng tái sử dụng và ngữ nghĩa gắn kết; trình biên dịch không kiểm soát lựa chọn đó.

Features và các artifact của Recipe cùng nhau bao quát các tài nguyên phụ trợ mà một Recipe cần.

Cơ chế artifact

Artifact inline và artifact tải từ tệp

Loại đầu vào artifacts phát các tệp manifest gốc của provider dựa trên template trực tiếp vào đầu ra của boundary, bên cạnh mọi đầu ra được render từ nguồn hoặc tổng hợp từ khối lượng công việc. Tác giả khai báo nó qua hai bề mặt:

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

Các đường dẫn $import: là tương đối so với thư mục của Recipe và phải nằm bên trong thư mục đó, vì mọi tệp mà một lần công bố Recipe mang theo đều được lấy từ thư mục đó — mỗi tệp mà một lần nhập nêu tên đều đi kèm với nó — còn một tệp nằm ngoài thì không. Một quy ước thường gặp đặt chúng trong thư mục con ./artifacts/, dù trình biên dịch không bắt buộc điều này. Khóa của map đặt tên cho từng tệp được phát ra — phần tiếp theo trình bày ý nghĩa của điều đó trong từng dạng trong ba dạng.

Mỗi mục (inline hoặc tải bằng $import:) được xử lý như template Go dựa trên toàn bộ ngữ cảnh template trước khi được phát ra vào thư mục đầu ra.

Điều gì đặt tên cho từng tệp đầu ra

Map được đánh khóa theo tên mục, và khóa đặt tên cho những gì mục phát ra trong mọi dạng authoring. Với một mục inline, khóa là tên tệp đầu ra, được dùng đúng như đã viết:

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

Tạo ra configmap-config.yaml và pdb.yaml. Khóa cố định tên tệp; tệp nằm ở đâu là quyết định của đích, và phần về việc phát ra theo từng provider bên dưới sẽ trình bày điều đó.

Với một mục $import: tệp, khóa cũng là tên tệp đầu ra. Tệp được nhập cung cấp nội dung; nó không cung cấp tên, nên tác giả muốn một tên tệp đầu ra cụ thể sẽ viết tên đó làm khóa:

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

Tạo ra .../monitor.yaml và .../netpol.yaml. Tệp được nhập của mục thứ hai có tên some-other-name.yaml, và tên đó không đến được đầu ra — khóa mới là thứ đến được. Do đó, hai mục nhập các tệp khác nhau tình cờ trùng tên, ./extras/shared.yaml và ./overrides/shared.yaml, là hai đầu ra riêng biệt, mỗi đầu ra được đặt tên theo khóa của chính nó.

Với một mục $import: thư viện, vốn kéo vào một gói tệp như một đơn vị, mục đó được mở rộng thành một đầu ra cho mỗi tệp trong gói, mỗi đầu ra lồng dưới khóa dưới dạng <key>/<filename>. Một khóa đặt tên cho nhiều tệp, nên riêng khóa không thể đặt tên cho chúng: nó là thư mục chứa các tệp của gói chứ không phải tên của bất kỳ tệp nào trong đó.

Vì mọi dạng đều đặt tên đầu ra theo khóa, khóa bị giới hạn ở bề mặt authoring trong phạm vi những gì một tên tệp duy nhất có thể là: một chữ cái hoặc chữ số đứng đầu, sau đó là chữ cái, chữ số, dấu chấm, dấu gạch ngang và dấu gạch dưới. Dấu chấm mang phần mở rộng mà bên tiêu thụ mong đợi, đó là điều khiến một khóa dùng trực tiếp được làm tên tệp; và bảng ký tự không chứa / cũng không có . đứng đầu, nên một khóa không bao giờ có thể tạo thành nhiều hơn một đoạn đường dẫn và không bao giờ có thể là đoạn thư mục cha. Một khóa nằm ngoài bảng ký tự sẽ không qua được bước xác thực envelope khi tải workspace, tại aggrega validate và trong chẩn đoán của trình soạn thảo.

Hai đầu ra artifacts: mang cùng tên tệp sẽ dừng build khi node được render, bất kể dạng nào đã tạo ra chúng. Hai mục của cùng một map artifacts: không bao giờ đặt tên cho cùng một đầu ra: một khóa là duy nhất trong một tài liệu và là một tên tệp duy nhất, nên tên đầu ra của một mục tệp đơn là khóa của nó, còn các đầu ra của một mục gói đều nằm dưới một thư mục được đặt tên theo khóa của nó. Do đó, đoạn đầu tiên của mọi đường dẫn được phát ra là khóa đã tạo ra nó, và các khóa khác nhau vẫn là các tên đầu ra khác nhau. Điều mà việc dừng này bao quát là trường hợp vượt qua các loại đầu vào — một tên tệp được hai loại trong số đó đóng góp, chẳng hạn một template của chart và một mục artifact cùng tạo ra servicemonitor.yaml — kèm một chẩn đoán nêu tên mọi nguồn gốc đóng góp.

Ngữ cảnh template cho artifact

Template artifact có quyền truy cập toàn bộ ngữ cảnh pillar:

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata — các pillar chuẩn của Aggrega được mô tả trong 06-data-taxonomy-and-composition.md.
  • .workload — đặc tả Workload đã được phân tích cho Recipe này (nếu có). Cho phép artifact tham chiếu các giá trị Workload mà không cần lặp lại, ví dụ một ServiceMonitor tham chiếu .workload.services.metrics.ports.prom.
  • .source — nội dung đã phân giải của trường source: (nếu có).

Artifact được đánh giá sau khi Workload được phân tích, nên .workload khả dụng khi có. Với các Recipes không có workload:, .workload là nil; một template cố gắng tham chiếu đến nó sẽ thất bại với một lỗi rõ ràng. Với các Recipes không có source:, .source là nil với cùng cách thất bại.

Bất biến tự chứa

Artifact phải tự chứa. Chúng chỉ có thể tham chiếu các đầu vào đã khai báo của Recipe: ngữ cảnh pillar, Workload của chính Recipe (khi có) và giá trị source: của chính Recipe. Chúng không thể tham chiếu:

  • Đầu ra của các Recipes khác trong cùng boundary.
  • Các tài nguyên Kubernetes có sẵn trong môi trường mà Recipe không khai báo.
  • Secret, ConfigMap hoặc các tài nguyên khác được giả định là tồn tại bên ngoài (trừ khi được tham chiếu qua một pillar đã khai báo).

Một artifact ConfigMap được volumes.*.configmap.source của Workload tham chiếu phải được phát ra bởi CHÍNH Recipe này (qua artifacts: tạo ra ConfigMap đó) hoặc bởi một Feature gắn vào node này. Phụ thuộc giữa các Recipe với nhau trong một boundary không được hỗ trợ.

Bất biến này giữ được khả năng tái sử dụng của Recipe: một Recipe có thể được đưa vào bất kỳ tổ hợp Aggregate + Release nào thỏa mãn hợp đồng pillar của nó, mà không có phụ thuộc ẩn.

Label nguồn gốc

Sau khi dịch, mọi tệp được phát ra đều mang thông tin nguồn gốc aggrega.ai/* trong metadata — dù nó được render từ nguồn, tổng hợp từ khối lượng công việc hay phát ra từ một template artifact. Mọi bề mặt phát ra đều đóng dấu thông tin này từ một tập builder dùng chung, nên cùng một tệp luôn mang cùng thông tin nguồn gốc bất kể loại đầu vào nào đã tạo ra nó. Tập này được chia theo việc một giá trị có thỏa mãn bộ ký tự của giá trị label Kubernetes hay không: các khóa an toàn cho label là label (có thể truy vấn); các khóa không an toàn với bộ ký tự — recipe-uri (chứa :), boundary-path (một đường dẫn lồng nhau chứa /) và sync-wave (dấu - đứng đầu của một wave âm) — là annotation, có giá trị không bị ràng buộc. Một giá trị định danh mà bản build không buộc tuân theo quy tắc label — tên aggregate, môi trường, tên nhà cung cấp, phiên bản của trình biên dịch và nhà cung cấp — là một label được viết ở dạng mà label chấp nhận, và khi dạng đó khác với giá trị, giá trị nguyên văn cũng là một annotation dưới cùng khóa đó (một Aggregate tên imported/flow được gắn label imported-flow và annotation imported/flow). Mọi tệp mang đầu ra của cùng một Recipe đều có chung thông tin nguồn gốc:

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

Cách chia này đồng nhất trên cả ba loại đầu vào. (Provider Compose không có khái niệm annotation và giá trị label của nó không bị ràng buộc, nên nó phát toàn bộ tập dưới dạng label của dịch vụ.) Xem 11-governance-and-compliance.md về việc đóng dấu nguồn gốc lúc biên dịch.

Vì một provider đóng dấu nguồn gốc ở nơi mà định dạng đầu ra của chính nó có chỗ chứa, một provider có định dạng không cung cấp chỗ như vậy cho một tệp nhất định sẽ phát tệp đó ra nguyên vẹn và thông báo điều đó. Compose là trường hợp cần biết: nơi chứa nguồn gốc của nó là khối labels: của một dịch vụ, nên một đoạn artifact compose chỉ đóng góp volumes:, configs: hoặc models: cấp cao nhất sẽ không mang nguồn gốc, và build phát ra cảnh báo “skipped provenance label injection (đã bỏ qua việc chèn label nguồn gốc)” nêu tên artifact đó. Cảnh báo này là điều được dự kiến với một đoạn có hình dạng như vậy chứ không phải dấu hiệu của vấn đề — các dịch vụ mà cùng thành phần phát ra đều mang đầy đủ tập, và không có gì thay đổi trong các byte được phát ra. Điều nó loại trừ là khả năng thứ ba: một tệp rời khỏi build mà không được đóng dấu và không được nêu tên.

CloudFormation là trường hợp còn lại cần biết, và nó khác ở chỗ nguồn gốc nằm ở đâu chứ không phải ở việc nguồn gốc có được đặt hay không. Một template CloudFormation không có khối metadata cấp tài liệu đi kèm với một tài nguyên, nên nguồn gốc được đặt trên thuộc tính Metadata của chính từng tài nguyên, dưới một khóa aggrega.ai/provenance duy nhất chứa toàn bộ tập:

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

Ba thuộc tính xuất phát từ vị trí đó. Thuộc tính Metadata có sẵn trên mọi tài nguyên bất kể loại, nên mọi tài nguyên mà một stack đã lắp ráp mang theo đều được đóng dấu — kể cả nhiều loại tài nguyên hoàn toàn không chấp nhận tag, nơi mà một con dấu dựa trên tag sẽ không có chỗ. Con dấu được thêm vào bất kỳ Metadata nào tác giả đã viết thay vì thay thế nó, nên các mục của chính tác giả vẫn nằm bên cạnh. Và vì nó áp dụng theo từng tài nguyên chứ không theo từng template, một stack được nhiều thành phần lắp ráp sẽ mang danh tính đóng góp riêng của từng tài nguyên — thành phần, Recipe và boundary của nó — điều mà một mục duy nhất cho toàn template không thể biểu đạt.

Toàn bộ tập đi cùng nhau dưới khóa đó. Một giá trị Metadata là JSON không bị ràng buộc, nên không cần chia theo bộ ký tự; hai khóa mà chỉ runtime Kubernetes đọc — tên label khuyến nghị chuẩn và annotation thứ tự triển khai mà một controller GitOps tiêu thụ — bị loại ra, vì không khóa nào nêu tên thứ gì trong một stack. Mục nguồn gốc đơn thuần aggrega.ai/sync-wave vẫn được giữ, vì nó ghi lại wave mà thành phần đã khai báo chứ không ra lệnh cho controller.

Hình dạng không có chỗ ở đây là một template hoặc đoạn không khai báo tài nguyên nào — loại chỉ đóng góp Parameters, Mappings, Conditions hoặc Rules. Nó không mang nguồn gốc, đến được stack đã lắp ráp với nội dung nguyên vẹn, và build phát ra cảnh báo “skipped provenance injection (đã bỏ qua việc chèn nguồn gốc)” nêu tên nó. Như với compose, cảnh báo này là điều được dự kiến với một phần đóng góp có hình dạng như vậy: các tài nguyên mà cùng thành phần đóng góp ở nơi khác đều mang đầy đủ tập, và các byte được phát ra vẫn như nhau dù có thứ gì đang lắng nghe hay không.

Ngữ nghĩa artifact theo từng Provider

Ngữ nghĩa theo từng provider dưới đây mô tả cách mỗi provider tích hợp artifact vào đầu ra gốc của mình.

provider helm: artifact là các tài liệu YAML Kubernetes được ghi vào một thư mục mang tên component đã khai báo chúng, bên trong thư mục đầu ra chứa các manifest được render từ chart và được tổng hợp từ Workload. Lý do nằm ở cách đặt tên: một manifest được render hoặc tổng hợp được provider đặt tên theo component mà nó thuộc về, còn một artifact được đặt tên theo khóa mà tác giả của nó đã viết, vốn không cho biết đó là component nào — vì vậy hai component gắn với cùng một Recipe sẽ ghi vào một đường dẫn duy nhất mà không tác giả nào có thể tách chúng ra. Thư mục mang chính tên của component, nên tệp mà tác giả đọc lại trong đầu ra có đúng tên họ đã viết, ở sâu hơn một cấp.

Một operator muốn bố cục khác có thể dùng template subDirectory: của boundary, template này di chuyển mọi tệp mà một bên đóng góp phát ra chứ không chỉ riêng các artifact. Xem ../language-reference/path-template-variables.md.

provider compose: artifact là các phân đoạn compose. Các khóa cấp cao nhất (services:, volumes:, configs:, models:) được hợp nhất vào docker-compose.yaml kết hợp của từng boundary trong bước kết hợp boundary.

provider helm-chart (trường hợp đặc biệt): artifact không được ghi vào thư mục đầu ra dưới dạng tệp độc lập — Helm sở hữu pipeline render. Thay vào đó, provider helm-chart đặt mỗi mục artifacts: vào bên trong chính chart, và dạng viết của mục đó quyết định nó nằm ở đâu. Mỗi mục được xử lý template Go với ngữ cảnh trụ cột của Aggrega TRƯỚC TIÊN, trước mọi thao tác đặt vị trí; từ đó hai dạng tách ra. Một mục được nạp bằng $import: là một tệp template tiền Helm: nó được chèn vào thư mục templates/ của chart TRƯỚC khi Helm render, nên Helm render nó cùng với các template riêng của chart nguồn. Một block scalar inline là một tệp rời của chart: nó được đặt ở gốc chart dưới khóa đã viết, không có tiền tố templates/ và không có nhãn nguồn gốc được hợp nhất, nên các template riêng của chart có thể đọc nó thông qua .Files.Get / .Files.Glob của Helm — mẫu ConfigMap-từ-tệp. Điều này mang lại cho provider helm-chart một cơ chế mở rộng tương đương với những gì artifacts: cung cấp cho provider helm thông thường, đồng thời tôn trọng mô hình chart của Helm.

Tệp được chèn nằm tại boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — các tệp của một bundle lồng bên dưới khóa đó — nên nó nằm cạnh các template của chart nguồn và Helm nhận nó trong lượt render tiếp theo. Một block scalar inline nằm tại boundaries/<bp>/charts/<nodeID>/<authored-key> — gốc chart, cao hơn templates/ một cấp — vì một tệp được đọc qua .Files phải nằm ở nơi chart tìm nó, còn một tệp đặt dưới templates/ sẽ bị render thành manifest. Cả hai dạng đều được đặt tên theo khóa mà chúng được viết dưới đó; điểm khác nhau giữa chúng là thư mục mà provider đặt chúng vào.

Quy ước dấu phân cách của helm-chart. Lượt tiền template của Aggrega trên các mục artifact helm-chart, dù được nạp bằng $import: hay inline, dùng dấu phân cách [[ ]] thay vì {{ }} mặc định, để cú pháp {{ ... }} riêng của Helm bên trong tệp đi nguyên vẹn vào lượt render của Helm. Tác giả viết các phép thay thế phía Aggrega dưới dạng [[ .context.instance_id ]], [[ .values.name ]], v.v.; các phép thay thế phía Helm vẫn giữ là {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }}, v.v. Việc tác giả trộn hai cặp dấu phân cách trong một tệp là dạng viết được hỗ trợ.

Nguồn gốc và artifact helm-chart. Thông tin nguồn gốc được hợp nhất vào metadata.labels và metadata.annotations (theo cách phân tách theo bộ ký tự ở trên) cho các tệp được nạp bằng $import: vượt qua được vòng chuyển đổi YAML mà vẫn giữ nguyên token Helm — các tệp chỉ dùng ngữ cảnh Aggrega [[ ]] hoặc chỉ có {{ }} của Helm ở vị trí scalar có dấu nháy. Các tệp có hành động template Helm mang tính cấu trúc ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} ở vị trí mà chúng phát ra cấu trúc YAML thay vì lá scalar), hoặc các tệp có {{ ... }} không có dấu nháy ở vị trí giá trị, không vượt qua được vòng chuyển đổi YAML của Aggrega; bản build phát ra cảnh báo “skipped provenance label injection” (bỏ qua việc chèn nhãn nguồn gốc) nêu tên artifact và chuyển tệp qua mà không thay đổi. Cảnh báo này là điều được dự kiến đối với mọi tệp artifact helm-chart được nạp bằng $import: có dùng hành động template Helm mang tính cấu trúc hoặc phép thay thế giá trị Helm không có dấu nháy — đó là trường hợp phổ biến khi viết Helm cho môi trường production, không phải trường hợp biên. Tác giả cần nhãn nguồn gốc trên những tệp như vậy sẽ chèn chúng qua một template có tên mà họ tự viết trong _helpers.tpl của chính chart (ví dụ một template tên là aggrega.commonLabels) hoặc một cơ chế tương đương phía Helm, chứ không qua việc chèn tiền template của Aggrega.

Xung đột tên tệp ở gốc chart. Một artifact được nạp bằng $import: có khóa đã viết trùng với tên tệp ở gốc chart (Chart.yaml, values.yaml, .helmignore, v.v.) sẽ không bị phát hiện bởi bước kiểm tra xung đột tên tệp của Aggrega — artifact nằm tại templates/<authored-key> trong khi tệp gốc nằm ở gốc chart, và tiền tố đường dẫn khiến chúng khác nhau theo góc nhìn của Aggrega. Tác giả tránh những tên khóa này; hệ quả của việc dùng chúng là Helm thấy cả hai tệp (một ở gốc chart, một bên trong templates/) và có thể render bản sao phía templates một cách ngoài ý muốn.

provider terraform: artifact là các tệp cấu hình Terraform, được phát ra nguyên văn vào thư mục riêng của component dưới cây modules/ của boundary. HCL (main.tf) là mặc định thuận tiện và Terraform JSON (.tf.json) được chấp nhận tương đương; không định dạng nào được chuyển dịch hay định dạng lại. Cấu hình gốc của boundary khai báo component đó là một khối module có source trỏ tới thư mục đó, nên toàn bộ một boundary vẫn là một đồ thị phụ thuộc duy nhất; đó cũng chính là thư mục mà các tệp của một module được vendor chiếm, nên một Recipe khai báo cả source: lẫn artifacts: sẽ ghi chúng cạnh nhau. Thông tin nguồn gốc đi kèm dưới dạng một khối chú thích Terraform ở đầu; khi một component đóng góp một phần thân JSON, vốn không có cú pháp chú thích, mọi phần thân được phát ra nguyên vẹn và thông tin nguồn gốc đi trong một tệp .tf đi kèm chỉ chứa chú thích đặt cạnh chúng, nên dấu đóng không bao giờ bị lặp giữa hai bên. Xem trang provider terraform.

provider cloudformation: artifact là các phân đoạn stack — các tài nguyên mà một component đóng góp chứ không phải cả một template. Provider chuẩn hóa mỗi phân đoạn thành các hàm nội tại dạng dài thuần JSON và hợp nhất nó vào stack duy nhất được lắp ráp cho thư mục đầu ra đó, nơi các tài nguyên gộp vào một map Resources và các provides của component xuất hiện dưới dạng Outputs của stack với tên được giới hạn trong component công bố chúng. Những phần cấp cao nhất khác của một phân đoạn còn giữ lại sau khi lắp ráp được nêu tại Tài liệu hợp nhất mang gì từ artifacts:. Xem trang provider cloudformation.

Phạm vi boundary: các tệp cho đầu ra dùng chung của một boundary

Cơ chế artifact có một phạm vi thứ hai. Mọi thứ ở trên được ghi vào vị trí riêng của component trong đầu ra của boundary của nó; spec.boundary.artifacts của một Recipe là cùng một map đó — cùng ba dạng, cùng quy tắc từ khóa sang tên tệp, cùng ngữ cảnh template — nhưng được ghi một lần cho toàn bộ boundary. Nó tồn tại cho một tệp mà đích đọc một lần cho mọi thứ một boundary triển khai, thứ mà không vị trí riêng nào của component có thể chứa: tài liệu của Terraform nói rằng một module được thiết kế để gọi không được chứa khối provider, và một module có chứa khối đó không thể được gọi với depends_on, count hoặc for_each, nên cấu hình của một provider thuộc về cấu hình gốc của boundary chứ không nằm trong module của một component.

Nơi tệp được đặt. Trong thư mục chứa đầu ra đã lắp ráp của nhóm dispatch, cạnh các tệp mà bước lắp ráp riêng của provider ghi ở đó — với terraform là cạnh cấu hình gốc. Trình biên dịch đánh giá mỗi mục một lần cho mỗi component mà Recipe render, theo ngữ cảnh của component đó, và tự ghi tệp: provider không được trao bất kỳ tệp nào trong số này, và không có gì được đóng dấu vào tệp để cho biết nó đến từ component nào, vì nó thuộc về mọi bên đóng góp đã khai báo nó.

Cách các bên đóng góp gặp nhau. Các tệp mà mọi bên đóng góp vào một nhóm dispatch đã khai báo được hợp nhất theo tên. Một tên được khai báo với các byte giống hệt nhau là một tệp; một tên được khai báo với các byte khác nhau, hoặc một tên mà bước lắp ráp của provider tự ghi, sẽ dừng bản build và nêu tên tệp cùng mọi bên đóng góp — cùng kiểu từ chối mà hai bên đóng góp ghi vào một đường dẫn đầu ra gặp phải. Vì vậy, một cấu hình provider mà hai Recipes cần sẽ được cả hai ghi dưới một tên, và bản build kiểm tra rằng chúng khớp nhau.

Ai chấp nhận nó. Việc một tệp đặt cạnh đầu ra đã lắp ráp của một boundary có ý nghĩa hay không là thuộc tính của đích mà provider nhắm tới, nên đó là tuyên bố của chính provider, được đọc từ khai báo của chính provider giống như các loại đầu vào của nó. Một Recipe khai báo khối này cho một provider không tuyên bố điều đó sẽ bị từ chối trước khi bất cứ thứ gì được render. Bảng lưới bên dưới ghi tuyên bố này ở cột cuối cùng; trong số các provider được phân phối cùng trình biên dịch, terraform đưa ra tuyên bố đó.

Artifact không phải là gì

Ba điểm phân biệt mang tính cấu trúc:

Không đa provider trong một Recipe. Một Recipe khai báo đúng một capability: ở đầu spec của nó. Mọi thứ Recipe tạo ra — đầu ra render từ source, đầu ra tổng hợp từ workload và các artifact được phát ra — đều ở định dạng gốc của provider đó. Artifact của một Recipe helm chứa YAML Kubernetes. Artifact của một Recipe compose chứa các phân đoạn compose. Một Recipe nhắm tới một provider; mọi đầu ra đều ở định dạng gốc của provider đó.

Việc kết hợp nhiều provider diễn ra ở cấp Release. Các boundary chứa các component với provider hỗn hợp; các bên đóng góp của từng provider tại đường dẫn đã đánh giá của một boundary được dispatch và lắp ráp độc lập theo từng (đường dẫn, provider). Một Release có các component lần lượt nhắm tới helm, helm-chart và compose có thể đặt cả ba vào một boundary; việc nhóm dispatch phân chia chúng theo provider, các bên đóng góp của từng provider nằm trong đầu ra đã lắp ráp riêng dưới đường dẫn của boundary, và operator viết phần điều phối giữa các provider thông qua cấu trúc boundary mà họ chọn. Việc điều phối giữa các provider là trách nhiệm của tác giả Release.

Không phải Recipes lồng trong Recipes. Artifact không nạp hay kết hợp các Recipes khác. Chúng là các manifest inline (hoặc đường dẫn tệp tới manifest inline), được xử lý template với các trụ cột của Recipe này và được phát ra vào đầu ra của Recipe này. Việc tái sử dụng Recipe diễn ra qua ba cơ chế: extends: của một Component (một Recipe viết cho một Component cơ sở phục vụ mọi Component mở rộng nó; thứ được kế thừa là metadata và schema, không phải tệp đầu ra — bản thân Recipe không khai báo extends:); ánh xạ URI phẳng của Manifest (cùng một Component có thể được phân giải thành các Recipes khác nhau trên các catalog — xem ../language-reference/entities/manifest.md); và Features + FeatureRecipes (các mối quan tâm xuyên suốt được gắn một cách trực giao).

Không phải lớp kết dính giữa các Recipe. Artifact không thể tham chiếu tên, tài nguyên hay trạng thái mà Recipe không tự khai báo. Một artifact ConfigMap được Workload của Recipe tham chiếu phải do chính Recipe này phát ra. Một artifact mong đợi một Secret được cấp phát từ bên ngoài phải lấy tên của Secret đó qua trụ cột .features — từ các provides đã phân giải của attachment phát ra nó — thay vì giả định rằng nó tồn tại. Đây là bất biến tự chứa (ở trên) được phát biểu từ góc nhìn viết artifact: mỗi Recipe phát ra các tệp ở một định dạng, được áp dụng bởi một công cụ, vào thư mục đầu ra của một boundary.

Ma trận năng lực của Provider

Mỗi provider khai báo những loại đầu vào mà nó render; một cổng loại đầu vào trung tâm chấp nhận các tổ hợp được hỗ trợ và từ chối phần còn lại bằng một chẩn đoán thống nhất khi node được render. Năng lực là thuộc tính của provider, không phải của Recipe — một provider render một tập con của ba loại. Cột artifacts: phân biệt các artifact đi kèm theo một đầu vào chính sourced/synthesized với một Recipe độc lập chỉ gồm artifact (không có source:, không có workload:). Hai cột cuối là tuyên bố của provider rằng nó tuân theo omits: và rằng nó chấp nhận các tệp mà một Recipe đóng góp vào đầu ra dùng chung của boundary của nó dưới boundary.artifacts: (ở trên); không cột nào là loại đầu vào.

Đọc từng cột riêng rẽ. Một hàng cho biết provider render những loại nào khi xét từng loại một. Hàng đó không nói rằng hai loại được đánh dấu có thể được khai báo cùng nhau. Vì các loại kết hợp theo cách cộng thêm, mỗi loại được khai báo được dispatch và phát ra riêng, nên một cặp có thể bị từ chối vì một lý do mà không cột nào thể hiện — thường gặp nhất là vì cả hai loại đều tạo ra một tệp có cùng tên đầu ra. Những tổ hợp mà mỗi provider thực sự chấp nhận được trình bày bằng văn xuôi tại Mỗi provider chấp nhận những gì, đầy đủ.

Providersource: + valuesMapping:workload:artifacts: (đi kèm)chỉ artifact (độc lập)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ được xử lý template với dấu phân cách [[ ]]❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

Bảng lưới này bao gồm các provider được phân phối cùng trình biên dịch. Một provider được cung cấp riêng sẽ khai báo theo cùng cách các loại đầu vào mà nó chấp nhận, liệu nó có tuân theo omits: hay không và liệu nó có chấp nhận boundary.artifacts: hay không, và trình biên dịch đọc khai báo đó theo cùng một đường — nó không được liệt kê ở đây, vì một trang đã xuất bản không thể liệt kê những provider mà nó chưa từng thấy.

Các ô được đánh dấu ✅ được render; ❌ là một sự từ chối về năng lực của provider do cổng đưa ra. Các phân đoạn compose theo từng node được hợp nhất theo từng đường dẫn lắp ráp, nên các boundary dùng chung một directory: sẽ dùng chung một tệp.

Mỗi provider chấp nhận những gì, đầy đủ

helm — mọi tổ hợp. source: + valuesMapping:, workload:, artifacts:, hai cái bất kỳ trong số đó, hoặc cả ba. Đây là provider duy nhất được phân phối cùng trình biên dịch không từ chối tổ hợp nào, và lý do là cách nó đặt tên đầu ra: mỗi tệp được phát ra được đặt tên theo tài nguyên bên trong nó, nên các manifest được render của một chart và các manifest của một Workload được tổng hợp không bao giờ rơi vào cùng một tên. Một Recipe khai báo cả ba sẽ phát ra các tệp của chart, các tệp của Workload và các tệp artifact cạnh nhau trong thư mục đầu ra của boundary.

compose — mọi tổ hợp trừ hai tổ hợp mà source: và workload: xuất hiện cùng nhau. Mỗi loại riêng lẻ đều build được, và artifacts: có thể đi kèm với một trong hai. source: cùng workload: không thể build, cả ba cùng nhau cũng vậy; Vì sao compose không thể kết hợp source với workload giải thích lý do, và đó không phải là một sự từ chối về năng lực.

helm-chart — source: + valuesMapping:, riêng lẻ hoặc có artifacts: đi kèm. Không gì khác. Nó không tổng hợp workload:, và không có dạng chỉ gồm artifact: một Recipe có loại đầu vào duy nhất là artifacts: sẽ bị dừng. Lý do là nơi provider này đặt một artifact — bên trong chart riêng của component — nên một Recipe không có source: không để lại chart nào cho nó đặt artifact vào.

terraform — ba dạng: source: + valuesMapping: riêng lẻ, artifacts: riêng lẻ, hoặc cả hai cùng nhau. Nó không tổng hợp workload:.

cloudformation — cùng ba dạng như terraform, với cùng một ngoại lệ duy nhất. source: + valuesMapping: riêng lẻ, artifacts: riêng lẻ, hoặc cả hai cùng nhau; không có workload:.

Một loại đầu vào bị từ chối trông như thế nào

Một Recipe khai báo một loại đầu vào mà provider được gắn với nó không render sẽ dừng bản build khi node được render, và dừng bất kể Recipe khai báo gì khác đi kèm loại đó — ghép một workload: với một source: mà provider có thể render không giúp workload đi qua. Thông báo dừng nêu tên provider, loại mà nó không thể render và các loại mà nó render:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

Sự từ chối dạng chỉ gồm artifact cũng có cách đọc tương tự và nêu tên dạng đó: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 là định danh cần ghi lại khi lần dừng này cần được gọi tên một cách lâu dài — trong một cổng tích hợp liên tục, một issue hoặc một runbook; bảng mọi điều kiện phân giải nó.

Vì sao compose không thể kết hợp source với workload

Provider compose tạo ra một phân đoạn cho mỗi component và đặt tên phân đoạn đó theo component. Việc render từ source và việc tổng hợp Workload đều tạo ra phân đoạn của component đó dưới cùng một tên, nên một Recipe khai báo cả hai sẽ tạo ra hai tệp trùng tên, và bản build dừng lại vì xung đột:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

Tên của phân đoạn đến từ định danh riêng của component và không có bề mặt viết nào cho nó, nên không thay đổi nào trong nội dung của Recipe tránh được xung đột. Việc dừng là thuộc tính của cặp chứ không phải của loại nào — compose render một source, compose tổng hợp một Workload, và bảng lưới đánh dấu cả hai là đúng. Để dùng cả hai dạng cho một component dưới compose, hãy tách chúng ra hai component, hoặc gộp nội dung của source vào Workload.

Tài liệu hợp nhất mang gì từ artifacts:

Hai provider hợp nhất các bên đóng góp của chúng thành một tài liệu duy nhất cho mỗi đường dẫn lắp ráp: compose thành một docker-compose.yaml, cloudformation thành một template stack. Một tài liệu hợp nhất chỉ có thể mang những phần mà bộ lắp ráp của nó mô hình hóa, nên một dấu tích ở artifacts: cho biết nội dung của một phân đoạn được đặt ở đâu chứ không phải mọi khóa bên trong phân đoạn đều được giữ lại.

compose mang services:, volumes:, configs: và models: từ một phân đoạn artifact, cùng với các khóa mở rộng có tiền tố x- của nó. Một phân đoạn khai báo bất cứ thứ gì khác ở cấp cao nhất sẽ dừng bản build và nêu tên khóa — networks:, vì mạng được suy ra theo từng boundary chứ không được tích lũy từ các bên đóng góp, và tương tự là một khối secrets: hoặc một name: cấp cao nhất. Trang provider compose nêu các quy tắc hợp nhất theo từng khóa và giải pháp thay thế cho định tuyến giữa các mạng.

cloudformation mang Resources, Outputs, Parameters, Mappings, Conditions, Metadata và Rules, và xây dựng Transform từ phần của mọi bên đóng góp. Các transform được nối theo thứ tự mà CloudFormation ghi trong tài liệu, với Globals của SAM đi cùng transform đọc chúng, và một transform có thể thay đổi cách nội dung của một bên đóng góp khác được triển khai sẽ dừng bản build và nêu tên nó. Description không được mang theo, và bản build có báo điều đó: nó đưa ra một cảnh báo trường không được hỗ trợ nêu tên phần đó và component, giống như với mọi khóa cấp cao nhất khác mà stack không mang, nên không có gì bị loại bỏ một cách âm thầm. Cảnh báo này chỉ mang tính tham khảo — template được phát ra giống hệt từng byte so với khi không có cảnh báo, và --no-unsupported-field-warnings tắt loại cảnh báo này. Outputs được mang dưới một tên mà provider giới hạn trong component đóng góp, nên hai component cùng đóng góp một output trùng tên vào một stack vẫn giữ chúng tách biệt. Các phần cấp cao nhất trong stack đã lắp ráp trình bày từng phần một.

Ba provider còn lại không hợp nhất, nên không có khóa artifact nào có nguy cơ bị một bộ lắp ráp loại bỏ. helm không lắp ráp gì: các manifest của mỗi component đi tới thư mục đầu ra của boundary đúng như chúng vốn có. terraform và helm-chart lồng nhau — các tệp của mỗi component nằm trong một thư mục riêng, một thư mục module Terraform hoặc một subchart, và một tài liệu gốc tại boundary tham chiếu tới chúng — nên một mục artifact được đặt như một tệp hoàn chỉnh thay vì được đọc vào một tài liệu dùng chung. Một mục artifact helm-chart nằm ở đâu, và vì sao cặp dấu phân cách của nó khác, được trình bày tại Ngữ nghĩa artifact theo từng Provider.