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.

Labels và annotations

Các thực thể Aggrega mang hai cơ chế siêu dữ liệu có cấu trúc tương tự nhau — metadata.labels và metadata.annotations — cùng với các trường mang annotation nằm rải rác trên các bề mặt lan truyền qua ranh giới và các bề mặt gắn feature. Sáu bề mặt riêng biệt khai báo hoặc mang nội dung annotation/label, mỗi bề mặt có quy tắc lan truyền khác nhau, bên sử dụng khác nhau và quy ước tiền tố khác nhau. Trang này mô tả các bề mặt đó tại một chỗ, định nghĩa ba nhóm ngữ nghĩa mà ngữ cảnh template lúc chạy cung cấp, nêu nguyên tắc về tiền tố mà tác giả nên tuân theo, và mô tả năm bề mặt gắn Feature đặt cạnh nhau để chúng hiển thị song song với bộ từ vựng labels/annotations rộng hơn.

Sáu bề mặt mang annotation và label

Tác giả gặp labels và annotations trên sáu bề mặt riêng biệt. Mỗi bề mặt có một phạm vi, một quy tắc lan truyền và một bên tiêu thụ khác nhau.

#Bề mặtPhạm viQuy tắc lan truyềnBên tiêu thụ chính
1metadata.labels của thực thể catalogDanh tính theo từng thực thể (Component, Feature, Aggregate)Không lan truyền xuống các instance; được mang trên chính thực thể catalogaggrega search -l cho Components và Features; nhãn của một Aggregate được mang trong tài liệu của nó và không lệnh nào đọc chúng
2metadata.labels của Component (nội tại)Thuộc tính theo từng instance của Component (component.aggrega.ai/type, v.v.)Lan truyền vào .context.labels của từng node trong IR sau các biến đổi label-transformKhớp selector (các khai báo selector: của usesSchema, được mang dưới dạng x-aggrega-selector: trong JSON Schema được tổng hợp), logic template của Recipe
3metadata.annotations của ComponentĐặc điểm theo từng instance của Component do Architect soạnLan truyền vào bucket .context.annotations.catalog của từng node trong IRcác vai trò phán quyết quản trị (chính sách về đặc điểm nội tại), logic template của Recipe
4annotations: của Aggregate / SubsystemMetadata nhận thức phía AggregateLan truyền vào bucket .context.annotations.aggregate của từng node trong IRvaluesMapping: của Recipe để định tuyến nhận thức
5annotations: của ranh giới ReleaseMetadata vật lý phía Ops, bao gồm các annotation phổ biến aggrega.ai/*Lan truyền vào bucket .context.annotations.release của từng node trong IRProviders (helm đọc aggrega.ai/namespace; compose suy ra tên mạng từ cùng khóa đó); injectMapping: của FeatureRecipe để định tuyến xuyên ranh giới
6Các ràng buộc features.annotations của ManifestRàng buộc khóa annotation → loại Feature, với định tuyến khóa con nhóm theo trụ cột (maps.infra / maps.values) cho việc gắn Feature dựa trên annotationGiai đoạn con mở rộng annotation của quá trình phân giải duyệt qua các ranh giới Release (từ ngoài vào trong) và các subsystem của Aggregate (từ ngoài vào trong); áp dụng ghi đè theo từng component và từ chối bằng null cho toàn bộ giá trị / từng khóa con; việc kiểm soát phía-so-với-trụ-cột quyết định trụ cột nào được kích hoạt theo từng phía soạn thảoMở rộng Feature dựa trên annotation (các lần gắn Feature tổng hợp, được ghi trong đồ thị IR với origin: annotation)

Bề mặt 4 và 5 có cùng hình dạng YAML (một map annotations: tại ranh giới lan truyền) nhưng lan truyền vào các bucket IR riêng biệt — sự phân biệt bucket là quy tắc cốt lõi mà runtime cung cấp. Bề mặt 6 tách biệt về cấu trúc: nó nằm trên thực thể Manifest thay vì trên nội dung Aggregate / Release, và việc tiêu thụ nó được kiểm soát bởi lượt mở rộng dựa trên annotation.

Ngữ nghĩa ba nhóm của .context.annotations.*

Khi trình kết xuất đánh giá một template của Recipe, trường .context.annotations theo từng nút mang ba nhóm có tên. Mỗi nhóm là một ánh xạ phẳng string → string với khóa là tên annotation; nhóm xác định ai đã viết annotation và ý định của nó là gì.

  • .context.annotations.release — các annotation ở ranh giới Release (Bề mặt 5). Dùng để chi phối các thực tế vật lý; trình kết xuất định tuyến chúng vào các trường infra: khi thích hợp. Các annotation phổ biến aggrega.ai/* nằm trong nhóm này.
  • .context.annotations.catalog — các annotation trong metadata của Component (Bề mặt 3). Các đặc điểm nội tại bất biến do Architect viết; chủ yếu được các Plugins chính sách Wasm sử dụng.
  • .context.annotations.aggregate — các annotation của subsystem trong Aggregate (Bề mặt 4). Metadata nhận thức; trình kết xuất định tuyến chúng vào các payload values: khi thích hợp.

Việc tách ba nhóm là một khế ước xã hội

Trình biên dịch không thực thi ranh giới giữa các nhóm. Ba nhóm có cùng dạng phẳng string → string; template của một Recipe có thể đọc cả ba, và không có gì ngăn một annotation ở ranh giới Release bị diễn giải thành một trường metadata nhận thức, hay một annotation của catalog bị định tuyến vào infra:. Sự tách biệt là kỷ luật khi viết, không phải một bảo đảm của trình biên dịch.

Mục tiêu của kỷ luật — điều mà các nhóm được dự định để biểu đạt:

  • release = “component này chạy ở đâu, do Ops chi phối”
  • catalog = “component này là gì, do Architect viết”
  • aggregate = “component này làm gì, do Developer viết”

Khi người viết tôn trọng sự tách biệt, công cụ phía sau có thể đọc đúng nhóm cho đúng mối quan tâm. Khi người viết vi phạm nó (ví dụ: đặt metadata nhận thức vào các annotation release vì tệp Release tiện hơn), runtime vẫn hoạt động nhưng ý định của nhóm bị lẫn lộn.

Socket linter — gắn cờ các lần đọc chéo nhóm

Một plugin linter (tư vấn ngoài luồng; xem plugins/plugin-contract.md về tiêu chí bố trí) có thể gắn cờ các lần đọc chéo nhóm, khi template của một Recipe lấy dữ liệu từ một nhóm có ý định không khớp với trường đang được định tuyến. Tiêu chí:

  • Đọc .context.annotations.release để điền một trường values: — gắn cờ (metadata nhận thức nên đến từ nhóm aggregate).
  • Đọc .context.annotations.aggregate để điền một trường infra: — gắn cờ (metadata vật lý nên đến từ nhóm release).
  • Đọc .context.annotations.catalog để điền values: hoặc infra: — thường chỉ mang tính tư vấn (annotation của catalog là các đặc điểm nội tại; định tuyến chúng vào các trụ cột là bất thường nhưng không phải lúc nào cũng sai).

Linter xuất bản không có quy tắc nào cho tiêu chí này, và build không kiểm tra nó; một plugin linter của riêng bạn có thể làm điều đó, thông qua socket linter mà aggrega lint chạy. Kỷ luật này được duy trì bởi người đánh giá và tác giả tuân theo quy ước về ý định của nhóm.

Kỷ luật tiền tố

Các khóa annotation và label tuân theo một dạng thống nhất <namespace>/<name>. Các họ tiền tố dưới đây cho biết ai viết các khóa dưới mỗi tiền tố và mỗi tiền tố được duy trì như thế nào — một tiền tố được dành riêng, và build dừng lại khi một ràng buộc Manifest hoặc một nhãn đầu ra của Recipe khai báo một khóa mới bên trong nó; các tiền tố còn lại là quy ước của catalog, không có gì từ chối một khóa. Khác biệt giữa hai loại là build có dừng lại hay không, vì vậy hãy đọc cột giữa trước các cột khác.

Tiền tốAi viết khóa ở đâyĐược duy trì như thế nàoMục đíchVí dụ
aggrega.ai/Chỉ nền tảng AggregaĐược dành riêng và được thực thi. Nền tảng định nghĩa các khóa ở đây, và bạn viết những khóa mà nó định nghĩa — chẳng hạn aggrega.ai/namespace trên một boundary của Release. Khai báo một khóa mới bên trong tiền tố sẽ dừng build: cả một ràng buộc features.annotations của Manifest dưới tiền tố trần, lẫn một khóa output-label của Recipe dưới tiền tố đó trong outputLabels: hoặc outputComponentLabels:. Một annotation viết dưới tiền tố này mà nền tảng không định nghĩa sẽ không bị từ chối: build mang nó theo, và khi nó nằm trên một Release, một target không xử lý nó sẽ báo điều đó bằng một cảnh báo. Xem errors/fatal-halts.md “A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Một ràng buộc annotation của Manifest khai báo tiền tố dành riêng)” và “An output-label key uses a reserved namespace (Một khóa output-label dùng một namespace dành riêng)”.Các annotation gốc của nền tảng được provider sử dụng trực tiếpaggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Thư viện chuẩn chính thứcQuy ước. Không có gì từ chối một khóa ở đây; bộ từ vựng thuộc về thư viện chuẩn theo thỏa thuận chứ không phải theo một phép kiểm tra.Các lối tắt Feature-annotation được ràng buộc trong features.annotations của Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Thư viện chuẩn chính thứcQuy ước. Không có gì từ chối một khóa ở đây.Các label đặc điểm nội tại của Component (khóa selector component.aggrega.ai/type nằm ở đây)component.aggrega.ai/type
aggregate.aggrega.ai/Thư viện chuẩn chính thứcQuy ước. Không có gì từ chối một khóa ở đây.Các label định danh cấp module của Aggregateaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Thư viện chuẩn chính thức, và các doanh nghiệp trong catalog của riêng họQuy ước. Không có gì từ chối một khóa ở đây.Các label năng lực — các chiều hành vi mà một selector usesSchema hoặc appliesTo của một Feature dùng để phân biệt. <role> gọi tên mối quan tâm mà chiều đó thuộc về: hoặc một vai trò component, hoặc một mối quan tâm xuyên suốt mà nhiều vai trò cùng chia sẻ.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Doanh nghiệp / cộng đồngMở. Hãy viết dưới một tên miền mà bạn kiểm soát.Annotation và label tùy chỉnhacme.com/billing-tier, corp/cost-center

Tác giả viết annotation tùy chỉnh dùng một tên miền mà họ kiểm soát (thường theo kiểu reverse-DNS). Viết trực tiếp dưới aggrega.ai/ (không có tiền tố con) được dành riêng cho nền tảng; các ràng buộc features.annotations của Manifest cũng không thể ràng buộc khóa trực tiếp dưới aggrega.ai/ — xem entities/manifest.md “Dành riêng tiền tố aggrega.ai/”.

Đặt tên một tiền tố năng lực

Một khóa năng lực có dạng <role>.aggrega.ai/<dimension>, và <role> là phần cần cân nhắc. Ba quy tắc chi phối nó, và quy tắc đầu tiên là quy tắc hay bị hiểu ngược nhất.

  • Gọi tên mối quan tâm, không phải loại component tình cờ mang nó đầu tiên. Khi một chiều mô tả điều mà nhiều loại component cùng chia sẻ, tiền tố gọi tên mối quan tâm chung để loại tiếp theo có được nó sẽ dùng lại bộ từ vựng thay vì tạo ra một bộ song song. component.aggrega.ai/hosting là một mối quan tâm — ai vận hành tài nguyên bên dưới — và mô tả một cơ sở dữ liệu lẫn một model API bằng cùng những từ ngữ; dataplane.aggrega.ai/* gọi tên một vị trí trên đường đi của lưu lượng, nên một proxy, một ingress gateway và một service mesh tự mô tả giống nhau. Một chiều thực sự đặc thù cho một vai trò thì mang tên vai trò đó, như model.aggrega.ai/capability.
  • Một từ viết thường, không có gạch nối, trong tiền tố. Gạch nối thuộc về nửa <dimension>, nơi một từ ghép đọc tự nhiên (request-mirroring, data-class, upstream-licensing).
  • Một chiều được thêm vào khi một selector cần nó, và mỗi giá trị nó khai báo đều có một component mang giá trị đó. Mỗi từ ở đây là một từ mà tác giả catalog phải học và tác giả Feature có thể gặp, nên một chiều xứng đáng có chỗ khi nó phân biệt điều mà một usesSchema hoặc một appliesTo thực sự hỏi đến. Một giá trị không component nào mang còn tệ hơn một giá trị vắng mặt: một selector gọi tên nó vẫn phân tích được, không khớp gì, và không báo gì — vì vậy một giá trị mà catalog không thể minh chứng sẽ bị loại khỏi bộ từ vựng cho đến khi có một component mang nó. Một khóa mà giá trị là tuyên bố của một hệ thống về cách nó dùng các component của chính mình, chứ không phải một thuộc tính của sản phẩm, là ngoại lệ, và compliance.aggrega.ai/data-class là trường hợp đó: dữ liệu của một component thuộc lớp nào phụ thuộc vào cách hệ thống dùng component đó, nên không Component nào của thư viện chuẩn mang bất kỳ giá trị nào của nó và không socket hay Feature nào của thư viện chuẩn chọn theo chúng. Khóa và các giá trị của nó được khai báo để các Components của chính hệ thống và các chính sách nó gắn vào dùng chung một cách viết; một selector hay một chính sách gọi tên một giá trị chỉ khớp trong catalog có các Components mang giá trị đó. policy-data-class-route minh họa một Component như vậy và chính sách đọc nó.

Sự dành riêng và một khóa do nền tảng định nghĩa không phải là một

Sự dành riêng áp dụng cho gốc aggrega.ai/ trần. Mỗi namespace <scope>.aggrega.ai/ bên dưới nó là một không gian khóa riêng mà nền tảng không sở hữu, đó là điều giữ cho bộ từ vựng của catalog có thể mở rộng: một catalog doanh nghiệp có thể viết acme.aggrega.ai/team mà không tranh chấp với bất cứ thứ gì build đóng dấu.

Tuy vậy, một vài khóa bên trong các namespace mở đó được nền tảng định nghĩa và được build đọc, và điều đó không khiến namespace của chúng trở thành dành riêng:

  • component.aggrega.ai/type là bắt buộc trên metadata.labels của mọi Component và nhận một trong một tập giá trị cố định. Các selector khớp theo nó; trình biên dịch không rẽ nhánh theo giá trị mà nó mang.
  • features.aggrega.ai/requiredType.<label>, được viết trên metadata.annotations của một Component, khai báo rằng một Feature thuộc loại được nêu tên phải được gắn vào. Build kiểm tra yêu cầu này với tập gắn kết cuối cùng của mỗi nút và dừng lại khi không có gì thỏa mãn nó — xem errors/fatal-halts.md “Required feature not attached (Feature bắt buộc chưa được gắn)”. Lưu ý dạng số nhiều: features.aggrega.ai/ là một namespace riêng, khác với feature.aggrega.ai/ số ít trong bảng trên, vốn chứa các lối tắt ràng buộc của Manifest.

Hãy hiểu khác biệt như sau: một tiền tố dành riêng từ chối một khóa mà bạn cố định nghĩa bên trong nó, còn một khóa do nền tảng định nghĩa là một khóa có tên mà build biết đến, nằm trong một namespace mà ngoài ra bạn được tự do viết. Mọi khóa khác dưới component.aggrega.ai/, features.aggrega.ai/ và các namespace còn lại là metadata mà build mang theo mà không diễn giải.

Một khóa như vậy trên metadata.annotations của một Component được linter xuất bản chuẩn đọc chứ không phải build: observability.aggrega.ai/metrics-credential cho biết các metric của sản phẩm xác thực như thế nào — none, chúng được phục vụ không cần thông tin xác thực; target-key, chúng dùng khóa mà Component yêu cầu ở mọi bên gọi; separate-token, chúng dùng một token riêng. Build mang nó như mọi annotation khác. Linter đọc nó để quyết định có so sánh thông tin xác thực của một kết nối scrape với khóa bên gọi của đích hay không, và buộc nó phải nhất quán với khóa provides metrics_credential_required mà Component khai báo — xem “Các quy tắc kỷ luật” trong cli/aggrega-lint.md.

Các nhãn nguồn gốc được phát ra trên đầu ra đã render

Ngoài các annotation đầu vào mà các provider sử dụng, Aggrega còn phát ra các nhãn nguồn gốc lên mọi manifest Kubernetes mà provider helm render và mọi service compose được phát ra, và provider helm-chart ghi cùng bộ nhãn đó, giống như provider helm ghi, lên mỗi artifact mà nó nạp bằng $import:. Bộ nhãn này cho phép công cụ phía sau (bảng điều khiển chi phí, ngăn xếp observability, bộ điều khiển GitOps) truy ngược các tài nguyên lúc chạy về nội dung catalog đã tạo ra chúng. Các template riêng của một sub-chart helm-chart được sao chép đúng như tác giả đã viết, nên chúng mang bất kỳ nhãn nào mà tác giả đó đã viết.

Bộ nhãn mà các provider helm và compose phát ra — trên helm, ba trong số các khóa được ghi dưới dạng annotation thay vì nhãn, như bảng cho biết:

NhãnNguồnLuôn được phát ra?
app.kubernetes.io/nameDanh tính Component — tên bạn đã viết, hoặc với một component do một Aggregate được nhập đóng góp thì là tên đủ điều kiện của nó với dấu phân cách module được viết ra (xem bên dưới); hoặc, với một tài nguyên do một FeatureRecipe phát ra, là định danh được suy ra cho lần gắn đóCó trên các manifest Kubernetes; không phát ra trên các service compose (nhãn chuẩn này dành riêng cho K8s)
aggrega.ai/component-idDanh tính Component — tên bạn đã viết, hoặc với một component do một Aggregate được nhập đóng góp thì là tên đủ điều kiện của nó với dấu phân cách module được viết ra (xem bên dưới); hoặc, với một tài nguyên do một FeatureRecipe phát ra, là định danh được suy ra cho lần gắn đóCó
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> của Recipe tạo ra (hoặc FeatureRecipe tạo ra, với các tài nguyên do FR phát ra)Khi thực thể tạo ra có đặt cả tên và phiên bản; là annotation trên helm
aggrega.ai/boundary-pathĐường dẫn boundary mà component được định tuyến vàoKhi đường dẫn boundary không rỗng; là annotation trên helm
aggrega.ai/aggregate-namemetadata.name của AggregateKhi được đặt
aggrega.ai/compiler-versionPhiên bản trình biên dịch được đóng dấu tại thời điểm buildKhi được đặt
aggrega.ai/providerProvider đã render tài nguyên (helm, helm-chart, compose)Có
aggrega.ai/provider-versionPhiên bản của provider đóCó
aggrega.ai/environmentmetadata.environment của ReleaseCó — mọi Release đều khai báo nó
aggrega.ai/sync-waveSố nguyên syncWave theo từng boundary, thứ tự mà công cụ GitOps áp dụng tài nguyênKhi khác 0; là annotation trên helm, bên cạnh argocd.argoproj.io/sync-wave

Tên tập hợp, môi trường, phiên bản trình biên dịch, cùng tên và phiên bản của nhà cung cấp là các chuỗi do bạn hoặc quá trình build chọn, và không chuỗi nào trong số đó bị ràng buộc bởi các quy tắc giá trị nhãn của Kubernetes tại nơi nó được ghi. Trên helm, mỗi nhãn đó mang giá trị đúng như đã viết khi giá trị ấy đã là một giá trị nhãn hợp lệ — chữ cái, chữ số, -, _ và ., một chữ cái hoặc chữ số ở cả hai đầu, tối đa 63 ký tự — còn nếu không thì mang giá trị đã được viết lại thành một giá trị hợp lệ, kèm giá trị nguyên văn được thêm vào dưới dạng chú thích dưới cùng khóa: một Aggregate tên imported/flow được gắn nhãn aggrega.ai/aggregate-name: imported-flow và chú thích aggrega.ai/aggregate-name: imported/flow. Một giá trị đã phù hợp sẵn thì không thêm chú thích nào. Compose mang giá trị nguyên văn làm nhãn. Quy tắc viết lại được nêu tại providers/well-known-annotations.md “Các nhãn nguồn gốc do nhà cung cấp phát ra”.

Với các tài nguyên do một FeatureRecipe phát ra, giá trị aggrega.ai/component-id được xây dựng từ lần gắn chứ không từ tên của component chủ — với mọi cách một FeatureRecipe có thể cung cấp các tài nguyên đó, dù nó tổng hợp một workload, phát ra một bộ artifact độc lập, hay render một chart hoặc một fragment do tác giả của nó cung cấp. Vì vậy một truy vấn chọn tài nguyên của một lần gắn theo định danh sẽ trả về tất cả chúng, và không tài nguyên nào trong số đó bị lẫn với một tài nguyên do chính component chủ phát ra. Cách xây dựng giá trị phụ thuộc vào nơi Feature được gắn; dù theo cách nào, kết quả cũng là một chuỗi nhãn Kubernetes hợp lệ.

Với một component do một Aggregate được import đóng góp, định danh là tên đầy đủ của component đó với dấu phân cách nối module với component được viết ra — data-layer.main-db được đóng dấu thành data-layer-zdmain-db — vì dấu chấm không phải là ký tự mà tên tài nguyên hay địa chỉ cluster có thể mang một cách an toàn. Một tên bạn viết không có dấu phân cách được đóng dấu nguyên từng byte.

Định danh cho biết một tài nguyên thuộc về cái gì. Đó là một câu hỏi khác với việc một tài nguyên được gọi là gì, và với một cách cung cấp, hai câu hỏi này có câu trả lời khác nhau:

  • Khi một FeatureRecipe tổng hợp một workload, Aggrega tự xây dựng các tài nguyên đó, nên nó cũng đặt tên chúng theo định danh: định danh đi vào metadata.name, các nhãn selector và tên tệp được phát ra của chúng, cũng như các nhãn của chúng. Đó là một tên bên trong cluster chứ không chỉ là một nhãn.
  • Khi một FeatureRecipe cung cấp một chart hoặc một fragment do tác giả của nó viết, các tên thuộc về người đã viết nó. Tên Helm release mà các template đó render theo — và tiền tố trên các tệp mà lần render đó phát ra — vẫn là của component chủ. Các chart thường đặt tên tài nguyên theo tên release, nên thay đổi nó sẽ đổi tên các tài nguyên mà chính chart khai báo, trong một cluster nơi chúng đã được triển khai, vì một lý do không liên quan gì đến chart. Các nhãn vẫn mang định danh riêng của lần gắn, và chính điều đó giúp tài nguyên của lần gắn vẫn tìm được.
  • Khi Feature được gắn vào một boundary, không có component chủ nào có tên để thay thế, nên định danh được ghép là cơ sở đặt tên ở đó, cũng như là nhãn.

Dù theo cách nào, giá trị được ghép từ các phần bạn đã viết, nối bằng --, sau một phần mở đầu cố định cho biết đó là trường hợp nào trong hai trường hợp. Có hai phần mở đầu được dùng, và một định danh component bạn viết không được mở đầu bằng phần nào trong số đó — chính điều này giữ cho một tên bạn viết và một tên Aggrega ghép không bao giờ bị nhầm lẫn với nhau.

Khi Feature được gắn vào một component, các phần là phần mở đầu cố định cfr, định danh của component mà Feature được gắn vào, và khóa mà nó được gắn dưới đó. Một Feature gắn vào component api dưới mon cho ra cfr--api--mon. Component chủ là một phần của giá trị vì một tên Feature gắn vào nhiều component sẽ phát ra một bộ tài nguyên riêng trên mỗi component, và mỗi bộ cần một định danh riêng: gắn mon vào cả api và worker cho ra cfr--api--mon và cfr--worker--mon thay vì một giá trị cho cả hai. Cũng vì lý do đó, một lần gắn được đặt tên đúng bằng tên component chứa nó cho ra một giá trị khác với giá trị riêng của component đó — mon gắn vào mon cho ra cfr--mon--mon.

Khi Feature được gắn vào một boundary — service gateway compose-bridge là ví dụ điển hình — các phần là phần mở đầu cố định bfr, rồi từng đoạn của đường dẫn boundary, ngoài cùng trước, rồi tên mà Feature được gắn dưới đó. Một Feature tên gateway trên một boundary tại bridge cho ra bfr--bridge--gateway; cùng Feature đó trên một boundary tại prod/eu cho ra bfr--prod--eu--gateway.

Một ký tự mà giá trị không thể mang sẽ được viết triển khai thay vì bị thay thế, và vì giá trị vừa là nhãn vừa là một tên bên trong cluster, nó bị giới hạn trong các ký tự mà mọi loại tên tài nguyên Kubernetes đều chấp nhận: chữ thường, chữ số và dấu gạch nối. Vì vậy, một dấu gạch nối bạn viết vẫn là dấu gạch nối, một chữ thường hoặc chữ số giữ nguyên, còn mọi thứ khác — kể cả chữ hoa, thứ mà giá trị nhãn chấp nhận nhưng tên tài nguyên từ chối — trở thành một chuỗi thoát ngắn: một attachment tên my_zone đóng góp my-zuzone, và một component myApi có attachment worker nhận giá trị cfr--my-zx000041pi--worker. Giá trị đã thoát đó là giá trị mà các tài nguyên của attachment được gắn nhãn và được chọn theo trên mọi target, là giá trị mà một workload do attachment tổng hợp được đặt tên và lưu tệp theo, và là giá trị mà tên release của một attachment trên boundary được suy ra từ đó. Chữ hoa là ký tự duy nhất mà quy tắc tên tài nguyên bổ sung vào những gì một nhãn đơn thuần sẽ viết triển khai, nên một giá trị ghép mà các phần không chứa chữ hoa nào — cfr--api--mon, bfr--prod--eu--gateway — chính là giá trị mà một nhãn đơn thuần sẽ mang. Do đó, hai attachment mà bạn có thể phân biệt sẽ nhận hai giá trị — dù bạn đặt tên chúng thế nào và boundary nằm sâu đến đâu — vì -- là một chuỗi mà không phần nào được viết có thể chứa, nên việc dịch chuyển ranh giới giữa các phần sẽ làm thay đổi giá trị thay vì gây xung đột.

Một giá trị được ghép có thể dài bao nhiêu là câu trả lời của target chứ không phải một con số do Aggrega nắm giữ: target mà các tài nguyên được render cho sẽ được hỏi, và giá trị được rút ngắn cho đến khi target đó chấp nhận. Một giá trị nhãn Kubernetes mang tối đa 63 ký tự, và một tên Helm release suy ra từ cùng định danh còn bị giới hạn chặt hơn nữa, nên cùng một lần gắn có thể có giá trị ngắn hơn dưới target này so với target khác. Một giá trị vừa vặn được phát ra đúng như khi ghép, đây là trường hợp thông thường và là trường hợp của mọi lần gắn trong catalog thư viện chuẩn. Giá trị không vừa sẽ bị rút ngắn: mỗi phần giữ lại phần đầu của nó, và một digest mười ký tự của toàn bộ định danh được nối vào sau một dấu đánh dấu mà không tên nào bạn có thể viết tạo ra được — nên một giá trị đã rút ngắn có thể nhận ra là như vậy và không bao giờ bị đọc nhầm là một giá trị vừa vặn. Do đó một lần gắn gateway lồng sâu có thể được render thành bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Hai giá trị đã rút ngắn rất khó trùng nhau, và nếu trùng, build sẽ dừng thay vì để hai giá trị đó dùng chung một tên.

Xem errors/fatal-halts.md “The same name is derived more than once inside the output (Cùng một tên được suy ra nhiều lần trong đầu ra)” để biết cặp nào gây dừng và cách tách chúng.

aggrega.ai/recipe-uri của một tài nguyên do FR phát ra phân giải thành name:version riêng của FeatureRecipe, không phải định danh của Recipe sử dụng nó — nên công cụ phía sau đọc recipe-uri để xác định thực thể tạo ra sẽ nhận được nguồn gốc chính xác cho cả đầu ra do component phát ra lẫn đầu ra do FR phát ra.

Để biết chi tiết phát ra theo từng provider (các nhãn nằm ở đâu trên đầu ra đã render, và mỗi provider tuần tự hóa chúng ra sao), xem providers/well-known-annotations.md “Provenance labels emitted by providers”.

Nhãn đầu ra do Recipe khai báo

Bên cạnh tập nhãn nguồn gốc do trình biên dịch sở hữu, tác giả Recipe có thể khai báo các nhãn riêng để gắn lên đầu ra được kết xuất của Recipe, thông qua Recipe.spec.outputLabels:. Các nhãn này đi cùng đường phát ra với các nhãn nguồn gốc — chúng được hợp nhất vào cùng tập nhãn và xuất hiện ở bất cứ đâu nhãn nguồn gốc xuất hiện — nhưng chúng thuộc quyền sở hữu của tác giả chứ không phải của trình biên dịch. Mục đích sử dụng dự kiến là một đặc điểm hiện thực hóa: một thuộc tính về cách một Recipe cụ thể hiện thực hóa một component (ví dụ hosting: managed so với hosting: self-hosted cho một Recipe dịch vụ được quản lý so với một Recipe chart tự lưu trữ của cùng một loại component), được hiển thị trên đầu ra để các công cụ chi phí, chính sách và kiểm kê có thể truy vấn.

Các không gian tên aggrega.ai/ và app.kubernetes.io/ được dành riêng cho tập nhãn nguồn gốc; một khóa thuộc một trong hai tiền tố này bị từ chối khi nạp — trong outputLabels: và trong outputComponentLabels:, khối đi kèm dùng để đặt tên một khóa nhãn component và gắn giá trị mà chính component khai báo. Do đó, một tập nhãn đầu ra đã được xác thực luôn tách biệt với các khóa nguồn gốc, nên hai tập không bao giờ xung đột trên đầu ra đã hợp nhất. Phép kiểm tra dựa trên gốc trần: một khóa có phạm vi như component.aggrega.ai/hosting nằm trong một không gian tên riêng và có thể được viết trực tiếp hoặc được nâng lên. Việc hiển thị theo từng provider (đối tượng helm và pod-template khi tổng hợp; đối tượng khi source-render và với artifact; nhãn dịch vụ compose; thẻ terraform theo từng tài nguyên trên phần thân artifact .tf.json) khớp với vị trí của nhãn nguồn gốc, và được mô tả đầy đủ trên trang thực thể Recipe trong mục “Trường outputLabels:” và “Trường outputComponentLabels:”.

Đính kèm Feature — năm bề mặt

Features được đính kèm vào Components thông qua năm bề mặt soạn thảo riêng biệt, mỗi bề mặt có phạm vi, người dùng dự kiến và thứ tự ưu tiên khác nhau trong Mô hình Củ hành 5 tầng. Toàn bộ thứ tự đính kèm và bản thân Mô hình Củ hành được mô tả tại architecture/10-compilation-pipeline.md; bảng dưới đây liệt kê song song năm bề mặt.

TầngBề mặtNgười soạnPhạm viQuy tắc lan truyền
1Khối features: của component trong AggregateDeveloperTheo từng instance component (chi tiết)Không có — tác giả khai báo trực tiếp
2Khối features: của subsystem trong AggregateDeveloperPhạm vi subsystem (xuyên suốt trong Aggregate)Lan truyền tới mọi component trong subsystem
3Boundary của Release components.<id>.featuresOpsTheo từng instance component (chi tiết, phía Ops)Không có — tác giả khai báo trực tiếp
4Khối features: của boundary trong ReleaseOpsPhạm vi boundary (xuyên suốt trong boundary)Lan truyền tới mọi component trong boundary
5Mở rộng features.annotations của ManifestPlatform OperatorDựa trên annotation (đính kèm tổng hợp)Lan truyền qua cây boundary (phía Release) hoặc cây subsystem (phía Aggregate); áp dụng ghi đè theo từng component và từ chối bằng null theo từng khóa con

Năm bề mặt này cộng dồn; một phần đính kèm có mặt ở bất kỳ bề mặt nào đều đóng góp vào tập feature đã phân giải của Component. Khi cùng một tên instance Feature xuất hiện trên nhiều bề mặt, các đóng góp được hợp nhất thành một phần đính kèm thay vì thay thế lẫn nhau, và sự không khớp kiểu giữa chúng sẽ dừng bản build với lỗi xung đột hợp nhất feature.

Năm bề mặt này là có chủ đích theo sự phân tách trách nhiệm của kiến trúc — Developer (tầng 1-2), Ops (tầng 3-4), Platform Operator (tầng 5) — chứ không phải dư thừa. Tác giả chọn bề mặt phù hợp với người sở hữu phần đính kèm và phạm vi của nó.

Những label nào quyết định một Feature có áp dụng hay không

Một Feature khai báo nơi nó có thể được đính kèm bằng spec.appliesTo và spec.appliesToAnyOf, và bản build đánh giá khai báo đó dựa trên các label đã hoàn tất của node mà phần đính kèm rơi vào. Đính kèm một Feature vào một node mà các label đó không thỏa mãn sẽ dừng bản build; một Feature không khai báo bề mặt nào trong hai bề mặt này thì không nêu yêu cầu nào và áp dụng ở mọi nơi.

Tập label đã hoàn tất được lắp ráp qua hai bước, và không bước nào là bước mà tác giả thường giả định nhất.

  1. Một node lấy label từ entity catalog Component mà type: của nó chỉ tới. Chúng là thuộc tính của kiểu component, không phải của instance: Aggregate không thể gắn label cho một instance component, và Release cũng không thể. metadata.labels riêng của một Aggregate mô tả Aggregate như một module tái sử dụng được và không lan truyền tới các component bên trong nó. Vì vậy hai instance của cùng một kiểu mang label giống hệt nhau, và muốn thay đổi label của một node nghĩa là thay đổi kiểu mà nó trỏ tới — hoặc thay đổi entity của kiểu đó.
  2. Sau đó một phần đính kèm label-transform có thể viết lại chúng. Khi cấu hình workspace đính kèm một plugin quản trị với vai trò label-transform, plugin đó chạy trong lúc dựng topology và có thể thêm, thay đổi hoặc xóa label của node trước khi bất cứ điều gì được đánh giá dựa trên chúng. Nó không được chạm vào thứ gì khác, nên label là phần duy nhất của node mà nó có thể thay đổi — và đó chính là phần mà khả năng áp dụng phụ thuộc vào.

Vì vậy, một đề xuất dựa trên các label mà một tài liệu đơn lẻ khai báo chỉ là một phép xấp xỉ, không phải một dự đoán. Đọc metadata.labels của một entity Component cho bạn biết một node thuộc kiểu đó khởi đầu với những gì, đây là câu trả lời đúng đủ thường xuyên để hữu ích nhưng sai theo hai cách cụ thể: một tài liệu chỉ trùng tên với một node là một đối tượng khác với các label khác, và một phần đính kèm label-transform có thể thay đổi tập label mà không phụ thuộc vào bất kỳ tài liệu nào. Các công cụ đưa ra gợi ý đính kèm chỉ từ mã nguồn đang làm việc với phép xấp xỉ đó; phán định mà bản build đưa ra dựa trên tập đã hoàn tất.

Thứ tự ưu tiên của phần đính kèm

Khi hai đóng góp cùng cung cấp một trường của cùng một phần đính kèm, bốn quy tắc quyết định đầu ra được render sẽ mang giá trị nào. Chúng được áp dụng theo thứ tự này, và chính thứ tự đó làm cho kết quả có thể dự đoán được:

  1. Nguồn gốc. Một đóng góp được soạn tường minh thắng một đóng góp dựa trên annotation, bất kể mỗi bên được khai báo ở phạm vi nào. Viết một trường vào khối features: là cách tác giả ghi đè những gì một annotation lẽ ra sẽ đóng góp, và một annotation không bao giờ âm thầm thay thế thứ được viết tay. Compiler ghi lại annotation bị loại bỏ cùng với giá trị thắng và báo cáo nó dưới dạng khuyến cáo, để việc ghi đè hiển thị rõ ràng thay vì khó hiểu.
  2. Quyền sở hữu trụ cột. Mỗi miền điền vào trụ cột của riêng mình: các bề mặt Aggregate đóng góp values, các bề mặt Release đóng góp infra. Vì hai bên không bao giờ ghi cùng một trụ cột, một đóng góp của developer và một đóng góp của operator không thể tranh chấp cùng một trường — không có câu hỏi ưu tiên giữa developer và operator cần giải đáp.
  3. Thẩm quyền kết hợp. Một khai báo trong Aggregate mà bạn đang triển khai có thứ hạng cao hơn một khai báo bên trong Aggregate mà nó kết hợp, kể cả khi Aggregate được kết hợp khai báo ở phạm vi hẹp hơn. Sự kết hợp giữ thẩm quyền: một module không thể đánh bại Aggregate sử dụng nó chỉ bằng cách chọn phạm vi hẹp hơn.
  4. Độ cụ thể. Trong cùng một cấp soạn thảo và một trụ cột, phạm vi hẹp hơn tinh chỉnh phạm vi rộng hơn, theo từng trường. Một phần đính kèm ở phạm vi component ghi đè một phần đính kèm toàn subsystem hoặc toàn boundary có cùng tên instance — nhưng chỉ với những trường mà nó thực sự nhắc tới. Các trường mà phạm vi hẹp hơn bỏ qua giữ giá trị của phạm vi rộng hơn, nên một phần đính kèm dùng chung có thể cung cấp cấu hình chung trong khi một component đơn lẻ điều chỉnh một trường trong đó. Hai đóng góp ở cùng phạm vi được phân giải theo thứ tự soạn, với đóng góp sau thắng, đây là điều cho phép một subsystem bên trong tinh chỉnh subsystem bên ngoài và một boundary sâu hơn tinh chỉnh boundary nông hơn.

Thứ tự ưu tiên chi phối giá trị của trường. Nó không sắp xếp lại quá trình đánh giá: trình tự mà compiler gộp các bề mặt, và trình tự mà nó thực thi injectMapping trước render của mỗi phần đính kèm, là trình tự năm tầng cố định được mô tả trong architecture/10-compilation-pipeline.md. Khối inject được soạn của một phần đính kèm tuân theo trình tự đánh giá đó thay vì thứ hạng phạm vi ở trên, nên một phần đính kèm không bao giờ mang hai thứ tự cạnh tranh nhau.

Những loại nào mang metadata.labels và metadata.annotations

metadata.labels có trên Component, Feature, Aggregate và bốn loại thư viện; metadata.annotations có trên cùng các loại đó trừ Aggregate. Manifest, Release, Recipe, FeatureRecipe và Plugin không mang cái nào.

Tóm tắt về cascade

Các quy tắc cascade trên sáu bề mặt, theo cách trình biên dịch đánh giá:

  1. Nhãn của thực thể catalog (Bề mặt 1) ở lại trên thực thể catalog. Chúng không truyền xuống các instance; bên sử dụng đọc chúng bằng cách kiểm tra trực tiếp nội dung catalog.
  2. metadata.labels của Component (Bề mặt 2) truyền vào .context.labels của từng node sau lượt label-transform tùy chọn trong quá trình xây dựng topology.
  3. metadata.annotations của Component (Bề mặt 3) truyền vào bucket .context.annotations.catalog của từng node.
  4. annotations: của Aggregate / Subsystem (Bề mặt 4) cascade qua hệ phân cấp subsystem, tích lũy từ các subsystem bên ngoài vào trong, vào bucket .context.annotations.aggregate của từng node.
  5. annotations: của boundary trong Release (Bề mặt 5) cascade qua hệ phân cấp boundary từ các boundary bên ngoài vào trong, vào bucket .context.annotations.release của từng node.
  6. features.annotations của Manifest (Bề mặt 6) không cascade trực tiếp xuống dữ liệu IR của từng node; pha con mở rộng dựa trên annotation của quá trình phân giải sử dụng các binding để tổng hợp các attachment Feature cho từng node, được đồ thị IR (--ir-graph) ghi lại với origin: annotation. Sau quá trình phân giải, các attachment tổng hợp này không thể phân biệt về mặt cấu trúc với các attachment tường minh, ngoại trừ qua provenance đó — xem providers/well-known-annotations.md để biết toàn bộ nội dung về việc mở rộng và architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion” để biết cơ chế lúc nạp catalog và lúc kiểm tra.

Để biết thiết kế chuẩn về annotation dạng cascade, xem architecture/06-data-taxonomy-and-composition.md §2 (Flow 5).

Tham chiếu chéo