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.

Helm-Chart Provider

Provider helm-chart tạo ra một Helm umbrella chart được đóng gói cho mỗi đường dẫn assembly. Trong khi provider helm xuất YAML Kubernetes phẳng để GitOps sử dụng trực tiếp, helm-chart xuất một khung chart — một Chart.yaml + values.yaml umbrella cùng một sub-chart cho mỗi node đóng góp — mà công cụ phía sau có thể cài đặt qua helm install hoặc vendor để tùy chỉnh thêm theo từng môi trường. Provider tổng hợp theo từng (path, provider): mọi node gắn với một Recipe helm-chart đều đóng góp vào umbrella tại directory: đã được đánh giá của boundary, nối với subDirectory: của từng component. Hai boundary được đánh giá ra cùng một đường dẫn sẽ gộp thành một umbrella chart hợp nhất, liệt kê mọi bên đóng góp như một dependency sub-chart.

Các template của một sub-chart được sao chép từ chart nguồn mang những gì tác giả của chúng đã viết: giá trị syncWave: <integer> của boundary, helm.sh/hook-weight trên một hook và các nhãn nguồn gốc Aggrega chỉ có mặt ở chúng khi chart tự viết chúng. Chính helm provider là provider gắn argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" và các nhãn nguồn gốc lên mọi tài nguyên nó render. Một artifact được nạp bằng $import: mà provider này thêm vào sub-chart mang các nhãn nguồn gốc và annotation argocd.argoproj.io/sync-wave, và không mang helm.sh/hook-weight (xem “Quy tắc chèn artifacts:” bên dưới). ArgoCD đọc annotation sync-wave, còn Helm đọc trọng số của hook.

Trang này là tài liệu tham khảo dành cho việc soạn thảo của provider helm-chart. Về sự phân chia giữa helm và helm-chart, xem mục Providers của trang Status; về mô hình kết hợp đầu vào giữa các provider, xem architecture/16-recipe-input-composition.md.

Các loại đầu vào được hỗ trợ

Provider helm-chart chấp nhận hai loại đầu vào:

  • Chế độ có nguồn. Một Recipe với source: <chart-path> trỏ đến một thư mục Helm chart trên đĩa. Chart được sao chép vào cấu trúc umbrella dưới dạng một sub-chart, giữ nguyên trừ name của chính chart đó — xem “Tên chart mà umbrella sở hữu”; không có việc render hay xử lý template nào được thực hiện ở cấp từng node. Vai trò của Aggrega là kết hợp (lắp ráp umbrella trên các node của boundary), không phải đánh giá template.
  • Chế độ artifacts: được nạp bằng $import:. Một Recipe có các mục artifacts: được viết dưới dạng $import: cho từng mục sẽ khai báo thêm các tệp template mà provider helm-chart chèn vào thư mục templates/ của sub-chart sau khi sao chép chart nguồn. Mỗi tệp được xử lý template trước theo ngữ cảnh template của Aggrega bằng các dấu phân cách [[ ]] (xem “Quy tắc chèn artifacts:” bên dưới), nhờ đó mọi template Helm {{ }} trong cùng tệp được giữ nguyên đến lần render helm install ở hạ nguồn.

Một Recipe nhắm đến helm-chart mà khai báo workload: sẽ bị từ chối trước khi render, với cùng lời từ chối mà bất kỳ provider nào đưa ra cho một loại đầu vào nó không khai báo — lời từ chối nêu loại mà provider này hỗ trợ và hướng tác giả đến một provider có tổng hợp:

provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (provider không hỗ trợ loại đầu vào của node (node “api”). Provider “helm-chart” không hỗ trợ các recipe tổng hợp (provider này hỗ trợ: sourced); hãy khai báo một trong các loại đầu vào được hỗ trợ, hoặc nhắm đến một provider hỗ trợ tổng hợp)

Sự phân tách này là có chủ đích: tổng hợp workload (chuyển một Workload trừu tượng thành các tài nguyên Kubernetes) là mối quan tâm riêng của provider helm. Vai trò của helm-chart là kết hợp umbrella + sub-chart cho các chart mà tác giả đã tạo sẵn.

