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.

MappingLibrary

Một MappingLibrary là một thực thể catalog chứa các đoạn Go template có thể tái sử dụng. Các Recipes và FeatureRecipes dùng chung toàn bộ một tài liệu valuesMapping: — các giá trị mà nhiều Recipes cùng lấy một chart làm nguồn đều trao cho chart đó — khai báo nó một lần trong một thư viện và tham chiếu nó tại thời điểm sử dụng thông qua một chỉ thị valuesMapping: { $import: ... }. Thực thể thư viện thuộc Tier 3: là tùy chọn dành cho các catalog cần tái sử dụng mapping giữa các Recipe. Các catalog không có nội dung template lặp lại được phát hành mà không cần MappingLibrary nào.

Vai trò của MappingLibrary

Các kiến trúc sư nền tảng tạo MappingLibraries để tập trung các đoạn template Go 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ứ đâu import được phân giải.

Việc tách biệt giữa “thư viện” và “bên sử dụng” là có chủ ý. Recipes mã hóa các chỉ dẫn build (source, valuesMapping, artifacts). FeatureRecipes mã hóa các phần gắn kèm hành vi. MappingLibraries chỉ mã hóa các đoạn template — nội dung Go template mà các thực thể khác sử dụng tại thời điểm render. Giữ ba vai trò này 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 template 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ể MappingLibrary mang lớp vỏ catalog tiêu chuẩn. apiVersion: aggrega.ai/v1beta1 và kind: MappingLibrary đánh dấu loại thực thể; metadata.name là một định danh PascalCase; metadata.version tuân theo quản lý phiên bản ngữ nghĩa nghiêm ngặt. Nội dung của thư viện nằm dưới spec.mappings, một map bắt buộc phải khai báo ít nhất một mục.

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

Một mục được đánh giá bởi chính engine template của Recipe sử dụng nó, dựa trên ngữ cảnh render của Recipe đó, nên nó đọc các trụ cột viết thường mà valuesMapping: của chính Recipe đọc — .values, .infra, .context và các phần còn lại — và dùng cùng các hàm, chẳng hạn helper optional có nhận biết sự hiện diện cho một khóa vắng mặt. .Values, cách viết của Helm cho values của chart, không phải là một gốc mà ngữ cảnh đó định nghĩa: một mục đọc nó sẽ dừng bản build, nêu tên tham chiếu.

Soạn thảo các mục ánh xạ

Mỗi mục ánh xạ là một đoạn Go template được soạn dưới dạng chuỗi YAML. Lớp vỏ thực thể không nhìn thấy nội dung của đoạn này — trình biên dịch lưu nguyên văn chuỗi khi nạp MappingLibrary và phân tích nó tại thời điểm sử dụng, khi một Recipe hoặc FeatureRecipe nhập mục đó qua valuesMapping: { $import: ... }. Việc nhập thay thế toàn bộ valuesMapping: của Recipe — map $import: không mang khóa nào khác — nên một mục là một tài liệu values hoàn chỉnh chứ không phải một mảnh được ghép vào một tài liệu.

Các đoạn ngắn vừa trên một dòng:

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

Các đoạn nhiều dòng dùng scalar kiểu literal của YAML (|) để ký tự xuống dòng và thụt lề được giữ nguyên qua quá trình đọc và ghi lại:

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

Toàn bộ bộ từ vựng kết hợp của Go template đều dùng được bên trong các đoạn: {{ define "name" }}...{{ end }} khai báo các khối tái sử dụng trong một thư viện duy nhất; {{ template "name" . }} gọi chúng; pipeline và hàm được hỗ trợ theo gói Go chuẩn text/template.

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

MappingLibrary đi kèm 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 ở 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 mục được import, nên một mục được đọc đúng như văn bản riêng của Recipe và tác giả chỉ cần học một mô hình đánh giá. Bộ từ vựng kết hợp của Go template — {{ define }} và {{ template }} bên trong một thư viện, và chỉ thị $import: tại thời điểm sử dụng — cung cấp các khối tái sử dụng được và lời gọi có tham số mà một thư viện cần.

Tác giả cần khả năng biểu đạt vượt quá những gì bộ từ vựng kết hợp của Go template cung cấp 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 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 song song bên trong chính MappingLibrary.

Quy ước đặt tên

Tên thư viện và khóa của các mục ánh xạ 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 pattern:

  • metadata.name khớp với ^[A-Z][A-Za-z0-9]*$.
  • Các khóa của map spec.mappings khớp với cùng mẫu đó thông qua propertyNames.

