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.

WorkloadLibrary

Một WorkloadLibrary là một thực thể danh mục chứa các đoạn mẫu Workload có thể tái sử dụng. Các Recipes và FeatureRecipes triển khai cùng một dạng workload — một máy chủ công khai metrics, một batch job, một cặp sidecar — khai báo dạng đó một lần trong một thư viện và tham chiếu đến nó tại thời điểm sử dụng thông qua chỉ thị workload: { $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 workload giữa các Recipe. Các danh mục mà mỗi Recipe mang dạng workload riêng biệt của mình được phát hành mà không cần bất kỳ WorkloadLibrary nào.

Vai trò của WorkloadLibrary

Các kiến trúc sư nền tảng tạo các WorkloadLibraries để tập trung hóa nội dung Workload 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 các mục của thư viện bằng một chỉ thị $import:, được viết một lần và được sử dụng ở bất cứ nơi nào phép import được phân giải.

Sự phân tách giữa “thư viện” và “bên sử dụng” là có chủ đích. Các Recipes mã hóa chỉ dẫn build (source, valuesMapping, artifacts). Các FeatureRecipes mã hóa các phần gắn kèm hành vi. Các WorkloadLibraries chỉ mã hóa nội dung Workload — hình dạng workload mà provider tổng hợp thành các manifest gốc của provider. Việc giữ ba vai trò tách biệt cho phép mỗi loại thực thể phát triển theo nhịp độ riêng; những tác giả không cần nội dung workload dùng chung sẽ không bao giờ gặp thực thể thư viện.

Lớp vỏ thực thể

Một thực thể WorkloadLibrary mang lớp vỏ catalog tiêu chuẩn. apiVersion: aggrega.ai/v1beta1 và kind: WorkloadLibrary đánh dấu loại thực thể; metadata.name là một định danh PascalCase; metadata.version tuân theo phiên bản ngữ nghĩa 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 không trong suốt 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.workloads, một map bắt buộc phải khai báo ít nhất một mục.

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/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
workloads:
SimpleServer: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}

Soạn thảo các mục Workload

Mỗi mục là một đoạn Go template được soạn thảo dưới dạng chuỗi YAML. Đầu ra được kết xuất của mục là một tài liệu Workload hoàn chỉnh — nó mang apiVersion: aggrega.ai/v1beta1 và kind: Workload của riêng nó — vì trường workload: của một Recipe nhận một Workload hoàn chỉnh, không phải một đoạn được ghép vào một tài liệu bao quanh, và việc nhập sẽ thay thế toàn bộ trường. Một mục MappingLibrary cũng hoàn chỉnh theo cùng cách: nhập một mục như vậy sẽ thay thế toàn bộ valuesMapping: của Recipe.

Phần thân là mờ đục đối với lớp vỏ thực thể. Trình biên dịch lưu chuỗi nguyên văn khi tải WorkloadLibrary 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 nhập mục đó. Việc lưu đoạn nguyên văn giữ nguyên độ trung thực của bản soạn thảo để phát lại, và có nghĩa là lỗi template xuất hiện tại nơi mục được sử dụng và ngữ cảnh trụ cột của nó đã được biết, thay vì tại thư viện.

Vì một tài liệu Workload có nhiều dòng, các mục dùng scalar kiểu literal của YAML (|) để các dòng mới và thụt lề được giữ nguyên qua vòng lặp đọc–ghi:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

Giá trị của một mục phải là một scalar chuỗi. Việc viết một mapping hoặc một sequence ở vị trí của phần thân sẽ bị từ chối — phần thân của mục là văn bản template, không phải YAML có cấu trúc mà trình biên dịch duyệt qua.

Toàn bộ từ vựng kết hợp của Go template đều có sẵn bên trong một mục: {{ define "name" }}...{{ end }} khai báo các khối có thể tái sử dụng trong một thư viện, {{ template "name" . }} gọi chúng, còn các pipeline và hàm tuân theo gói Go chuẩn text/template. Ngữ cảnh trụ cột mà một mục có thể đọc — .values, .infra, .locals, .context, .features — cũng chính là ngữ cảnh mà mọi template Workload đọc, và được mô tả trên trang Workload trong phần đánh giá template.

Provider đích phải hỗ trợ tổng hợp workload. Một Recipe nhập một mục thư viện nhưng liên kết với một provider không thể tổng hợp Workload sẽ dừng một cách rõ ràng tại thời điểm kết xuất thay vì phát ra một hình dạng suy giảm; catalog thư viện chuẩn khai báo workloadSchema trên các provider có hỗ trợ, như hợp đồng được ghi trong tài liệu.

Chế độ soạn thảo duy nhất

WorkloadLibrary được cung cấp với một chế độ soạn thảo duy nhất: 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 về khả năng biểu đạt nào ở 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 xuyên suốt, và nội dung riêng của chúng được đánh giá qua cùng một engine Go template dùng để phân giải một fragment được import. Một bề mặt soạn thảo song song sẽ buộc tác giả phải chuyển đổi giữa các mô hình đánh giá 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 mục thư viện đượ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 mục thư viện cùng với những 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à khóa của các mục workload tuân theo PascalCase. JSON Schema của phong bì 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.name khớp với ^[A-Z][A-Za-z0-9]*$.
  • Các khóa map spec.workloads khớp với cùng mẫu đó thông qua propertyNames.