Một Recipe nhắm đến helm-chart cũng có thể khai báo các mục artifacts: có nội dung nội tuyến (các mục có giá trị là một block scalar mang nội dung tệp trực tiếp trong Recipe thay vì một tham chiếu được nạp bằng $import:). Một mục nội dung nội tuyến được đặt ở gốc sub-chart dưới khóa đã viết của nó — không có tiền tố templates/ và không ghép provenance. Các template của chính chart đọc một tệp rời như vậy qua .Files.Get / .Files.Glob của Helm (mẫu ConfigMap-từ-tệp chuẩn), vì vậy một tệp ở gốc chart là một dạng hợp lệ, hạng nhất chứ không phải một lỗi.

Cả hai dạng đều được đánh giá với các dấu phân cách Aggrega [[ ]] trước khi đặt vào, nên nội dung của dạng nào cũng có thể đọc ngữ cảnh pillar của Recipe; {{ }} trong cả hai đều được giữ nguyên và trở thành một chỉ thị Helm vào lúc helm install ở hạ nguồn. Điều khác nhau giữa hai dạng là nơi tệp được đặt và việc provenance có được hợp nhất vào hay không:

  • Một mục được nạp bằng $import: là một tệp template: sau khi đánh giá (xem “Quy tắc chèn artifacts:” bên dưới), nó được chèn vào thư mục templates/ của sub-chart với provenance được hợp nhất vào, nên Helm render nó như một manifest cùng với các template của chính chart.
  • Một mục nội dung nội tuyến là một tệp dữ liệu rời: sau khi đánh giá, nó được đặt ở gốc chart, giữ nguyên như kết quả đánh giá và không mang provenance hợp nhất, để được dùng qua .Files.

Quy tắc chèn artifacts:

Khi một Recipe helm-chart khai báo các mục artifacts: qua $import: theo từng mục, mỗi giá trị $import: là đường dẫn tới một tệp template được phân giải tương đối với thư mục của chính Recipe (thư mục chứa tệp YAML của Recipe trên đĩa). Provider:

  1. Đọc nội dung của từng tệp.
  2. Tiền xử lý template nội dung với các dấu phân cách Aggrega [[ ]] dựa trên ngữ cảnh template của Recipe (cùng ngữ cảnh mà valuesMapping: của Recipe được đánh giá). {{ }} bên trong nội dung tệp được giữ nguyên — chúng trở thành các chỉ thị template của Helm tại thời điểm helm install.
  3. Ghi từng tệp vào charts/<instance-id>/templates/<authored-key> dưới đường dẫn lắp ráp của umbrella, với các tệp của một bundle được lồng bên dưới khóa đó. Khóa mà mục được khai báo dưới đó đặt tên cho tệp; đường dẫn $import: chọn nội dung của tệp và không góp phần nào vào tên, vì vậy cấu trúc thư mục bên trong đường dẫn đó không bao giờ xuất hiện trong đầu ra.

Nguyên tắc hai cặp dấu phân cách [[ ]] / {{ }} là chi tiết then chốt. Một tệp artifact điển hình được nạp bằng $import: có thể kết hợp nội suy ở thời điểm Aggrega (ví dụ: [[ .values.image ]]) với nội suy ở thời điểm Helm (ví dụ: {{ .Release.Namespace }}). Mỗi cặp dấu phân cách được xử lý ở giai đoạn riêng của nó: Aggrega phân giải [[ ]] tại thời điểm biên dịch, trước khi tệp được đặt vào; Helm phân giải {{ }} tại thời điểm cài đặt, sau khi umbrella được phát hành.

Xung đột tên tệp giữa các template của source-chart và các artifact được chèn qua $import: sẽ gây ra CATALOG_ERROR — chẩn đoán nêu đường dẫn đầu ra bị xung đột, chẳng hạn templates/cm.yaml, và hai loại đầu vào đã tạo ra nó. Tác giả giải quyết xung đột bằng cách đổi tên khóa của artifact hoặc template của chính chart.

Bộ khóa source:

source: của provider helm-chart chỉ định một chart, và nó chấp nhận cả hai dạng mà trường source: nhận, được đọc đúng như bộ khóa source: của provider helm mô tả: một chuỗi đường dẫn hệ thống tệp trần, và một đối tượng có cấu trúc mà url: mang vị trí. Khi url: chỉ định một đường dẫn hệ thống tệp, không có gì được tải về và chart được đọc từ đĩa; khi nó mang một lược đồ truyền tải — ví dụ oci://…, với kind: helm-oci-chart — aggrega pull tải về và ghim chart, và bản build sao chép nó ra khỏi bộ nhớ đệm vào umbrella dưới dạng một sub-chart, theo cùng điều kiện như một chart được đọc từ đĩa.

