ArtifactLibrary
Một ArtifactLibrary là một thực thể danh mục chứa các gói artifact có thể tái sử dụng — những tập hợp được đặt tên gồm các tệp đầu ra phụ trợ đi cùng nhau. Các Recipes và FeatureRecipes phát ra cùng các tài nguyên hỗ trợ — một CRD cùng RBAC và một ConfigMap của nó, một NetworkPolicy đi kèm một HPA — khai báo tập hợp đó một lần trong một thư viện và tham chiếu đến nó khi sử dụng thông qua một mục artifacts: có giá trị là một chỉ thị $import:. Thực thể thư viện thuộc Tier 3: tùy chọn cho các danh mục cần tái sử dụng artifact giữa các Recipe. Các danh mục mà mỗi Recipe tự mang theo các tệp phụ trợ của riêng nó được phát hành mà không cần bất kỳ ArtifactLibrary nào.
Vai trò của ArtifactLibrary
Các kiến trúc sư nền tảng tạo các ArtifactLibraries để tập trung hóa các manifest phụ trợ lặp lại trong các Recipes và FeatureRecipes của catalog. Một thư viện không phải là một chỉ dẫn build có thể triển khai; nó là một không gian tên định nghĩa. Tác giả Recipe và FeatureRecipe tham chiếu một bundle bằng một chỉ thị $import:, được viết một lần và được sử dụng ở bất cứ đâu mà import được phân giải.
Điều phân biệt loại thư viện này với ba loại còn lại là độ chi tiết của một mục. Một mục SchemaLibrary là một schema, một mục MappingLibrary là một đoạn template, và một mục WorkloadLibrary là một tài liệu Workload — mỗi mục là một nội dung duy nhất được sử dụng tại một vị trí duy nhất. Một mục ArtifactLibrary là một tập hợp tệp, vì các tài nguyên mà nó nhóm lại chỉ hữu ích khi đi cùng nhau: import một CRD mà không có RBAC của nó sẽ tạo ra một tập manifest không hoạt động. Đó là lý do một bundle là đơn vị tái sử dụng và một vị trí sử dụng duy nhất được mở rộng thành nhiều đầu ra.
Lớp vỏ thực thể
Một thực thể ArtifactLibrary mang lớp vỏ catalog tiêu chuẩn. apiVersion: aggrega.ai/v1beta1 và kind: ArtifactLibrary đánh dấu loại thực thể; metadata.name là một định danh PascalCase; metadata.version tuân theo quy chuẩn semantic versioning nghiêm ngặt. Cả hai đều bắt buộc. metadata.description, metadata.labels và metadata.annotations là tùy chọn — labels và annotations là siêu dữ liệu mờ do tác giả khai báo, được mang theo để bất cứ thứ gì đọc thư viện có thể dùng để so khớp, và trình biên dịch không diễn giải giá trị của chúng. Nội dung của thư viện nằm dưới spec.artifacts, một map bắt buộc phải khai báo ít nhất một bundle.
Lớp vỏ được đóng ở cả ba cấp — gốc tài liệu, metadata và spec đều từ chối các khóa mà schema không khai báo.
apiVersion: aggrega.ai/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Soạn thảo các gói artifact
spec.artifacts có hai cấp, và mỗi cấp có một nhiệm vụ riêng. Khóa bên ngoài là tên gói — định danh mà bên sử dụng tham chiếu. Các khóa bên trong là tên tệp, và mỗi giá trị bên trong là phần thân Go template được xuất ra tệp đó. Một gói phải khai báo ít nhất một tệp.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"Phần thân tệp là một đoạn Go template được viết dưới dạng chuỗi YAML. Vì một manifest có nhiều dòng, phần thân tệp dùng scalar kiểu literal của YAML (|) để dấu xuống dòng và thụt lề được giữ nguyên qua quá trình khứ hồi. Giá trị của một mục gói phải là một ánh xạ từ tên tệp tới phần thân dạng chuỗi; viết một chuỗi trần ở vị trí của gói, hoặc một sequence, sẽ bị từ chối — cấp mà bên sử dụng import là gói, không phải một tệp đơn lẻ.
Phần thân là mờ đối với envelope của thực thể. Trình biên dịch lưu nguyên văn từng chuỗi khi tải ArtifactLibrary và không phân tích template tại đó; trình phân tích template chạy vào thời điểm sử dụng, khi một Recipe hoặc FeatureRecipe import gói. Việc lưu nguyên văn phần thân giữ được độ trung thực của bản soạn thảo khi xuất lại, và điều đó có nghĩa là lỗi template xuất hiện tại nơi gói được sử dụng và ngữ cảnh pillar của nó đã được biết, thay vì tại thư viện.
Thứ tự tệp trong một gói là thứ tự tác giả đã viết, được giữ nguyên qua quá trình tải và sử dụng, nên tập tệp được xuất ra ổn định giữa các lần build.
Toàn bộ vốn từ vựng kết hợp của Go template đều dùng được bên trong phần thân tệp: {{ define "name" }}...{{ end }} khai báo các khối tái sử dụng, {{ template "name" . }} gọi chúng, còn pipeline và hàm tuân theo gói Go chuẩn text/template. Ngữ cảnh pillar mà phần thân tệp có thể đọc — .values, .infra, .locals, .context, .features, cùng .workload và .source khi Recipe sử dụng khai báo chúng — là ngữ cảnh mà chính các mục artifacts: của Recipe sử dụng đọc, được mô tả trên trang Recipe dưới trường artifacts:. Một phần thân đọc .workload khi Recipe sử dụng không khai báo workload:, hoặc đọc .source khi nó không khai báo source:, sẽ dừng lại với một chẩn đoán nêu tên tham chiếu không thể đáp ứng — mỗi pillar được kiểm tra riêng, nên việc khai báo một pillar không cho phép đọc pillar kia.
Chế độ soạn thảo duy nhất
ArtifactLibrary chỉ có một chế độ soạn thảo: Go template. spec không chấp nhận bề mặt soạn thảo song song nào và không có lối thoát nào về khả năng biểu đạt ở cấp thư viện.
Lý do là tính đồng nhất của bề mặt sử dụng. Recipes và FeatureRecipes đều dùng Go template từ đầu đến cuối, và nội dung của chính chúng được đánh giá qua cùng một engine Go template dùng để phân giải một bundle được import. Một bề mặt soạn thảo song song sẽ buộc tác giả phải chuyển đổi mô hình đánh giá ngay trong quá trình render của một Recipe duy nhất — một mô hình cho nội dung riêng của Recipe, một mô hình khác cho mọi bundle được import. Giữ bề mặt đồng nhất nghĩa là tác giả chỉ cần học một mô hình đánh giá và áp dụng nó ở mọi nơi.
Tác giả cần khả năng biểu đạt vượt ra ngoài bộ từ vựng kết hợp của Go template sẽ kết hợp ở cấp cao hơn — các Components hoặc Features bao bọc các bundle của thư viện với biến thể thực chất của riêng chúng — thay vì leo thang sang một ngôn ngữ soạn thảo thứ hai bên trong thư viện.
Quy ước đặt tên
Tên thư viện và tên bundle tuân theo PascalCase. JSON Schema của envelope thực thể áp đặt quy ước này tại hai vị trí thông qua các ràng buộc mẫu:
metadata.namekhớp với^[A-Z][A-Za-z0-9]*$.- Các khóa map của
spec.artifactskhớp với cùng mẫu đó thông quapropertyNames.
Một ArtifactLibrary có tên bundle không theo PascalCase sẽ không vượt qua bước xác thực envelope khi nạp workspace. Việc áp đặt này có vai trò then chốt: tên bundle xuất hiện trong fragment tham chiếu #/artifacts/<name>, nên một tên không theo PascalCase sẽ lan truyền qua mọi bên tiêu thụ import bundle đó.
Sự thống nhất trong cách đặt tên giúp fragment #/artifacts/<name> dễ đọc: #/artifacts/OperatorSupport có thể hiểu ngay khi nhìn qua.
Tên tệp bên trong một bundle là tự do, miễn là mỗi tên chỉ một tệp. Chúng không theo PascalCase và không có mẫu schema nào ràng buộc chúng, vì chúng đặt tên cho các tệp mà đầu ra của một bản build cuối cùng mang theo — crd.yaml, deny-all.yaml, values-override.json đều hợp lệ. Điều một tên tệp bắt buộc phải là một tên tệp tương đối thông thường, được viết đơn giản; bản build từ chối một tên không chỉ tệp nào của riêng nó, như Tham chiếu các mục trong thư viện mô tả. Hai cấp này được ràng buộc khác nhau vì chúng phục vụ những người đọc khác nhau: tên bundle là một định danh mà các thực thể khác trích dẫn, còn tên tệp là những tên mà bên tiêu thụ nhìn thấy bên trong thư mục nơi bundle được import.
Tham chiếu các mục của thư viện
Tác giả Recipe và FeatureRecipe tham chiếu một bundle bên trong một mục artifacts: có giá trị là một map $import:, bằng định danh tên trần của bundle:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"Fragment #/artifacts/<name> chọn bundle và phân biệt một tham chiếu artifacts với #/mappings/<name> của MappingLibrary, #/schemas/<name> của SchemaLibrary và #/workloads/<name> của WorkloadLibrary. Tham chiếu không mang registry host; dạng có host oci://… bị từ chối cả bởi schema của envelope lẫn tại vị trí sử dụng, nên một vị trí registry vật lý không bao giờ đi vào mã nguồn được viết. Tác giả có thể khẳng định một mức phiên bản tối thiểu tùy chọn dưới dạng <Library>:<version>#/artifacts/<name> — dấu phân tách phiên bản là :, khớp với các loại thư viện khác và với pin trong lockfile, và việc viết @ thay vào đó bị từ chối với một chẩn đoán nêu tham chiếu đã sửa. Phiên bản được phân giải do lockfile của từng Release cung cấp, lockfile này pin mỗi thư viện được sử dụng theo tên, phiên bản và digest nội dung; vị trí vật lý được gắn tại thời điểm phân giải.
Bundle sở hữu các tên tệp của nó, còn khóa sử dụng sở hữu thư mục chứa chúng. Một mục artifacts: import một bundle sẽ mở rộng thành một đầu ra cho mỗi tệp trong bundle đó, mỗi đầu ra lồng dưới khóa sử dụng dưới dạng <key>/<filename>. Khóa tại vị trí sử dụng — operator-support ở trên — đặt tên cho toàn bộ việc sử dụng chứ không cho một tệp riêng lẻ nào; ví dụ xuất ra operator-support/crd.yaml và operator-support/rbac.yaml. Vì vậy tên bundle được chọn để dễ đọc tại tham chiếu, các tên tệp được chọn cho người đọc thư mục đầu ra, và không bên nào phải khớp với bên kia. Bản thân khóa sử dụng bị giới hạn ở một tên tệp duy nhất — 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 nối và dấu gạch dưới, và một khóa nằm ngoài bảng ký tự đó sẽ không qua được kiểm tra envelope — nên nó đặt tên đúng một đoạn thư mục, và mọi thứ bên dưới đoạn đó đến từ bundle. Chính điều đó cho phép tên tệp của bundle tự do trong khi khóa vẫn chặt chẽ: một tên tệp là duy nhất trong bundle của nó, một khóa là duy nhất trong tài liệu của nó, và khóa là đoạn đầu tiên của mọi đường dẫn mà mục xuất ra, nên không có hai mục artifacts: nào đặt tên cho cùng một đầu ra. Tự do nghĩa là tự do trong phạm vi đoạn đó: một tên tệp có thể mang bố cục lồng nhau riêng — crds/widget.yaml nằm tại <key>/crds/widget.yaml — nhưng nó phải là một tên tệp tương đối thông thường bên dưới khóa, viết đơn giản, và một tên tệp không như vậy sẽ dừng bản build thay vì đặt tệp vào nơi mà Recipe sử dụng chưa từng chỉ định. Điều đó từ chối một tên leo lên trên khóa hoặc chỉ một vị trí tuyệt đối; . hoặc ./, và một tên thu gọn trở lại khóa như x/.., vốn chỉ chính thư mục của khóa chứ không phải một tệp trong đó; và một tên có / ở cuối hoặc lặp đôi, hoặc có phần . hay .. — x/, a//b, ./a, a/../b — vốn là cách viết thứ hai của một tệp mà tên khác có thể mang, nên a//b bên cạnh a/b sẽ đặt hai tệp tại một đường dẫn. Chẩn đoán nêu tệp bundle và khóa mà nó được import tại đó. Hai đầu ra thực sự mang cùng một tên tệp sẽ dừng bản build khi node được render, điều này xảy ra khi hai loại đầu vào khác nhau cùng đóng góp một tên tệp. Xem Recipe để biết cách artifacts: kết hợp với các loại đầu vào khác của Recipe và hai chế độ viết không dùng thư viện, và vocabulary/cross-document-ref để biết sự phân biệt rộng hơn giữa $ref: / $import:.
Kết hợp giữa các thư viện
Phần thân của một tệp trong bundle là nội dung cuối. Khác với một mục của MappingLibrary hoặc WorkloadLibrary, một tệp trong bundle không thể là một chuyển hướng $import: ở gốc trường: một vị trí tệp đơn lẻ không có chỗ cho nhiều tệp mà một bundle khác sẽ mang vào, vì vậy trình biên dịch từ chối dạng đó thay vì phân giải nó thành thứ mà tác giả không viết. Một phần thân có token đầu tiên là $import: sẽ dừng lại với một chẩn đoán nêu tên bundle và tệp.
Thay vào đó, việc kết hợp diễn ra tại vị trí sử dụng, nơi có chỗ cho nó. Một Recipe cần hai bundle sẽ khai báo hai mục artifacts:, và mỗi mục được mở rộng độc lập:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Một tên thư viện không xác định, và một tên bundle không có trong một thư viện vẫn phân giải được, được báo cáo thành các chẩn đoán riêng biệt, để tác giả có thể phân biệt một phụ thuộc bị thiếu với một tên bundle bị viết sai.
Vị trí cấp bậc
ArtifactLibrary thuộc Cấp 3 trong mô hình tài liệu phân cấp thực thể — tùy chọn cho các catalog cần tái sử dụng artifact giữa các Recipe. Các catalog có Recipes tự mang các tệp phụ trợ của riêng chúng được phát hành mà không cần bất kỳ thực thể ArtifactLibrary nào; việc đánh dấu cấp bậc báo hiệu “nâng cao; bỏ qua nếu không cần” cho việc điều hướng tài liệu, chứ không phải về khả năng. Trình biên dịch xử lý ArtifactLibrary đồng nhất với các loại thực thể catalog khác: cùng cơ chế xác thực envelope khi tải workspace, cùng quy trình phát hành OCI tại thời điểm release, cùng cơ chế ghim lockfile theo tên, phiên bản và digest nội dung.
Loại thư viện này hoàn thiện một bộ ở cấp catalog — SchemaLibrary chứa các định nghĩa schema có thể tái sử dụng, MappingLibrary chứa các đoạn mapping có thể tái sử dụng, WorkloadLibrary chứa nội dung workload có thể tái sử dụng, và ArtifactLibrary chứa các bundle artifact có thể tái sử dụng. Mỗi loại là tùy chọn độc lập; các catalog phát hành những loại chúng cần và không cần bất kỳ loại nào khác.
ArtifactLibrary không phải là gì
Một vài hiểu lầm phổ biến cần được làm rõ trước:
-
Không thay thế cho
artifacts:nội tuyến. Hầu hết các Recipes mang theo các tệp phụ trợ đủ đặc thù để được viết nội tuyến, nơi tác giả đọc chúng cùng với phần còn lại của Recipe. Một ArtifactLibrary hữu ích khi CÙNG một tập tệp đi kèm nhiều Recipes; với nội dung dùng một lần, viết nội tuyến là lựa chọn đúng. -
Không phải cách để đổi tên các tệp bên trong một bundle. Tên tệp thuộc về bundle. Bên sử dụng chọn thư mục mà các tệp được đặt vào — đó là việc khóa sử dụng thực hiện — nhưng không chọn tên của bất kỳ tệp nào: bên sử dụng cần một tên tệp khác thì hoặc dùng một bundle khai báo tên đó, hoặc tự viết tệp nội tuyến.
-
Không phải nơi chứa nội dung workload, mapping hay schema. Một tài liệu Workload thuộc về một WorkloadLibrary, tài liệu values của một Recipe thuộc về một MappingLibrary, và các định nghĩa schema thuộc về một SchemaLibrary. Các loại thư viện được phân chia theo loại nội dung, không theo mẫu tái sử dụng.
-
Không phải cơ chế cho các tài nguyên xuyên suốt. Các tài nguyên phụ trợ áp dụng cho nhiều component bất kể Recipe nào hiện thực hóa chúng — một sidecar sao lưu gắn vào mọi kho dữ liệu — thuộc về cơ chế sinh tài nguyên của FeatureRecipe, vốn gắn theo Feature thay vì theo Recipe. Xem entities/featurerecipe.md. Một ArtifactLibrary tách riêng các tệp mà nhiều Recipes đều tự phát sinh cho chính mình.
-
Không phải một thực thể có thể triển khai độc lập. Một bundle là nội dung artifact, và nội dung artifact không bao giờ được tham chiếu riêng lẻ — nó tồn tại như đầu vào mà một Recipe hoặc FeatureRecipe sử dụng. Việc xuất bản một ArtifactLibrary khiến các bundle của nó có thể được import; nó không khiến chúng có thể triển khai.