Một MappingLibrary có khóa không theo PascalCase trong spec.mappings 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 tính chịu lực: khóa của các mục ánh xạ xuất hiện trong fragment tham chiếu #/mappings/<name>; các 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 đặt tên giúp fragment #/mappings/<name> dễ đọc: #/mappings/ProbeBlock 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 ánh xạ bên trong khối valuesMapping: { $import: ... } bằng định danh tên trần (bare-name) của nó:

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

Fragment #/mappings/<name> chọn mục và phân biệt một tham chiếu ánh xạ với #/schemas/<name> của SchemaLibrary. Tham chiếu dùng cùng mô hình định danh tên trần như $ref: của SchemaLibrary — <Library>#/mappings/<name>, không mang host registry nào. Phiên bản được cung cấp bởi lockfile theo từng Release (tên + phiên bản + digest nội dung); tác giả có thể khẳng định một mức sàn phiên bản tối thiểu tùy chọn dưới dạng <Library>:<version>#/mappings/<name> (dấu phân tách phiên bản là :, khớp với các ánh xạ recipe/feature và việc ghim phiên bản trong lockfile), và vị trí vật lý được gắn kết tại thời điểm phân giải.

Kết hợp giữa các thư viện

Một mục MappingLibrary có thể là một chuyển hướng $import: ở gốc trường: token đầu tiên trong phần thân của nó là $import: <Library>#/mappings/<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 định danh, không phải tạo mẫu tại chỗ. Chuyển hướng được phân giải tại thời điểm sử dụng (khi kết xuất Recipe), không phải khi tải MappingLibrary, và theo cách đệ quy — một mục được nhập có thể tự nó là một $import: ở gốc trường. $import: chỉ áp dụng cho toàn bộ mục; nó không phải là một hàm mẫu giữa đoạn. Để kết hợp văn bản mẫu bên trong một đoạn 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:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

Các thư viện có thể tự do tham chiếu lẫn nhau. Một chuỗi vòng ngược về chính nó sẽ dừng khi Recipe sử dụng nó được render, kèm một chẩn đoán nêu tên từng bước của vòng lặp.

Vị trí cấp bậc

MappingLibrary thuộc Tier 3 trong mô hình tài liệu phân cấp thực thể — tùy chọn tham gia dành cho các catalog cần tái sử dụng mapping giữa các Recipe. Các catalog không có nội dung template lặp lại được phát hành mà không cần bất kỳ thực thể MappingLibrary 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” để đ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ý MappingLibrary đồng nhất với các loại thực thể catalog khác: cùng cơ chế kiểm tra envelope khi tải workspace, cùng pipeline phát hành OCI tại thời điểm release.

Loại thư viện này kết hợp tự nhiên với SchemaLibrary ở 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 template có thể tái sử dụng. Catalog cần cả hai thì phát hành cả hai; catalog không cần cái nào thì không phát hành cái nào.

Những gì MappingLibrary không phải là

Một vài hiểu lầm phổ biến cần được làm rõ trước:

  • Không phải là sự thay thế cho valuesMapping: nội tuyến. Hầu hết các Recipes mang nội dung valuesMapping: đơn giản, vốn có lợi khi được viết nội tuyến — Recipe vẫn tự chứa đầy đủ và người viết đọc nội dung ánh xạ cùng với phần còn lại của Recipe. MappingLibrary hữu ích khi CÙNG một đoạn xuất hiện trong nhiều Recipes; với các ánh xạ dùng một lần, viết nội tuyến là lựa chọn đúng đắn.

  • Không phải là nơi chứa nội dung schema. Các định nghĩa schema (JSON Schema 2020-12) thuộc về SchemaLibrary; các đoạn template thuộc về đây. 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à tái sử dụng có tham số vượt ra ngoài các cơ chế của Go template. Người viết cần biến thể có tham số sẽ dùng cơ chế {{ define }} + {{ template arg }} của Go template bên trong các mục thư viện, hoặc kết hợp các Components / Features bao bọc các mục thư viện với biến thể riêng của chúng. Bản thân thực thể thư viện không cung cấp cơ chế hỗ trợ tham số nào (không có khối templates tương tự các helper tham số spec.templates của SchemaLibrary); bộ từ vựng kết hợp của Go template đáp ứng cùng trường hợp sử dụng đó.