spec:
capability: helm-chart
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Chart tại đường dẫn nguồn phải chứa một Chart.yaml hợp lệ ở thư mục gốc; nếu thiếu, một lỗi rõ ràng sẽ xuất hiện trước khi việc sao chép chạy. Bố cục thư mục của chart được giữ nguyên khi sao chép — templates/, values.yaml, Chart.yaml và mọi tệp khác đều có mặt trong thư mục sub-chart sau khi kết hợp. Mọi tệp đến nơi với đúng các byte bạn đã viết, đến cả chú thích, thứ tự khóa và cách đặt dấu ngoặc; ngoại lệ duy nhất là trường name trong Chart.yaml của chính chart, do umbrella đặt — xem “Tên chart mà umbrella sở hữu”.

Cả hai cách không chỉ định được chart đều bị từ chối, và hai sự từ chối này đến từ những nơi khác nhau — điều đáng biết, vì chỉ một trong hai thay đổi nếu bạn chuyển capability. Một source: có mặt nhưng không khai báo gì bị trình biên dịch từ chối trước khi bất kỳ provider nào chạy, nên kết quả là như nhau bất kể Recipe chỉ định capability nào; thông báo chẩn đoán yêu cầu bạn bỏ trường này cho chế độ không nguồn hoặc chỉ định một đường dẫn không rỗng. Bỏ hẳn source: là cách viết hợp lệ — đó là cách một Recipe yêu cầu chế độ không nguồn — và nó bị từ chối ở đây vì helm-chart chỉ khai báo loại đầu vào có nguồn, nên trình biên dịch từ chối tổ hợp này với cùng thông báo mà nó đưa ra cho bất kỳ capability nào được yêu cầu một loại đầu vào mà nó không khai báo. Điều thuộc riêng về helm-chart là lời khai báo, không phải một sự từ chối của riêng nó: đối với các tài nguyên Kubernetes được tạo từ một khối workload:, hãy dùng capability helm thay thế.

Một Recipe khai báo omits: sẽ bị từ chối. Khóa omits: loại khỏi bản build các tài liệu mà một nguồn render ra, còn provider này không render tài liệu nào lúc build: nó sao chép chart vào umbrella, và các template của chart được render khi umbrella được cài đặt. Không có gì được render thì không có gì để loại bỏ, nên provider này không khai báo rằng nó tuân theo khóa đó, và một Recipe hoặc FeatureRecipe khai báo khóa này sẽ bị từ chối trước khi bất cứ thứ gì được sao chép — xem The provider does not support omits (Provider không hỗ trợ omits). Với một chart bạn giữ bên cạnh Recipe, một dòng trong .aggregaignore ở đó sẽ loại một tệp của chart ra thay thế, kể từ lần tiếp theo Recipe được ghim; với một chart được tải về mà đầu ra phải bỏ đi một tài liệu, hãy render nó qua provider helm, vốn tuân theo khóa này.

Kết hợp theo đường dẫn — hình dạng umbrella

Provider chạy theo hai pha cho mỗi đường dẫn assembly:

  1. Sao chép theo từng contributor. Với mỗi nút gắn với một Recipe helm-chart, provider sao chép toàn bộ cây thư mục của chart nguồn vào một vị trí sub-chart. Các tệp được đặt phẳng trong map đầu ra của từng contributor; assembler chỉ định charts là thư mục con chứa các contributor của nó, và orchestrator cấp cho mỗi contributor một thư mục riêng tại đó khi lắp ráp umbrella — charts/<instance_id>/ đối với một component. Một attachment Feature cũng là một contributor — dù nó vendor một chart hay render manifest qua helm provider — và nhận một thư mục nằm bên cạnh thư mục của component thay vì bên trong nó; xem “Nơi chart của một attachment được đặt”.
  2. Lắp ráp umbrella theo từng (path, provider). Khi mọi bản sao theo từng nút của đường dẫn đã hoàn tất, assembler xuất một Chart.yaml + values.yaml umbrella tại gốc của đường dẫn assembly. Umbrella khai báo một dependency cho mỗi nút đóng góp và định tuyến các giá trị theo từng nút vào các khối con có khóa là instance-id. Khi đường dẫn assembly nhận contributor từ nhiều hơn một boundary (các boundary dùng chung directory:), mọi contributor đều trở thành dependency trong cùng một umbrella.

