Đặt tên cho một tài nguyên được kết xuất
Một Recipe thường xuyên phải gọi tên một thứ mà chính đầu ra của nó đã tạo ra: một hostname để công bố qua
provides:, một tham chiếu bên trong một valuesMapping:, một định danh được ghi vào phần thân của artifacts:.
Hai khóa của ngữ cảnh template mang các tên có sẵn cho việc đó, và chúng trả lời những câu hỏi khác nhau.
Đọc nhầm khóa sẽ tạo ra đầu ra sai một cách âm thầm thay vì bị từ chối — một địa chỉ gọi tên một
tài nguyên mà không có gì phát ra — vì vậy trang này trình bày khóa nào trả lời câu hỏi nào.
Trang này cũng trình bày sự phân biệt mà hai khóa dựa vào: một target và một tham chiếu không phải là cùng một thứ, và một target không bao giờ là một tên mà nền tảng triển khai sẽ phân giải.
Target đặt tên cho một component; reference đặt tên cho một tài nguyên đã render
Target là một định danh khi soạn thảo. Đó là giá trị mà nhà phát triển viết để chỉ ra một cạnh trỏ tới component nào — target: my_db trong một khối uses — và là định danh mà quá trình build dùng để tìm component đó, báo cáo về nó trong các chẩn đoán, và làm khóa cho các dữ kiện của nó. Nó đọc như nhau dưới mọi provider, vì đó là dữ kiện về tài liệu của bạn chứ không phải về bất kỳ nền tảng nào.
Reference là thứ khiến một artifact đã render trỏ tới một artifact khác. Nó được viết bằng từ vựng riêng của một provider: một địa chỉ nội bộ cluster dưới helm, một tên service dưới compose, một phép nội suy dưới terraform, một giá trị được import dưới cloudformation. Reference khác nhau dưới mỗi provider, vì mỗi nền tảng phân giải reference theo cách riêng của nó.
🔴 Target không bao giờ được viết vào đầu ra đã render. Mỗi provider tự suy ra tên của riêng nó, nên một định danh soạn thảo được giao cho nền tảng làm tên sẽ sai bất cứ khi nào hai cách viết khác nhau — và chúng khác nhau đúng ở những ký tự mà bảng chữ cái của chính target không chấp nhận. Một định danh không chứa ký tự như vậy sẽ giữ nguyên, và đó là điều khiến lỗi này dễ mắc: sai lầm vẫn chạy được cho đến khi ai đó đặt tên component có dấu gạch dưới hoặc chữ hoa.
Vì vậy reference mà bên tiêu thụ cần được công bố bởi bên cung cấp, vì Recipe của bên cung cấp là thứ biết từ vựng của provider của chính nó — bên tiêu thụ có thể gắn một provider hoàn toàn khác, và không thể viết reference cho một nền tảng mà nó không render tới. Bên tiêu thụ đọc một chuỗi đã công bố thông thường.
Cặp ví dụ minh họa
Recipe của bên cung cấp công bố địa chỉ; bên tiêu thụ đọc lại nó thông qua alias của cạnh.
# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.# It publishes an in-cluster address built from the name that chart's own# templates render their resources against.spec: capability: helm source: ./charts/postgres provides: host: "{{ .context.rendered_name }}.svc.cluster.local" port: "5432"# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an# authoring identity and stays in the documents. The uses block is keyed by the# socket the catalog entity declares, then by the alias you choose for the edge.spec: components: api: type: core/compute/api-server uses: databases: primary: target: my_db inject: env: - in: DB_HOST from: host - in: DB_PORT from: port# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.# The context keys an edge by its alias, so the socket does not reappear here.spec: capability: helm valuesMapping: | { "db_host": "{{ .context.uses.primary.provides.host }}" }Với một chart do tác giả cung cấp dưới helm, một component tên my_db render các tài nguyên của nó dưới release name my-zudb. Vì vậy chart của bên cung cấp phát ra một Service có metadata.name là my-zudb, host được công bố là my-zudb.svc.cluster.local, và bên tiêu thụ kết nối tới một Service có tồn tại — dù nó đọc giá trị qua .context.uses.primary.provides.host hay nhận giá trị dưới dạng DB_HOST được inject.
Nếu viết {{ .context.uses.primary.target }} ở đó thì sẽ công bố my_db.svc.cluster.local thay vào đó. Giá trị đó trông không hề sai: nó là định danh mà nhà phát triển đã viết, đúng như cách họ viết. Chỉ là nó không đặt tên cho Service nào cả, và không có gì trong quá trình build báo điều đó.
Hai khóa, như một cặp
Không khóa nào tự nó dễ hiểu, vì mỗi khóa được định nghĩa bởi điều mà khóa kia không phải.
| Khóa | Nó đặt tên cho gì |
|---|---|
{{ .context.instance_id }} | Định danh của nút, và tên của các tài nguyên được xây dựng cho nút này mà không provider nào suy ra tên cho chúng — một tập artifact được đặt từ khối artifacts: của bạn, và một workload được tổng hợp từ khối workload: của bạn bởi một provider đặt tên nó theo định danh, như compose làm. Luôn có mặt. |
{{ .context.rendered_name }} | Tên mà provider được gắn suy ra cho các tài nguyên nó render cho nút này — với nguồn do bạn cung cấp, đó là tên mà các template bạn cung cấp dùng để render tài nguyên của chúng, chẳng hạn tên release mà một chart đọc; với một workload: mà nó tổng hợp, đó là tên nó đặt cho các tài nguyên đó khi nó đặt tên chúng theo một tên của riêng nó thay vì theo định danh, như helm làm. Chỉ có mặt khi provider đó suy ra một tên. Trên các template riêng của một phần đính kèm Feature, đó là tên của component chủ — xem bên dưới. |
Sự phân tách này xuất phát từ nơi mà tên phải dùng được. Một chart hoặc module do bạn cung cấp có các template, và các template đó đặt tên tài nguyên của chúng theo bất kỳ định danh nào nền tảng trao cho chúng — nên tên phải là tên mà nền tảng đó sẽ dùng, được viết theo bảng chữ cái riêng của nền tảng đó. Một workload được tổng hợp không có template nào của bạn, nhưng các tài nguyên của nó vẫn phải mang những tên mà nền tảng chấp nhận: một provider có tên chấp nhận mọi thứ mà một tên do tác giả viết có thể chứa sẽ đặt tên chúng theo định danh, còn một provider có tên không chấp nhận thì đặt tên chúng theo tên nó suy ra — và rồi báo cáo tên đó tại đây, để bạn không bao giờ phải đoán trước nó.
Một nút khai báo cả một nguồn được cung cấp lẫn một workload: sẽ phát ra cả hai loại đầu ra cùng lúc, và không cần khóa thứ ba. Dưới helm, cả hai đều được đặt tên theo cùng một tên release, nên rendered_name dùng được cho cả hai: các tài nguyên riêng của chart mang tên đó theo bất kỳ cách nào các template của nó ghép tên, và mỗi Service được tổng hợp là <rendered_name>-<service key>. Dưới một provider đặt tên một workload được tổng hợp theo định danh, hãy đặt tên các tài nguyên của workload đó bằng instance_id và các tài nguyên của đầu ra được cung cấp bằng bất kỳ giá trị nào provider báo cáo cho nó.
Các bảng chữ cái là lý do khiến hai khóa có thể khác nhau. Một tên component do tác giả viết có thể chứa dấu gạch dưới hoặc chữ hoa; tên release của một chart thì không, và thay vì gộp một ký tự như vậy thành một ký tự tương tự — điều sẽ khiến hai component mà bạn phân biệt được lại có cùng một tên trong cluster — phép suy ra sẽ viết nó ra. Xem ../providers/helm.md “How the release name is derived” để biết bảng chữ cái và giới hạn độ dài riêng của provider đó.
Những provider nào báo cáo một tên, và vì sao các provider khác thì không
helm báo cáo một tên: tên release. Một chart có nguồn đọc tên đó dưới dạng .Release.Name và thường đặt tên các tài nguyên của nó theo tên này, và provider cũng đặt tên mọi tài nguyên mà nó tổng hợp cho một component theo tên đó — controller mang chính tên release, và mỗi Service là <release name>-<service key>. Vì vậy, một địa chỉ được công bố cho bất kỳ loại đầu ra nào cũng được xây dựng từ rendered_name. Với một node chỉ đặt một tập artifact, nó không báo cáo tên nào: các tên trong tập đó là những tên mà tác giả của nó đã viết.
# A synthesized helm Recipe publishing the address of the Service its workload# declares under the key `default`.spec: capability: helm workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "valkey/valkey:8" ports: redis: 6379 services: default: type: ClusterIP ports: redis: 6379 provides: host: "{{ .context.rendered_name }}-default" port: "6379"Một component tên cache công bố cache-default, và một component tên my_cache công bố
my-zucache-default — trong mỗi trường hợp là tên của Service mà bản build tạo ra.
Bốn provider còn lại không báo cáo tên nào, và lý do không giống nhau. Không provider nào trong số đó đang chờ được hỗ trợ — trong mỗi trường hợp, hoặc không có tên dẫn xuất nào để báo cáo, hoặc tên bạn cần đã có thể truy cập theo cách khác.
-
cloudformationvàcompose— bạn đã viết các tên, hoặc định danh chính là tên. Một Recipe cloudformation tự đặt logical id cho các tài nguyên của nó và provider đọc chúng đúng như đã viết; một tệp compose do bạn cung cấp tự đặt tên các service của nó và provider hợp nhất và gắn nhãn tệp đó mà không đổi tên bất cứ thứ gì trong đó. Một workload docomposetổng hợp được đặt tên theo định danh của node, vốn được tệp compose chấp nhận đúng như đã viết, nên{{ .context.instance_id }}chính là tên đó. Không có sự dẫn xuất nào để báo cáo, và các tên là những tên có trong chính tài liệu của bạn. Tên đó là service chính của workload, service mà một peer kết nối tới; một sidecar hoặc init service mà nó mang được đặt tên từ cùng định danh đó và tên của container, nối bằng--, như Cách một sidecar hoặc init service được đặt tên mô tả. -
terraform— tên là một hàm của nơi các tệp được đặt. Khốimodulecủa một contributor được đặt tên theo thư mục đầu ra mà cấu hình của nó được ghi vào, điều này được xác định khi các tệp của boundary được tập hợp chứ không phải khi một node được render. Tại thời điểm các template của một Recipe chạy, vị trí đó chưa tồn tại. -
helm-chart— tên mà nó dẫn xuất là địa chỉ riêng của chart được đặt, một thứ khác với tên mà các template của chart đó render theo. Provider này đặt trườngnamecủa một chart bạn vendor thành định danh đã mã hóa của thứ đã đóng góp nó, đây cũng là alias mà umbrella dùng để liên kết sub-chart đó và là khóa mà các giá trị của nó được đặt phạm vi bên dưới. Với một component, định danh đó là thứ mà{{ .context.instance_id }}mang, nên tên của chart được đặt đã có thể truy cập qua khóa nói rõ nó là gì. Tên mà chính các template của chart được vendor render theo là tên release, do release của umbrella cung cấp lúc cài đặt chứ không phải do provider này dẫn xuất — nên ở đây không có tên như vậy để khóa này báo cáo. Xem../providers/helm-chart.md“The chart name the umbrella owns”.
Đọc khóa ở nơi không có tên nào được báo cáo
Việc đọc {{ .context.rendered_name }} trên một node mà provider của nó không báo cáo tên như vậy sẽ dừng
bản build, và thông báo chẩn đoán cho biết nên viết khóa nào thay thế. Nó không render ra một giá trị rỗng: một
địa chỉ thiếu một đoạn là một artifact sai nhưng vẫn được triển khai, điều đó tệ hơn một bản build dừng lại.
Cách khắc phục mà việc dừng đưa ra phụ thuộc vào node chứ không phụ thuộc vào nơi bạn viết tham chiếu:
- Một node không cung cấp source của riêng nó, dưới một provider không báo cáo tên nào cho nó, có các
tài nguyên được đặt tên theo định danh của nó, nên thông báo dừng nêu
{{ .context.instance_id }}— có một giá trị đúng và thông báo nói rõ điều đó. - Một node có cung cấp source, dưới một provider không suy ra tên nào cho nó, thì không có giá trị thay thế. Thông báo dừng nói rõ điều đó thay vì đưa ra một giá trị, vì việc chỉ bạn đến định danh ở đó sẽ đặt tên cho các tài nguyên mà node của bạn không mang.
Sự từ chối này bao gồm provides: và mọi template khác mà một Recipe viết inline — valuesMapping: của nó,
phần thân workload: của nó, mỗi mục artifacts:, và with: cùng
when: của mỗi bước pipeline.
🔴 Cả hai dạng import đều nằm ngoài phạm vi đó. Một mục valuesMapping:, workload: hoặc artifacts: được cung cấp
thông qua $import: — dù import đó nêu một tệp cục bộ hay một mục thư viện — không mang văn bản nào trong
Recipe của bạn cho đến khi quá trình render phân giải nó, nên một tham chiếu đến khóa này bên trong phần thân như vậy không được kiểm tra.
Nó render tên mà provider của node import báo cáo ở nơi provider đó có báo cáo, và một giá trị rỗng
thay vì dừng ở nơi nó không báo cáo. Do đó, một phần thân được import chỉ đọc khóa này khi mọi Recipe
import nó đều gắn một provider có báo cáo tên — một mục thư viện được viết cho các Recipe helm dùng source là một
chart, và nói rõ điều đó trong phần mô tả. Một phần thân dành cho các bên import mà provider có thể không báo cáo tên thì
lấy tên thông qua một giá trị mà Recipe import đặt ra.
Các mục locals: của một Recipe hoàn toàn không đọc khóa này. Một local dùng chung context với template
source: của Recipe, và việc node có cung cấp source hay không là một trong những điều mà tên phụ thuộc vào, nên
tên không được cung cấp ở đó. Do đó, một tham chiếu đến {{ .context.rendered_name }} trong một local sẽ dừng bất kể
provider báo cáo gì, với thông báo chẩn đoán dành cho tham chiếu mà render context không định nghĩa (E0060),
thông báo này liệt kê .context.instance_id là khóa duy nhất mà .context cung cấp ở đó. Hãy đọc khóa trong mục provides:
hoặc template inline cần đến nó.
Trên các template riêng của một attachment Feature
Trên các template mà FeatureRecipe của một attachment Feature viết — locals:, source:, provides:,
injectMapping:, valuesMapping:, workload:, mỗi mục artifacts:, và with: cùng
when: của mỗi bước pipeline — {{ .context.rendered_name }} là tên của component chủ: tên mà
provider riêng của host báo cáo cho các tài nguyên nó render cho host, cũng là giá trị mà
Recipe riêng của host đọc. Nó đi cặp với {{ .context.instance_id }}, mà trên các template đó là danh tính
của component chủ; bản thân attachment là .attachment_name. Một attachment được viết trên một trong các
kết nối của một component sẽ đọc tên của component tiêu thụ, vì component đó là host của nó.
Đó là khóa dùng để dựng tên tài nguyên riêng của một attachment. Một FeatureRecipe đặt tên một Secret,
một route hay một policy theo component mà nó được gắn vào cần một tên mà nền tảng chấp nhận, và
danh tính của host như được viết không phải là tên như vậy ở bất cứ đâu nó chứa dấu gạch dưới hoặc chữ hoa. Dưới
helm, một component tên my_db báo cáo my-zudb, nên một Secret tên
{{ .context.rendered_name }}-{{ .attachment_name }} cho attachment root được render thành
my-zudb-root, trong khi {{ .context.instance_id }} sẽ cho ra my_db-root, tên mà cluster từ chối.
Giá trị vẫn là của host bất kể attachment render qua provider nào.
Khóa này có mặt ở bất cứ đâu provider của host báo cáo một tên — dưới helm, một host có Recipe cung cấp
một chart hoặc khai báo một workload: — và vắng mặt ở nơi nó không báo cáo tên nào: một host chỉ đặt một tập artifact,
và một host trên bất kỳ provider nào khác. Đọc nó trên một attachment của host như vậy sẽ dừng bản build
với chẩn đoán dành cho một tham chiếu mà ngữ cảnh render không định nghĩa (E0060), liệt kê các khóa
mà .context định nghĩa ở đó. {{ .context.instance_id }} nằm trong số đó, và đó là thứ mà các tài nguyên riêng
của host được đặt tên theo trên host như vậy, nên một FeatureRecipe viết cho các host có thể không báo cáo tên
sẽ đọc danh tính thay thế.
Sự từ chối này bao gồm các template mà một FeatureRecipe viết inline, ngoại trừ injectMapping: của nó. Một
injectMapping:, và một mục valuesMapping:, workload: hoặc artifacts: mà FeatureRecipe cung cấp
qua $import:, không được kiểm tra: trên một host không báo cáo tên, một tham chiếu ở đó render ra một giá trị
rỗng thay vì dừng lại.
Khi một attachment phân phối một chart do tác giả của nó cung cấp, các template của chart đó render theo
tên release của component chủ, một cách có chủ ý: suy ra nó từ attachment sẽ đổi tên
các tài nguyên mà tác giả chart đã khai báo và có thể đã triển khai. .attachment_name là giá trị
phân biệt hai attachment trên cùng một host — xem ../providers/helm.md
“How the release name is derived”.
Các tên suy ra từ attachment của một kết nối
Một attachment mà một kết nối mang theo là một attachment của component tiêu thụ, được đặt tên <alias>.<slot> — gpt.credential cho slot credential của kết nối được viết dưới alias gpt (xem mục kết nối của Aggregate). Tên ghép đó là .attachment_name mà FeatureRecipe của nó render dựa theo, và nó mang theo dấu chấm.
Hai loại tên suy ra từ đó, và chúng xử lý dấu chấm theo cách khác nhau.
Một tên do FeatureRecipe ghép thì giữ nguyên những gì template của nó viết. Các hiện thực credential của thư viện chuẩn đặt tên tài nguyên của chúng là {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, nên credential trên kết nối gpt của một component tên router được render thành một tài nguyên tên router-gpt.credential, kể cả dấu chấm, và đây là một tên đối tượng Kubernetes hợp lệ. Dấu chấm còn lại trong một tên thuộc loại này đúng khi template giữ nó.
Một tên do bản build suy ra từ định danh của attachment thì viết dấu chấm ra thành chữ. Các nhãn định danh và tệp được xuất ra được ghép từ component chủ và tên attachment qua cùng một cách mã hóa mà mọi tên suy ra từ một định danh đều đi qua, và cách mã hóa đó viết dấu chấm thành zd và một chữ hoa thành chuỗi thoát của code point của nó, vì định danh được dùng làm tên tài nguyên cũng như nhãn, và tên Service không chấp nhận cả hai: một kết nối được viết dưới alias gptPro sẽ thành cfr--router--gpt-zx000050ro-zdcredential. Tài nguyên ở trên được gắn nhãn aggrega.ai/component-id: cfr--router--gpt-zdcredential (và app.kubernetes.io/name cũng vậy), và dưới provider helm nó được xuất ra thành router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Xem Quy ước đặt tên “The separator does not reach a name” để biết vì sao dấu chấm được viết ra thành chữ thay vì bị thay thế.
Liên quan
- Hợp đồng ngữ cảnh template — toàn bộ cấu trúc của ngữ cảnh chứa các khóa này.
- Ma trận mở rộng template — mỗi vị trí template đọc những trụ cột nào.
- Bộ ba topology:
provides,inject,uses— cách một giá trị được công bố đi qua một cạnh để đến bên tiêu thụ. - Quy ước đặt tên — những gì bạn có thể viết cho tên một component, và cái giá của một tên dưới một bảng chữ cái hẹp hơn.
errors/fatal-halts.md— điểm dừng mà trang này mô tả, cùng với thông báo được phát ra.