Một WorkloadLibrary có khóa không theo PascalCase trong spec.workloads sẽ không vượt qua bước xác thực phong bì khi tải workspace. Việc áp đặt này mang vai trò thiết yếu: khóa của các mục workload xuất hiện trong fragment tham chiếu #/workloads/<name>, nên một khóa không theo PascalCase sẽ lan truyền qua mọi bên tiêu thụ nhập mục đó.

Sự đồng nhất trong cách đặt tên giúp fragment #/workloads/<name> dễ đọc: #/workloads/BatchJob có thể hiểu ngay khi nhìn qua.

Tham chiếu các mục của thư viện

Tác giả Recipe và FeatureRecipe tham chiếu một mục workload bên trong khối workload: { $import: ... } bằng định danh tên trần của nó:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

Phân đoạn #/workloads/<name> chọn mục và phân biệt một tham chiếu workload với #/mappings/<name> của MappingLibrary và #/schemas/<name> của SchemaLibrary. Tham chiếu không mang máy chủ registry; dạng có máy chủ oci://… bị từ chối cả bởi schema của envelope lẫn tại nơi sử dụng, nhờ đó 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>#/workloads/<name> — dấu phân cách phiên bản là :, khớp với các ánh xạ recipe/feature và mục ghim trong lockfile, còn việc viết @ thay vào đó sẽ 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 ghim 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 vào lúc phân giải.

Cùng trường workload: chấp nhận hai dạng khác — một chuỗi Go template nội tuyến, và một $import: của đường dẫn tệp cục bộ tương đối với thư mục Recipe. Ba dạng được phân biệt bởi hình dạng của nội dung, và cả ba đều tạo ra cùng một Workload sau khi phân tích cú pháp. Xem Recipe để biết cách workload: kết hợp với các loại đầu vào khác của Recipe, 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

Một mục WorkloadLibrary có thể là một chuyển hướng $import: ở gốc trường: token đầu tiên trong thân của nó là $import: <Library>#/workloads/<entry>, thay thế toàn bộ mục bằng nội dung của mục được tham chiếu — tái sử dụng theo danh tính, không phải tạo template tại chỗ. Chuyển hướng được phân giải tại thời điểm sử dụng, không phải khi tải WorkloadLibrary, và nó được phân giải đệ quy, nên bản thân một mục được import cũng có thể là một $import: ở gốc trường. Một chuỗi vòng lặp quay lại chính nó sẽ dừng với một chẩn đoán nêu tên chu trình. $import: chỉ áp dụng cho toàn bộ mục; nó không phải là một hàm template giữa đoạn. Để ghép nội dung template bên trong một mục duy nhất, hãy dùng Go template define / template.

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

Một tên thư viện không xác định, và một tên mục không có trong một thư viện vẫn phân giải được, được báo cáo dưới dạng các chẩn đoán riêng biệt, nhờ đó tác giả có thể phân biệt một phụ thuộc bị thiếu với một mục bị viết sai chính tả.

Vị trí cấp bậc

WorkloadLibrary là Tier 3 trong mô hình tài liệu phân cấp thực thể — tùy chọn dành cho các catalog cần tái sử dụng nội dung workload giữa các Recipe. Các catalog có Recipes mang nội dung workload riêng biệt của chính chúng được phát hành mà không cần bất kỳ thực thể WorkloadLibrary 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ý WorkloadLibrary giống hệt như các loại thực thể catalog khác: cùng cách xác thực phần bao ngoài khi tải workspace, cùng quy trình phát hành OCI khi release, cùng cách ghim trong lockfile theo tên, phiên bản và digest nội dung.

Loại thư viện này là một trong 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, ArtifactLibrary chứa các gói artifact có thể tái sử dụng, WorkloadLibrary chứa nội dung workload có thể tái sử dụng. Mỗi loại đều là tùy chọn một cách độc lập; các catalog phát hành những loại chúng cần và không kèm loại nào khác.

WorkloadLibrary 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 phải là thứ thay thế cho workload: nội tuyến. Hầu hết các Recipes mang nội dung workload đủ đặc thù để đặt nội tuyến, nơi tác giả đọc nó cùng với phần còn lại của Recipe. Một WorkloadLibrary hữu ích khi CÙNG một dạng workload xuất hiện trong nhiều Recipes; với nội dung chỉ dùng một lần, viết nội tuyến là lựa chọn đúng.

  • Không phải là nơi chứa các mảnh rời rạc. Một mục được kết xuất thành một tài liệu Workload hoàn chỉnh. Tài liệu values của một Recipe thuộc về một MappingLibrary, một tập tệp phụ trợ thuộc về một ArtifactLibrary, 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 là một thực thể có thể triển khai độc lập. Một mục thư viện là nội dung Workload, và nội dung Workload không bao giờ có thể đượ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 WorkloadLibrary làm cho các mục của nó có thể được import; nó không làm cho chúng có thể triển khai.

  • Không phải là cơ chế tái sử dụng có tham số vượt ra ngoài các cơ chế của Go template. Tác giả cần biến thể có tham số sẽ dùng cơ chế {{ define }} + {{ template }} của Go template bên trong các mục thư viện, hoặc ngữ cảnh pillar mà Recipe sử dụng cung cấp. Bản thân thực thể thư viện không đi kèm bộ máy hỗ trợ tham số nào.