Chart.yaml umbrella có hình dạng:

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: Aggrega umbrella chart for boundary "<assembly-path>"
dependencies:
- name: <encoded-instance-id> # the name the placed sub-chart carries
version: <user-chart-version> # from the source chart's Chart.yaml
alias: <encoded-instance-id> # see "How a name is derived" below
repository: file://charts/<instance_id> # the sub-chart's own directory

Phân giải tên chart

name chart của umbrella được phân giải qua cascade annotation của boundary. Annotation aggrega.ai/chart-name hiệu lực của mỗi boundary đóng góp (giá trị được cascade phân giải, đi ngược lên cây boundary) quyết định tên umbrella; giá trị đã phân giải được mã hóa cho vị trí tên chart giống hệt như bất kỳ định danh nào khác, nên một giá trị chỉ chứa chữ cái, chữ số, dấu gạch dưới và dấu gạch nối mà quy tắc bên dưới giữ lại sẽ đến chart nguyên văn. Khi đường dẫn assembly nhận contributor từ nhiều hơn một boundary, aggrega.ai/chart-name hiệu lực của mọi contributor PHẢI phân giải thành cùng một giá trị; sự không khớp sẽ dừng build với một chẩn đoán nêu tên các giá trị xung đột và các boundary đóng góp.

Cascade giải quyết tự nhiên mâu thuẫn DRY: khai báo aggrega.ai/chart-name một lần trên boundary cha và các boundary con kế thừa nó qua cascade; các boundary anh em không có cha chung phải khai báo tường minh các giá trị khớp nhau. Các boundary không khai báo aggrega.ai/chart-name ở bất kỳ đâu trong cascade của chúng sẽ dùng tên aggregate và đường dẫn lắp ráp — thư mục đầu ra của umbrella dưới dist/, chẳng hạn boundaries/data/helm-chart — mỗi phần được mã hóa và nối lại như mô tả bên dưới.

name của mỗi mục dependency là tên mà sub-chart được đặt mang — định danh đã mã hóa của chính instance component, cùng giá trị với alias — vì những lý do trong “Tên chart do umbrella sở hữu”. version của nó vẫn là version lấy từ Chart.yaml của chính chart nguồn. Alias đặt phạm vi các giá trị của sub-chart dưới values.yaml.<alias>.*, khớp với quy ước umbrella-values của Helm để các giá trị theo từng instance được truyền đúng khi umbrella được cài đặt.

Thư mục sub-chart của một component giữ instance_id đúng như khi viết, nên charts/<instance_id>/ là nơi các tệp của nó được đặt và là nơi repository của dependency trỏ tới. Do đó hai instance của cùng một chart nguồn cùng tồn tại mà không xung đột trên hệ thống tệp, và mỗi instance giữ khối giá trị riêng dưới alias riêng của nó.

name và repository của dependency là hai chuỗi khác nhau, và điều đó là do thiết kế. name là thứ mà chart tại vị trí đó KHAI BÁO, vì Helm gắn một dependency với một chart con theo tên do chính chart con khai báo; repository là nơi chart đó nằm. Với một component, hai giá trị tình cờ giống nhau, vì cả hai đều bắt nguồn từ cùng một instance id. Với một attachment Feature, chúng khác nhau — tên khai báo mang định danh kết hợp của attachment, còn thư mục mang hai tọa độ của nó được nối lại — nên đọc cái này thành cái kia sẽ chỉ tới một thứ không tồn tại.

Nơi chart của một attachment được đặt

Một attachment Feature vendor một chart nhận một thư mục riêng bên cạnh component mà nó được gắn vào, ở một cấp dưới charts/:

charts/
├── api/ # the component's own chart
├── api--guardrail/ # a Feature attached to `api` under `guardrail`
└── api--audit/ # a second Feature attached to the same component

Một Feature được gắn vào một boundary thay vì một component thì không có component chủ để đặt tên, nên thư mục của nó chỉ là tên instance của nó: charts/aux/.

Vì sao bên cạnh thay vì bên trong. Helm phát hiện chart con tại charts/* — một cấp, không duyệt đệ quy. Một chart được đặt sâu hơn thế không phải là con của bất kỳ thứ gì; nó là dữ liệu bên trong thư mục của một chart con khác, chỉ truy cập được qua .Files. Vì vậy một chart được đặt bên trong thư mục chart của chính component sẽ được sao chép vào đầu ra, sẽ khiến build thành công, và sẽ không đóng góp tài nguyên nào của nó vào những gì bạn triển khai — mà không có gì báo cáo điều đó. Đặt mỗi contributor vào thư mục cấp cao nhất riêng của nó là điều khiến các tài nguyên của attachment được render.

Umbrella cũng khai báo attachment là một trong các dependency của nó. Cả hai nửa đều cần thiết: một chart có mặt dưới charts/ nhưng vắng trong dependencies: là một lỗi lint, và một chart được khai báo trong dependencies: mà không có chart con tương ứng khiến umbrella từ chối tải.

Hai tọa độ được nối, không phải ghép liền. Tên thư mục được tạo từ host và instance thông qua cùng quy tắc escape mô tả bên dưới, áp dụng cho từng tọa độ trước khi chúng được nối bằng --. Ghép trực tiếp chúng bằng -- sẽ gây mơ hồ: một host tên a--b với instance c, và một host a với instance b--c, sẽ ra cùng một thư mục. Mã hóa từng tọa độ trước giữ chúng tách biệt, nên một -- được viết bên trong một tọa độ xuất hiện thành -zh-.

Tên thư mục chấp nhận những gì. Chữ cái ASCII ở cả hai dạng hoa thường, chữ số, dấu chấm và dấu gạch dưới được giữ nguyên như bạn viết, nên API--aux và web.api--aux trông đúng như bạn mong đợi. Một dấu gạch nối bạn viết được giữ lại ở bất cứ đâu ký tự sau nó là một trong các ký tự đó, nên web-api--aux không đổi; một cặp gạch nối đôi được escape, vì cặp đó là dấu nối. Mọi thứ khác được escape theo cùng quy tắc như tên chart. Tập ký tự được giới hạn như vậy vì các tên thư mục này vừa là đường dẫn trên đĩa vừa là vị trí mà con trỏ file:// của một dependency phân giải tới, và một ký tự hợp lệ trong tên tệp có thể cắt cụt hoặc giải mã lại một URL.

Giá trị đi theo tên khai báo, không theo thư mục. Các giá trị của một chart con được đặt phạm vi dưới tên mà chart đó khai báo, nên các giá trị cho chart ở trên được định địa chỉ theo tên khai báo của api--guardrail — cfr-zh-api-zh-guardrail — thay vì theo thư mục của nó.

Bạn không bao giờ tự viết khóa đó. Bạn viết các giá trị trên attachment, và values.yaml của umbrella được tạo sẵn cho bạn với khối đã nằm tại địa chỉ mà chart được đặt dùng. Với một Feature gắn vào một component, đó là values: bạn khai báo trên attachment, được đọc bởi valuesMapping: của chính FeatureRecipe; với một Feature gắn vào một boundary, đó là infra: bạn khai báo tại đó, vì một Feature gắn vào boundary không có trụ giá trị component. Dù là trường hợp nào, map mà valuesMapping: phân giải thành sẽ trở thành khối riêng của attachment trong umbrella:

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

Đây là con đường duy nhất của các giá trị đó. Một chart do Feature mang đến sẽ có các tệp đúng như tác giả của nó đã viết — ngoại trừ trường manifest duy nhất được mô tả trong “Tên chart do umbrella sở hữu” — nên không có gì ghi các giá trị của bạn vào chart đó, và khối của umbrella là thứ cung cấp chúng. Một chart mà khối của nó không bao giờ đến không phải là một chart hỏng: nó render các giá trị mặc định mà values.yaml của chính nó cung cấp và báo thành công, vì vậy hãy đặt cho một giá trị mặc định một giá trị mà bạn sẽ nhận ra nếu muốn thấy sự khác biệt trong lúc viết.

Attachment có FeatureRecipe render qua helm provider

Một FeatureRecipe thuộc capability helm, được gắn vào một component trên đích này, mang đến các manifest Kubernetes hoàn chỉnh thay vì một chart. Chúng được đặt vào thư mục riêng của attachment đúng như helm provider đã render chúng, và provider cung cấp cho thư mục đó hai thứ khiến nó thành một chart mà Helm cài đặt được: một Chart.yaml tối thiểu, khai báo tên riêng của attachment ở phiên bản 0.1.0, và một template, templates/rendered.yaml, phát ra từng tệp YAML đã render qua .Files.Get của Helm theo tên của nó:

charts/api--guardrail/
├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0
├── guardrail-config.yaml # the manifest the helm provider rendered
└── templates/
└── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}

Tên được khai báo là tên mà một chart do cùng attachment đó vendor sẽ khai báo, nên mục phụ thuộc của umbrella và khối values của nó được định địa chỉ đúng như mô tả ở trên. .Files.Get trả về các byte của tệp nguyên trạng thay vì đánh giá chúng lần thứ hai, nên một manifest mang dấu ngoặc nhọn template theo nghĩa đen — {{ $labels.instance }} của một quy tắc cảnh báo, truy vấn của một dashboard — được cài đặt với chúng còn nguyên vẹn. Các giá trị của nó đã được phân giải vào những manifest đó khi helm provider render chúng, nên khối mà values.yaml của umbrella mang dưới tên đó không được thứ gì đọc.

Tên chart do umbrella sở hữu

Điều duy nhất Aggrega thay đổi bên trong một chart bạn đã vendor là trường name của chính chart đó. Trong Chart.yaml của chart được đặt, name được đặt thành định danh đã mã hóa của bất kỳ thứ gì đã đóng góp chart đó.

Với một component, đó là định danh của chính instance component — cùng giá trị với alias của dependency — và mục dependency của umbrella cũng nêu giá trị đó, nên hai phía luôn khớp nhau.

Một chart do một attachment Feature mang đến là một contributor độc lập, và nó khai báo định danh riêng của nó thay vì lặp lại định danh của component mà nó được gắn vào. Định danh đó được tạo từ hai thứ bạn đã viết — component chứa attachment, và tên mà Feature được gắn theo — đứng sau một phần mở đầu ngắn đánh dấu nó là định danh của một attachment chứ không phải của một component; giá trị kết hợp sau đó được viết cho vị trí tên chart qua phép dẫn xuất bên dưới, giống hệt như bất kỳ định danh nào khác.

Vì vậy, gắn một Feature vendor chart vào một component tên api dưới tên guardrail sẽ đặt một chart khai báo cfr-zh-api-zh-guardrail, trong khi chart riêng của component đó vẫn khai báo api. Hai cái là các contributor riêng biệt, và mỗi cái khai báo một tên của riêng mình thay vì cả hai cùng khai báo tên của host.

Không có gì khác trong chart bị động đến. Mọi tệp khác đến nguyên từng byte như bạn đã viết, và bên trong Chart.yaml, mọi trường khác, mọi chú thích, thứ tự khóa và cách đặt dấu nháy đều đúng như khi viết. Một khóa lồng ở nơi khác trong manifest cũng tình cờ có tên name — chẳng hạn tên của một maintainer — được giữ nguyên.

Vì sao umbrella cần trường đó. name của một chart là thứ mà Helm dùng để gắn dependency của umbrella. Nó được viết bởi người tạo ra chart, mà với một chart lấy từ upstream thì không phải người triển khai nó — nên hai component trong một đường dẫn assembly hoàn toàn có thể vendor các chart có manifest khai báo cùng một tên. Nếu cả hai sub-chart giữ tên chung đó, cả hai dependency của umbrella sẽ phân giải tới chart nào trong hai chart mà Helm tải trước: chart của một component sẽ được render hai lần và của component kia thì không lần nào, trong khi giá trị của mỗi component vẫn đến, nên đầu ra trông đầy đủ nhưng lại sai. Dẫn xuất tên được đặt từ instance component loại bỏ hoàn toàn tên chung, đó là lý do không có gì phải bị từ chối — kể cả hai trường hợp không có cách khắc phục nào khác: vendor cùng một chart dưới hai component, nơi tên được chia sẻ do chính cấu trúc, và vendor một chart bạn không viết, mà tên của nó bạn không thể thay đổi.

Điều duy nhất bạn có thể quan sát thấy. Một template đọc tên chart của chính nó — {{ .Chart.Name }}, và bất cứ thứ gì dẫn xuất từ nó như thành ngữ đặt tên tài nguyên phổ biến {{ .Chart.Name }}-{{ .Release.Name }} — sẽ đọc định danh instance đã mã hóa, không phải tên được viết trong Chart.yaml của chart nguồn. Đó cũng là thứ mà template như vậy đã đọc trước khi trường được đặt, vì Helm báo cáo một sub-chart theo alias mà chart cha dùng để gắn nó; việc đặt trường khiến tệp trên đĩa khớp với những gì quá trình render đã tạo ra. Vì vậy với ví dụ minh họa bên dưới, một template trong sub-chart api-east đọc được api-east.

Nếu tên tài nguyên phải mang tên chart như khi viết, hãy đặt tên đó vào values.yaml của chart và đọc nó từ đó — một giá trị là của bạn và Aggrega không động đến nó.

Cách dẫn xuất một tên

Tên chart Helm và alias dependency Helm mỗi thứ chấp nhận một tập ký tự hẹp hơn những gì một tên aggregate, một đường dẫn boundary hoặc một instance_id có thể chứa. Thay vì thay thế một ký tự mà đích không chấp nhận, phép dẫn xuất viết nó ra, nên hai định danh chỉ khác nhau ở dấu câu luôn cho ra hai tên — và một giá trị viết dưới một alias chỉ có thể đến sub-chart mà alias đó chỉ tới.

  • Chữ cái, chữ số và dấu gạch dưới được giữ nguyên đúng như khi viết.
  • Dấu gạch nối được giữ như khi viết ở bất cứ đâu ký tự sau nó được giữ nguyên trực tiếp và không phải là chữ z thường. Một dấu gạch nối theo sau bởi chữ z thường sẽ mở một chuỗi escape, nên một dấu gạch nối được viết ở vị trí đó cũng được viết ra — api-zone trở thành api-zhzone, đó là điều cho phép đọc ngược lại bất kỳ tên nào mà không cần đoán.
  • Mọi ký tự khác được viết là -z theo sau bởi một chữ cái chỉ tên ký tự đó: d cho dấu chấm, s cho dấu phân cách đường dẫn, h cho dấu gạch nối mà quy tắc ở trên không giữ lại. Mọi thứ còn lại được viết là x kèm code point thập lục phân sáu chữ số của ký tự, và một byte không bắt đầu ký tự nào được viết là b kèm giá trị hai chữ số của chính nó — nên một tên không phải văn bản hợp lệ vẫn được viết ra riêng biệt thay vì bị gộp lại.
  • Giá trị rỗng được viết là -ze, điều mà không giá trị không rỗng nào có thể tạo ra.
  • Khi hai định danh tạo nên một tên chart — một tên aggregate bổ nghĩa cho một đường dẫn lắp ráp — chúng được nối bằng --. Một định danh đã mã hóa không bao giờ chứa cặp đó, nên tên đã nối cho biết rõ ràng định danh nào là định danh nào.

Vì vậy một instance_id data.main-db cho ra alias data-zdmain-db, và aggregate fullstack-app với đường dẫn lắp ráp boundaries/data/helm-chart cho ra tên chart fullstack-app--boundaries-zsdata-zshelm-chart. Đầu vào giống nhau luôn tạo ra tên giống nhau.

values.yaml umbrella có khóa theo alias:

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

Khi valuesMapping: của một sub-chart được đánh giá dựa trên ngữ cảnh template của nó, map giá trị thu được sẽ tự động điền vào khối con có khóa theo alias này. Điều đó đúng với mọi contributor của umbrella, không chỉ với các component: một attachment Feature vendor một chart là một contributor độc lập, nên valuesMapping: của FeatureRecipe của nó điền vào một khối riêng, có khóa theo tên mà chart được đặt của nó khai báo. Xem “Nơi chart của một attachment được đặt”.

Một khóa mà valuesMapping: đặt thành null được ghi vào khối của nó là null. Khi cài đặt bằng Helm 4, một null trong chính values.yaml của umbrella chỉ xóa giá trị mặc định của sub-chart cho khóa đó khi lần cài đặt cũng cung cấp giá trị cho sub-chart đó; một lần cài đặt không cung cấp giá trị nào cho nó sẽ bỏ null, và giá trị mặc định của sub-chart được giữ. Một null trong các giá trị truyền cho helm install xóa giá trị mặc định trong cả hai trường hợp.

Các đặc điểm riêng của Provider

  • Chart.yaml của sub-chart là bắt buộc. Thao tác sao chép yêu cầu phải có Chart.yaml tại gốc của source-path. Nếu thiếu, quá trình build dừng lại trước khi bước umbrella chạy.
  • name của chart được đặt vào thuộc về umbrella. Nó được đặt thành định danh đã mã hóa của bất cứ thứ gì đóng góp chart đó — định danh riêng của một instance component, hoặc, với chart do một attachment Feature mang đến, định danh riêng của attachment đó — và đó là thứ duy nhất bên trong một chart được vendor mà Aggrega thay đổi. Xem “The chart name the umbrella owns”.
  • Chart nguồn phải khai báo một version và một name. Version của mục dependency là version mà chính Chart.yaml của chart nguồn khai báo, nên một chart không khai báo version sẽ làm dừng build thay vì được gán một version — một dependency được ghim vào version mà sub-chart không mang sẽ khiến các values theo từng instance của umbrella không thể đến được nó. Một chart có Chart.yaml không khai báo name, chứa nhiều hơn một tài liệu YAML, hoặc không phân tích được cũng dừng vì cùng lý do: umbrella không thể ghép một sub-chart mà nó không đọc được.
  • Alias và tên chart được mã hóa. Một instance_id, tên aggregate hoặc boundary path chứa ký tự mà tên Helm chart hoặc dependency alias không chấp nhận sẽ xuất hiện ở dạng mã hóa trong umbrella được render, theo “How a name is derived” ở trên. Một định danh chỉ gồm chữ cái, chữ số, dấu gạch dưới và các dấu gạch nối mà phép dẫn xuất giữ lại sẽ xuất hiện đúng như khi viết.
  • Con trỏ repository file://. Các mục dependency của umbrella dùng một con trỏ repository file:// chỉ tới thư mục riêng của chart con — file://charts/<instance_id> đối với một component, và thư mục riêng của attachment đối với chart do một Feature mang đến. Đây là quy ước của hệ thống tệp cục bộ cho các chart con nằm trong cây và cho phép helm dependency build phân giải umbrella mà không cần gọi registry bên ngoài. Con trỏ chỉ một vị trí và không bao giờ là tên đã khai báo của chart; hai thứ này khác nhau đối với một attachment, và helm dependency build là bước từ chối một con trỏ chỉ tới thư mục không tồn tại.
  • Không render template ở cấp helm-chart. Provider không gọi pipeline render của Helm SDK; nó sao chép và ghép. Tác giả cần các manifest phẳng đã render sẵn nên dùng chế độ sourced của provider helm.

Ví dụ minh họa

Một boundary gồm hai node, mỗi node được gắn với một Recipe helm-chart trỏ đến cùng một chart nguồn:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Sau khi kết hợp, đường dẫn assembly đã được đánh giá của boundary (mặc định là dist/<boundary-directory>/<capability>/ vì subDirectory: mặc định là {{ .capability }}) chứa:

dist/<boundary-directory>/helm-chart/
├── Chart.yaml # umbrella; lists api-east and api-west as dependencies
├── values.yaml # alias-keyed: api-east + api-west values blocks
└── charts/
├── api-east/ # ./charts/api-server, name: api-east
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml
└── api-west/ # ./charts/api-server, name: api-west
├── Chart.yaml
├── values.yaml
└── templates/
└── deployment.yaml

Cả hai sub-chart đều là bản sao của cùng một chart nguồn, và mỗi sub-chart mang tên instance riêng của nó trong Chart.yaml — đây chính là điều cho phép một chart được vendor hai lần trong cùng một umbrella. Mọi thứ khác trong cả hai bản sao đều giống hệt nguồn.

Lệnh helm install <release-name> dist/<boundary-directory>/helm-chart chạy trên bố cục này sẽ cài đặt cả hai instance như một Helm release duy nhất, với các values theo khóa alias của umbrella điều khiển template của từng sub-chart.

Tham chiếu chéo