aggrega inspect
aggrega inspect hiển thị một khung nhìn dễ đọc cho con người của bất kỳ thực thể Aggrega nào — một Component trong catalog, một tệp thực thể do bạn soạn, một thực thể được phát hành trong registry, hoặc một Release đã được phân giải đầy đủ. Đây là bề mặt gỡ lỗi chuẩn để hiểu những gì trình biên dịch sẽ tạo ra: Components nào mở rộng base nào, Recipe nào ánh xạ tới từng kiểu, Features nào gắn vào từng nút, và chính xác các đóng góp của mỗi Feature đến từ đâu.
Mỗi loại thực thể có một khung nhìn “hợp đồng” tự nhiên. inspect hiển thị hợp đồng đó — schema mà một Component công bố, các ánh xạ mà một Manifest khai báo, topology mà một Aggregate xây dựng, các phần gắn Feature theo từng nút mà một Release phân giải thành. Tài liệu hướng dẫn và khái niệm nằm ở nơi khác; inspect trả lời câu hỏi “thực thể này thực sự được phân giải thành gì?”
Một đối số vị trí duy nhất được định tuyến theo hình dạng nội dung; không cần lệnh con. Lệnh phân phối theo quy tắc kinh nghiệm sau:
| Hình dạng định danh | Phân phối | Đầu ra |
|---|---|---|
Bắt đầu bằng ./, ../, hoặc /, hoặc kết thúc bằng .yaml / .yml | Nhánh tệp | Kiểm tra theo từng tệp, dựa trên header kind: của tệp. |
Bắt đầu bằng oci:// | Nhánh registry | Thực thể được phát hành tại tọa độ đó, đọc từ registry của nó và hiển thị bằng khung nhìn mà một tệp cùng loại nhận được. Xem Đọc một thực thể đã phát hành. |
| Mọi trường hợp khác | Nhánh catalog | Tra cứu định danh trong ngăn xếp tìm kiếm catalog trên mọi loại thực thể; phân giải các chuỗi extends:; hiển thị khung nhìn riêng của loại khớp được. |
Ba mức chi tiết
--list, mức mặc định và --detail tạo thành một nguyên tắc ba mức độ chi tiết thống nhất mà mọi loại entity đều tuân theo. --list và --detail loại trừ lẫn nhau — truyền cả hai sẽ bị từ chối thay vì được giải quyết ngầm.
--list— chỉ các định danh. Một Component liệt kê tên của nó và tên các uses-socket; một MappingLibrary liệt kê tên các mapping; một Aggregate liệt kê tên các component cùng với type của chúng.- mặc định — một bản tổng quan có cấu trúc, được điều chỉnh cho việc sử dụng tương tác. Nó mở đầu bằng danh tính của entity và, với mọi loại trừ Manifest và Release, phần mô tả của nó nếu entity có viết; một entity không có mô tả sẽ không in gì thay vì in một dòng trống. Phần còn lại của hình dạng tùy theo từng loại: một Component hiển thị schema và các socket; một Aggregate hiển thị các component, giá trị của chúng và các cạnh cùng với các attachment mà mỗi kết nối mang theo, và đồ thị phụ thuộc; một Release hiển thị cây node theo từng boundary với các attachment của Feature, mỗi attachment được viết trên một kết nối sẽ được liệt kê bên dưới kết nối đó.
--detail— toàn bộ nội dung các trường. Mọi thứ mà loại đó mang theo: một Component bổ sung các cơ chế self-inject, các Features bắt buộc và các label; một MappingLibrary mở rộng toàn bộ phần thân template của mỗi mapping; một Recipe bổ sung phần thân workload, provides và các assertion.
Một số loại dùng các mức này để hiển thị dần dần nhiều hơn phần thân đã viết. Một MappingLibrary ở mức --list hiển thị tên các mapping; ở mức mặc định, nó bổ sung ví dụ sử dụng được tổng hợp cho mỗi mapping; ở mức --detail, nó mở rộng toàn bộ phần thân template.
Phân giải: --raw và --resolved
Mỗi loại có một độ sâu phân giải mặc định tự nhiên (xem bảng bên dưới). --raw và --resolved là các tùy chọn ghi đè luôn có sẵn, và chúng loại trừ lẫn nhau — truyền cả hai sẽ bị từ chối thay vì được âm thầm giải quyết:
--rawbỏ qua mọi phân giải — thực thể được xuất ra đúng như khi được viết, lấy thẳng từ tệp.--resolvedbật độ sâu phân giải đầy đủ của loại đó.
Với các loại mặc định hiển thị như khi được viết, --raw không có tác dụng và --resolved kích hoạt mức phân giải mà loại đó hỗ trợ. Với các loại mặc định đã phân giải, --raw là cách bỏ qua để xem như khi được viết.
--raw tái tạo lại tệp, nên một giá trị mà tác giả đã khai báo là nhạy cảm sẽ xuất hiện trong đó đúng như khi được viết. Đó là cam kết, không phải một thiếu sót — một chế độ xem như khi được viết mà lặng lẽ giữ lại một phần của chính nó thì không còn là như khi được viết. Hãy xử lý đầu ra của --raw theo cách bạn xử lý tệp thực thể mà nó được lấy từ đó. --output yaml cũng tái tạo lại tệp theo cách tương tự, với mọi loại, kể cả một Release.
Một Release trả lời thêm hai câu hỏi nữa, và mỗi câu là một tài liệu khác nhau với cờ riêng. Đồ thị đã biên dịch mà một Release phân giải thành là --ir-graph; bao đóng phụ thuộc của nó là --closure. Xem Đầu ra máy đọc được và Bao đóng phụ thuộc: --closure bên dưới.
Giá trị mặc định theo từng loại
inspect nhận biết các loại có thể kiểm tra độc lập trong bảng dưới đây. Các loại thuộc catalog mặc định được hiển thị đúng như khi tạo — các tệp của chúng là những hợp đồng tự chứa. Các loại instance mặc định hiển thị dạng đã phân giải, vì YAML được tạo ra của chúng chỉ là điểm khởi đầu cho một chuỗi cascade hoặc một pipeline.
| Loại | Mặc định | “Đã phân giải” nghĩa là gì |
|---|---|---|
| Component | như khi tạo | Tệp là một hợp đồng tự chứa; việc phân giải được thực hiện dựa trên một ràng buộc Manifest, hiển thị qua --show-implements. |
| Feature | như khi tạo | Giống như Component. |
| Recipe | như khi tạo | --show-implements phân giải tham chiếu Component trong spec.implements. |
| FeatureRecipe | như khi tạo | --show-implements phân giải tham chiếu Feature trong spec.implements. |
| MappingLibrary | như khi tạo | Các mục là chuỗi Go-template không được diễn giải; việc render diễn ra tại thời điểm sử dụng. |
| SchemaLibrary | như khi tạo | Các mục là các định nghĩa schema và template có thể tái sử dụng, được phân giải tại thời điểm sử dụng. |
| WorkloadLibrary | như khi tạo | Các mục là các phần thân Workload tái sử dụng được mà một Recipe import, được đánh giá tại thời điểm sử dụng. |
| ArtifactLibrary | như khi tạo | Các mục là các gói artifact tái sử dụng được mà một Recipe import, được render tại thời điểm sử dụng. |
| Plugin | như khi tạo | Tệp là một hợp đồng plugin tự chứa: các loại socket, capability theo từng export, các ràng buộc runtime và con trỏ chữ ký. Có thể truy cập theo đường dẫn tệp, hoặc theo tọa độ <pluginType>/<name> của nó trong catalog. |
| Manifest | đã phân giải | Chuỗi extends: được áp dụng; các ánh xạ component và feature đã phân giải được trình bày ra. |
| Aggregate | đã phân giải | Topology được xây dựng — uses-graph và thứ tự được tính toán. |
| Release | đã phân giải | Toàn bộ pipeline chạy: phân giải, mở rộng annotation, chạy guard, xây dựng topology, xây dựng IR. |
Một tệp có kind: là Workload sẽ bị từ chối: một Workload chỉ tồn tại khi được nhúng trong một Recipe và không phải là một thực thể có thể kiểm tra độc lập. Hãy kiểm tra một Recipe để xem Workload của nó.
Độ sâu phân giải theo từng loại
Hầu hết các loại không có pipeline — inspect đọc tệp và hiển thị nó. Ba loại thực thể được phân giải một cách có ý nghĩa:
- Manifest áp dụng chuỗi
extends:của nó — theo dõi việc nhập tệp — và hiển thị các ánh xạ component và feature đã được hợp nhất.--rawhiển thị tệp như khi được viết. - Aggregate xây dựng topology của nó: đồ thị uses được dựng và thứ tự phụ thuộc được tính toán. Chế độ xem mặc định hiển thị các component cùng giá trị và cạnh của chúng, tiếp theo là đồ thị phụ thuộc.
--rawhiển thị cây hệ thống con như khi được viết. - Release chạy toàn bộ pipeline biên dịch cho tới IR — phân giải, mở rộng annotation, chạy guard, xây dựng topology, xây dựng IR — và hiển thị cây node theo từng ranh giới cùng các Feature attachment của mỗi node và nguồn gốc của chúng. Các attachment quản trị định hình đồ thị được chạy trong pipeline đó thay vì bị bỏ qua cho một chế độ xem, nên những gì bạn đọc phản ánh những gì chúng đã quyết định: các nhãn của một attachment
label-transformđã có mặt trước khi bất cứ thứ gì được so khớp với chúng, và các annotation được chèn bởi một attachmentannotation-transformmở rộng thành các Feature attachment đúng như một annotation do bạn viết. Một attachment có plugin mà lệnh này không thể phân giải sẽ dừng lệnh, thay vì để lại cho bạn một đồ thị được vẽ mà không có các quyết định của plugin đó. Một Release mở rộng một Release khác được vẽ, trong chế độ xem này và trong--ir-graph, thành Release mà chuỗiextends:của nó hợp thành — chính Release mà một bản build của nó đọc — nên một Release chỉ nêu tên cha của nó sẽ hiển thị Aggregate, Manifest và các ranh giới của cha đó dưới tên của chính nó. Manifest mà một Release nêu tên cũng được hợp thành qua chuỗiextends:riêng của nó, dù Release có mở rộng gì hay không, nên một attachment có mapping mà Manifest đó kế thừa sẽ hiển thị phần hiện thực mà bản build sử dụng.--rawxuất nguyên văn tệp Release mà không chạy pipeline.--closuređặt một câu hỏi khác về cùng Release đó và hoàn toàn không chạy pipeline; xem Bao đóng phụ thuộc:--closure.
Không có cờ độ sâu riêng; nút chuyển --raw / --resolved là cơ chế điều khiển phân giải duy nhất, được đặt chồng lên giá trị mặc định tự nhiên của từng loại.
Hành vi khi gặp lỗi
Một tệp liên quan được tham chiếu mà không tải được sẽ dừng lệnh ngay lập tức — một Release trỏ tới một Aggregate bị thiếu, một thực thể catalog bị hỏng trong ngăn xếp tìm kiếm. Lệnh dừng với một thông báo rõ ràng thay vì hiển thị đầu ra không đầy đủ, và không có chế độ tiếp tục khi lỗi cho một lần tải thất bại: một khi tài liệu mà quá trình phân giải cần không đọc được, sẽ không còn gì để phân giải thêm. Khi việc phân giải một tên dừng lại ở một tài liệu catalog mà quá trình tải từ chối, thông báo nêu sự từ chối đó một lần: một phần đầu mang danh mục và, nếu sự từ chối nêu tên một điều kiện, mã ngắn của nó, sau đó là tài liệu, rồi điều sai trong tài liệu đó — với một tài liệu bị schema của kind của nó từ chối, đó là dòng và ràng buộc mà nó vi phạm. Thông báo không kèm gợi ý di chuyển tệp — catalog đã đọc tệp đó, chính vì vậy mà tệp bị từ chối.
Một Release có thành phần bị các kiểm tra của trình biên dịch bác bỏ sẽ bị từ chối thay vì được hiển thị. Việc phân giải một Release sẽ dựng đồ thị, và các kiểm tra mà một lần build thực hiện trên đồ thị hoàn chỉnh — một cạnh uses: có đích không thỏa mãn selector: của socket, một Feature được gắn vào một component mà appliesTo: của nó không chấp nhận, và các kiểm tra còn lại — cũng được thực hiện ở đây, với cùng chẩn đoán mà một lần build trên cùng các tài liệu in ra. Sự từ chối nêu tên mọi phát hiện trong một lần chạy thay vì dừng ở phát hiện đầu tiên, nên một lượt cho bạn thấy toàn bộ danh sách cần sửa thay vì chỉ mục đầu tiên. Đó là điều giúp lệnh này trung thực về một lần triển khai: một khung nhìn hiển thị một thành phần mà lần build từ chối sẽ báo một workspace là ổn trong khi thực tế không phải vậy. Các lựa chọn không phân giải gì thì không bị ảnh hưởng — --raw, --output yaml và --closure tái hiện hoặc phân giải những gì bạn đã viết mà không dựng đồ thị.
Một Release có lockfile không còn khớp với kết quả phân giải của nó sẽ bị từ chối bằng điểm dừng mà aggrega build in ra. Khi có một lockfile nằm cạnh Release, mọi lựa chọn phân giải Release — chế độ xem mặc định, --resolved, --ir-graph và --closure — đều buộc lockfile phải khớp với kết quả phân giải của Release, bằng phép so sánh độ lệch mà một bản build chạy trước khi render. Một lockfile không còn khớp sẽ dừng lệnh bằng lần từ chối E0130 của bản build: mọi mục đã bị lệch, sau đó là lệnh aggrega pull --release <release> để khắc phục nó. Không có gì được ghi ra đầu ra chuẩn và lệnh thoát với mã khác không, vì một bức tranh được vẽ từ danh mục ở trạng thái hiện tại sẽ cho thấy điều mà không bản build nào của Release đó render. Riêng --raw và --output yaml không đọc lockfile cũng không đọc danh mục, và không bị buộc phải khớp với nó. Một Release không có lockfile nằm cạnh sẽ được phân giải dựa trên danh mục ở trạng thái hiện tại.
Một tệp có kind: không được nhận diện sẽ báo kind không xác định và tệp chứa nó. Một tệp Workload báo rằng kind này chỉ dùng dạng nhúng và nêu tên thực thể mà nó được nhúng vào. Một định danh oci:// không đọc được sẽ bị từ chối kèm điều kiện nêu lý do; Đọc một thực thể đã xuất bản liệt kê các điều kiện đó.
Phân giải catalog
Ngăn xếp tìm kiếm catalog được lắp ghép theo thứ tự ưu tiên phân tầng: các cờ --catalog (được thêm vào đầu, theo thứ tự) đứng trước, sau đó là catalog_dirs của workspace từ .aggrega-config.yaml — với một Release mà cấu hình cung cấp các thư mục riêng dưới workspace.releases, thì các thư mục của Release đó thay vào vị trí này — rồi đến thư mục catalog ở gốc workspace, thư mục này được đọc dù có gì nhắc đến nó hay không. Một workspace có catalog_dirs được viết là một danh sách rỗng sẽ không đọc catalog cục bộ nào cả. Ngăn xếp hoạt động theo kiểu cái đầu tiên thắng — thư mục sớm nhất khai báo một định danh thực thể sẽ sở hữu nó; bản sao của một thư mục sau bị che khuất. Nhánh catalog phân giải định danh theo ngăn xếp này trên mọi loại thực thể, theo một thứ tự ưu tiên cố định, và hiển thị kết quả khớp đầu tiên qua chế độ xem riêng của loại đó; các nhánh tệp và release nạp các thực thể catalog được tham chiếu từ ngăn xếp này khi cần phân giải một ánh xạ Manifest hoặc một cha extends:. Một cha extends: mà ngăn xếp không chứa sẽ được đọc ở nơi một bản build đọc nó: từ bộ nhớ đệm artifact, dưới pin mà lockfile của một Release ghi lại cho nó — lockfile của Release được chỉ định, hoặc của mọi Release mà workspace chứa khi không có Release nào được chỉ định. Vì vậy, một base được công bố lên registry sẽ được phân giải ở đây sau khi aggrega pull đã fetch và pin nó, và trước đó lệnh bị từ chối kèm chỉ dẫn aggrega pull --release <release>. Không có gì được fetch.
Tra cứu một tên theo các điều kiện của một Release
Một tên được đưa ra riêng lẻ sẽ được tra cứu trong ngăn xếp riêng của workspace. Thêm --release <release-path> bên cạnh nó thì tên sẽ được tra cứu trong ngăn xếp của Release đó — các thư mục mà cấu hình workspace cung cấp cho Release đó, với mọi --catalog được thêm vào đầu — chính là những gì một lần build Release đó đọc. Vì vậy, một workspace giữ một biến thể catalog cho mỗi Release, mỗi biến thể khai báo cùng một thực thể, sẽ trả lời một tên bằng biến thể mà Release đó dùng để build:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlMột tên mà ngăn xếp của Release đó không phân giải được sẽ bị từ chối, và phần giải thích về nơi đọc các thực thể cục bộ sẽ nêu mục của Release đó dưới workspace.releases, vì mục đó là thứ mà lần tra cứu đã đọc. --release chọn ngăn xếp để tra cứu một tên, nên nó chỉ áp dụng cho một tên riêng lẻ: một đường dẫn tệp và một tham chiếu registry được đọc nguyên trạng và từ chối nó. Một --release trỏ tới một tệp không tồn tại, hoặc trỏ tới một thư mục, sẽ bị từ chối trước khi bất kỳ thứ gì được tra cứu.
Đọc một thực thể đã xuất bản
aggrega inspect oci://<host>/<repository>:<tag> đọc thực thể được xuất bản tại tọa độ đó; @<digest> thay cho :<tag> chỉ định chính xác một manifest. Đây là cách bạn xem một thực thể chỉ tồn tại trong registry — repository là đoạn kind theo sau bởi danh tính của thực thể, như Catalog and Registry §6 trình bày, và aggrega push in ra tham chiếu mà nó đã xuất bản tới, tham chiếu này đọc được ở đây khi có oci:// phía trước.
Những gì bạn thấy là thực thể đúng như khi được xuất bản. Một thực thể được xuất bản cùng các tệp mà nó khai báo — một Recipe với chart cục bộ hoặc tệp khóa của nó, một Component với schema mà nó import — được phát hành dưới dạng một kho lưu trữ (archive), và thực thể được giải nén từ đó: tài liệu ở gốc archive khai báo một kind có thể xuất bản, nhờ vậy một chart template hay một đoạn compose đi kèm bên cạnh không bị nhầm là thực thể. Một thực thể không khai báo tệp nào được phát hành dưới dạng chính tài liệu của nó, không thay đổi, và thực thể của một Plugin được đọc từ manifest của nó chứ không phải từ tệp thực thi được xuất bản cùng. Sau đó tài liệu được hiển thị bằng cùng một khung nhìn mà một tệp thuộc kind đó nhận được, với cùng các mức chi tiết và cùng --raw và --output yaml. Không áp dụng kế thừa: khung nhìn là những gì nhà xuất bản đã đặt tại tọa độ đó. Các bố cục dễ đọc kết thúc bằng những gì đã được đọc: tọa độ, việc nó chứa thực thể dưới dạng archive hay chính tài liệu, media type mà manifest của nó khai báo, và digest của manifest đó, digest này đọc lại đúng các byte đó khi được viết thành @<digest> thay cho :<tag>; --output yaml in tài liệu và không in gì sau nó.
Những gì nó kiểm tra và những gì nó không kiểm tra. Các byte được tải về được kiểm tra với digest mà chính manifest của artifact ghi lại cho chúng, điều này xác lập rằng đó là các byte mà manifest chỉ định. Đây là phép kiểm tra đối chiếu với những gì registry đã phục vụ chứ không phải với bất cứ thứ gì được ghi lại từ trước: không có chữ ký nào gắn với artifact được xác minh, và không có thông báo rút lại nào được ghi đối với nó được báo cáo. Không có gì được ghi — không có mục cache và không có lockfile — nên việc đọc một tọa độ không thay đổi gì mà một lần build sau phân giải.
Nó truy cập mạng. Registry được liên hệ bằng thông tin xác thực mà máy này giữ cho nó, từ cùng kho mà aggrega push và aggrega pull đọc, và một registry trên chính máy này được liên hệ qua HTTP thuần. Một workspace đang ở chế độ ngoại tuyến từ chối việc đọc trước khi kết nối bất cứ thứ gì.
Một lần đọc không thể trả lời sẽ thoát với mã khác 0 và không in gì ra đầu ra chuẩn. Mỗi lỗi dưới đây nêu điều kiện của nó cùng với cách xử lý; một registry hoàn toàn không thể truy cập được báo cáo kèm lỗi mạng đã làm dừng việc đọc:
| Điều đã xảy ra | Điều kiện |
|---|---|
| Không có gì được xuất bản dưới tham chiếu này | E0137 |
| Registry từ chối thông tin xác thực, hoặc không có thông tin nào được lưu cho nó | E0138 |
| Workspace đang ngoại tuyến | E0125 |
| Artifact là một archive không thể giải nén | E0300 |
| Archive không chứa tài liệu thực thể nào ở gốc | E0298 |
| Archive chứa nhiều hơn một tài liệu thực thể ở gốc | E0299 |
| Tài liệu không phải là một thực thể thuộc kind mà registry xuất bản | E0301 |
Mỗi mã được liệt kê trong tài liệu tham chiếu lỗi. Một tham chiếu không chỉ định repository, hoặc không có cả tag lẫn digest, bị từ chối kèm dạng cần viết thay thế. --ir-graph và --closure bị từ chối trước khi tải bất cứ thứ gì, vì không có kind nào mà registry xuất bản là một Release.
Thông báo ngừng khuyến nghị và thu hồi
Sau khi xuất bản một artifact, nhà xuất bản có thể ghi một dấu đánh dấu cho artifact đó, cho biết phiên bản đã xuất bản bị ngừng khuyến nghị hoặc bị thu hồi. Khi nhánh catalog phân giải một thực thể, inspect báo cáo mọi dấu đánh dấu như vậy bên dưới khung xem của chính thực thể — cho mọi loại mà nó phân giải theo tên, không chỉ cho một Component.
Thông báo nêu mức độ nghiêm trọng mà nhà xuất bản đã ghi — warning, error hoặc retracted — cùng với phiên bản được ghi dấu, lý do, phiên bản thay thế nếu có nêu, và ngày phát hành dấu. Cả ba mức độ đều được báo cáo. Tập này rộng hơn tập các mức độ làm thay đổi kết quả phân giải của một bản build: một phiên bản được đánh dấu retracted bị loại khỏi việc chọn phiên bản, còn warning và error chỉ mang tính tham khảo và vẫn được chọn. inspect cho bạn thấy nhà xuất bản đã nói gì; nó không quyết định bạn nhận được gì.
Thông báo được đọc từ chỉ mục cục bộ của registry mà thực thể được phân giải từ đó, do aggrega registry update xây dựng — vì vậy nó không cần mạng và hoạt động trong một workspace ngoại tuyến. Vì chỉ mục là một bản chụp, thông báo kết thúc bằng việc cho biết bản chụp đó được tạo khi nào và nêu tên lệnh làm mới nó. Một workspace chưa xây dựng chỉ mục sẽ không báo cáo gì, và do đó việc không có thông báo có nghĩa là “không có gì được ghi trong bản chụp này” chứ không phải “không có gì được ghi”.
Một dấu đánh dấu chỉ được báo cáo khi chữ ký của chính nó được xác minh khớp với các bên ký mà chính sách tin cậy của registry chấp nhận. Một dấu không có chữ ký, hoặc có chữ ký không xác minh được, sẽ không được báo cáo: một khẳng định không thể xác thực thì không được trình bày như sự thật.
Thông báo đi kèm các khung xem dành cho người đọc. Cả --output yaml lẫn --ir-graph đều không nối thêm thông báo, nên một chương trình phân tích đầu ra của một trong hai chỉ nhận được một tài liệu và không có gì khác.
Ví dụ minh họa
Tra cứu Component trong catalog
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"Chế độ xem mặc định hiển thị mô tả của Component nếu nó có viết mô tả, sau đó là schema đã được phân giải (sau mọi lần hợp nhất extends:) và các uses-socket đã khai báo. Component ở trên không viết mô tả, vì vậy bản ghi bắt đầu ngay ở schema. --detail bổ sung các cơ chế self-inject, các Features bắt buộc và các nhãn; --list chỉ hiển thị định danh của Component và tên các socket của nó.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observabilityRecipe với --show-implements
Chế độ xem mặc định của một Recipe hiển thị một mục cho mỗi chế độ đầu vào mà nó khai báo, năng lực (capability) của nó và ánh xạ giá trị của nó. --show-implements phân giải tham chiếu spec.implements theo catalog và hiển thị Component được liên kết, cùng với các attachment mà Component đó yêu cầu:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe khai báo nhiều chế độ đầu vào
Các chế độ đầu vào của một Recipe kết hợp theo phép cộng: một source: để render, một workload: để tổng hợp và một map artifacts: đều đóng góp đầu ra, và một Recipe có thể khai báo bất kỳ tổ hợp nào của chúng. inspect báo cáo mọi chế độ mà Recipe khai báo thay vì chọn một, nên những gì bạn thấy chính là tập hợp bạn đã viết:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlCác mục được sắp xếp theo thứ tự source: → workload: → artifacts:, cùng thứ tự mà một bản build áp dụng khi phân giải một Recipe thành một tên chế độ duy nhất và khi báo cáo chế độ đã khai báo nào mà provider được liên kết không thể đáp ứng — nhờ vậy chế độ xem này và các chẩn đoán của bản build gọi tên các chế độ theo cùng một thứ tự. Một Recipe không khai báo cả source: lẫn workload: được báo cáo là chỉ có artifacts, đây là trường hợp duy nhất mà chế độ xem gọi tên một chế độ duy nhất.
Manifest (phân giải theo mặc định)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)Chế độ xem mặc định áp dụng chuỗi extends: của Manifest và trình bày các ánh xạ component và feature đã phân giải cùng các liên kết annotation. --raw hiển thị tệp như khi được viết, trước khi phân giải extends.
Aggregate (phân giải theo mặc định)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendChế độ xem mặc định dựng topology và hiển thị từng component cùng các giá trị và uses-edge của nó, tiếp theo là đồ thị phụ thuộc đã tính toán. Cây subsystem được hiển thị dạng lồng nhau; --flat hiển thị một mục cho mỗi nút, mỗi mục được định khóa bằng đường dẫn đầy đủ phân cách bằng dấu chấm.
Một kết nối được viết ở dạng đầy đủ sẽ được theo sau bởi các attachment mà nó mang, mỗi attachment nằm dưới tên mà nó nhận trên component tiêu thụ — alias của kết nối và slot nối với nhau bằng dấu chấm — kèm kiểu Feature mà nó chỉ định và một mệnh đề cho biết slot mà nó lấp đầy và liệu nó có xử lý dữ liệu được khai báo là nhạy cảm hay không:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]Slot và dấu đánh dấu là các dữ kiện mà một bản build của Release triển khai Aggregate này ghi nhận cho attachment, được đọc theo cùng cách mà chế độ xem Release đọc chúng (xem Attachment connection, slot and sensitivity clause); chúng đến từ khai báo slot của socket và khai báo của chính Feature, nên không phụ thuộc vào việc Release nào triển khai Aggregate. Một Aggregate không chỉ định Manifest nào, nên cách hiện thực hóa mà Manifest của một Release chọn cho attachment không được hiển thị ở đây. Chế độ xem này liệt kê các kết nối của một component và những gì chúng mang; các attachment trong khối riêng của một component xuất hiện trong chế độ xem Release.
Release (phân giải theo mặc định)
Chế độ xem Release là lần kiểm tra quan trọng nhất. Nó chạy toàn bộ pipeline và hiển thị, theo từng boundary, mọi nút Component, các uses-edge của nó và mọi Feature gắn vào nút đó — Feature được viết trên một kết nối nằm bên dưới edge của kết nối đó — mỗi Feature kèm slot attachment mà nó lấp đầy, liệu nó có xử lý dữ liệu được khai báo là nhạy cảm hay không và FeatureRecipe hiện thực hóa nó, cùng một ngoặc nguồn gốc (provenance bracket) cho biết attachment đến từ đâu:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)Mỗi boundary mang thư mục đầu ra và các annotation do provider tiêu thụ; mỗi component dưới một boundary mang kiểu component Aggregate của nó, các uses-edge của nó (các edge xuyên boundary được đánh dấu), mỗi edge theo sau bởi các attachment mà kết nối đó mang, và các attachment Feature của riêng nó, mỗi attachment kèm mệnh đề dữ kiện và ngoặc nguồn gốc. --flat thu gọn cây boundary thành một mục cho mỗi boundary, được định khóa bằng đường dẫn đầy đủ. --raw xuất nguyên văn tệp Release mà không chạy pipeline.
Đầu ra YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}Một Component được nêu tên từ catalog sẽ được in ra dưới dạng thực thể mà catalog đã phân giải, nên sau một lần hợp nhất extends: bạn thấy thực thể đã hợp nhất chứ không phải tệp đã soạn; một tệp Component được in đúng như đã soạn.
Đầu ra cho máy đọc
Hai cờ tạo ra đầu ra cho máy đọc, và chúng trả lời những câu hỏi khác nhau. --output chọn một định dạng cho tài liệu mà lệnh này vốn đã hiển thị; --ir-graph yêu cầu một tài liệu khác — đồ thị đã biên dịch mà một Release được phân giải thành — bổ sung thêm vào tài liệu đó. Chúng độc lập với nhau: truyền cả hai sẽ cho bạn đồ thị và YAML như khi được viết, mỗi thứ một lần.
--output yaml xuất thực thể như khi được viết, phù hợp để chuyển qua pipe và so sánh khác biệt. Đầu ra đó giữ nguyên văn, kể cả các giá trị mà tác giả đã khai báo là nhạy cảm — một đầu ra tuyên bố tái tạo đầu vào thì không thể giữ lại một phần mà vẫn là tái tạo. Hãy chuyển qua pipe, lưu trữ và chia sẻ nó theo cách bạn làm với tệp thực thể mà nó xuất phát.
Đồ thị đã biên dịch: --ir-graph
aggrega inspect <release> --ir-graph ghi đồ thị mà lần chạy phân giải được ra đầu ra chuẩn dưới dạng JSON, trước phần hiển thị mà lệnh vẫn luôn tạo ra. Một tài liệu JSON, một ký tự xuống dòng ở cuối, nên một bên tiêu thụ giải mã luồng sẽ đọc đồ thị rồi dừng.
Cờ này áp dụng cho một Release, loại duy nhất được phân giải thành một đồ thị. Khi được yêu cầu cho bất kỳ loại nào khác, hoặc cho một thực thể catalog theo tên, lệnh sẽ từ chối và nói rõ điều đó thay vì hiển thị chế độ xem riêng của thực thể đó và lặng lẽ bỏ qua yêu cầu.
Một cấu thành bị các bước kiểm tra của trình biên dịch từ chối sẽ không tạo ra đồ thị. Việc từ chối được mô tả trong Hành vi khi lỗi xảy ra trước khi bất cứ thứ gì được ghi vào luồng này, nên một pipeline đọc nó sẽ không bao giờ nhận một đồ thị mà bản build của cùng các tài liệu sẽ từ chối — nó nhận cùng các phát hiện mà một bản build sẽ báo cáo, và một mã thoát khác không.
Cùng cờ đó, với cùng ý nghĩa, có trên aggrega build và aggrega validate: mỗi lệnh trả lại đồ thị mà lần chạy đó tính được, bổ sung cho bất cứ thứ gì khác mà lệnh đó tạo ra. Một tích hợp trình soạn thảo đọc cùng đồ thị đó qua giao thức của daemon.
--output yaml không xuất đồ thị. Nó tái tạo Release như khi được viết, đúng như với mọi loại khác. Một pipeline muốn có đồ thị thì đọc nó từ --ir-graph, và nhận JSON thay vì YAML.
Đồ thị có giữ lại giá trị. Nó không phải là tệp do ai đó viết — nó là thứ mà quá trình biên dịch tính ra từ Aggregate, Release và catalog — nên không có cam kết “như khi được viết” nào cần giữ, và chính các khai báo chi phối các bố cục dễ đọc cũng chi phối nó. Ở bất cứ đâu đồ thị mang một lá mà tác giả đã khai báo là nhạy cảm, giá trị được thay bằng một đối tượng một khóa ghi nhận nó là bị giữ lại:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}Khóa vẫn còn, nên đồ thị vẫn trả lời được một node và các attachment của nó mang những lá nào; chỉ giá trị là mất. Một lá anh em không được khai báo trong cùng payload được xuất như khi được viết — secretName ở trên là một định vị công khai mà tác giả để không khai báo, và nó được in ra. Lý do đi kèm dấu đánh cho biết vì sao giá trị vắng mặt: declared cho một lá được một khai báo bao phủ, và unreadable khi payload đến ở dạng mà lệnh này không đọc được, trong trường hợp đó toàn bộ payload bị giữ lại thay vì đoán bất kỳ phần nào của nó.
Cấu hình riêng của một kết nối cũng bị giữ lại theo cùng cách. Các values theo từng kết nối mà một Aggregate viết trên một mục uses và infra theo từng kết nối mà một Release viết trên mục đó do socket của component tiêu thụ chi phối — valueSchema và infraSchema mà nó khai báo, các hợp đồng dùng để xác thực cấu hình đó — chứ không bao giờ do các khai báo của đích. Một lá mà một trong hai hợp đồng khai báo sensitive: true sẽ được thay bằng dấu đánh dấu trong values và infra của cạnh, và trong mục uses của node tiêu thụ, nơi mang các giá trị đúng như tác giả đã viết; mỗi cạnh liệt kê các lá mà nó giữ lại dưới sensitive_payload_leaves, trường mà một node dùng cho các lá của chính nó. Một lá cùng tên trên một kết nối có socket khai báo nó là đọc được sẽ được xuất đúng như đã viết.
Hãy truyền --unredacted khi một pipeline thực sự cần các giá trị, và đối xử với những gì nó tạo ra như cách bạn đối xử với chính các tệp thực thể. aggrega build và aggrega validate nhận cùng cờ này bên cạnh --ir-graph, với cùng điều kiện: đồ thị chúng trả lại sẽ giữ lại giá trị trừ khi cờ được truyền.
Giao thức của daemon cung cấp cùng đồ thị theo cùng quy tắc. aggrega/irGraph trả lời với các giá trị này bị giữ lại, và chỉ trả về chúng ở dạng rõ cho một yêu cầu đặt trường unredacted của nó — cách giao thức viết cờ này. Vì vậy những gì một bảng điều khiển trình soạn thảo hiển thị đều tuân theo cùng các khai báo, và một client hiển thị các giá trị là vì nó đã yêu cầu chúng.
Bao đóng phụ thuộc: --closure
aggrega inspect <release> --closure báo cáo bao đóng phụ thuộc của Release: mọi thực thể catalog mà nó với tới, ở phiên bản mà mỗi thực thể được phân giải thành, cùng với danh tính Aggregate và Manifest mà hai con trỏ của nó phân giải thành và các tài liệu dùng chung mà những thực thể đó dựa vào. Không có gì được kết xuất và không có artifact nào được tạo ra — bao đóng được phân giải chứ không được build, nên không provider nào được nạp để trả lời nó.
Bao đóng và chế độ xem đã phân giải là hai tài liệu khác nhau, và không thể khôi phục cái này từ cái kia. Chế độ xem đã phân giải — thứ mà lệnh này kết xuất cho một Release theo mặc định — cho biết việc triển khai trông như thế nào: các ranh giới, các nút component, cái gì được nối với cái gì, và cái gì được gắn vào mỗi nút. Bao đóng cho biết những gì đã được kéo vào để build nó, và ở những phiên bản nào. Một thực thể có thể được với tới mà không bao giờ xuất hiện như một nút — Recipe mà một Manifest ánh xạ một kiểu component tới được mọi bản build với tới nhưng không là nút trong bản nào — và một nút ghi lại kiểu component mà nó được khai báo, chứ không phải phiên bản mà kiểu đó được phân giải thành. Vì vậy, người đọc hỏi “tại sao phiên bản này thay đổi?”, “thay đổi tài liệu dùng chung này sẽ ảnh hưởng đến gì?” hay “việc triển khai này thực sự phụ thuộc vào gì?” là đang hỏi về bao đóng, và người đang có chế độ xem đã phân giải không thể có được nó chỉ bằng cách đọc kỹ hơn.
Cùng một từ yêu cầu cùng một tài liệu trên mọi giao diện. --closure ở đây, aggrega/releaseClosure qua giao thức của daemon (xem aggrega serve “Một closure không phải là đồ thị”), và chế độ release của công cụ describe qua giao thức công cụ trợ lý đều trả lời câu hỏi này về một Release; một tên Release qua bất kỳ giao diện nào trong số đó đều dẫn tới cùng một phép phân giải, nên ba giao diện không thể bất đồng về việc một Release phụ thuộc vào gì. Với một lockfile không còn khớp với những gì Release phân giải thành, lệnh này và công cụ describe từ chối bằng điểm dừng do sai lệch của bản build; còn daemon, vốn phục vụ trình soạn thảo trong lúc đang soạn thảo, thì trả lời.
Đó là một tài liệu, nên nó được yêu cầu riêng. --closure chọn bao đóng thay cho chế độ xem đã phân giải, và không thể kết hợp với --raw, --resolved, --output hay --ir-graph — mỗi cờ đó yêu cầu một tài liệu khác về cùng Release, và một lệnh chấp nhận hai yêu cầu sẽ phải âm thầm chỉ trả lời một trong hai. Việc kết hợp chúng bị từ chối, kèm tên cặp cờ.
Nó chỉ áp dụng cho một Release và không gì khác. Một thực thể catalog, một tệp Aggregate, một Manifest — không cái nào phân giải ra bao đóng, nên yêu cầu bị từ chối thay vì được trả lời bằng cách kết xuất chế độ xem riêng của đối tượng đó và bỏ qua yêu cầu. Một yêu cầu bị bỏ qua sẽ hiện ra với người gọi y hệt như một đối tượng có bao đóng rỗng.
Mỗi kết quả đều được phân biệt rõ. Một Release phân giải được sẽ được trả lời bằng danh sách. Một đường dẫn Release không trỏ tới tệp nào bị từ chối, kèm thông báo rằng tệp không tồn tại. Một Release có tồn tại nhưng bao đóng không phân giải được bị từ chối, kèm những gì không phân giải được và nơi tham chiếu xuất phát, tiếp theo là mọi tệp mà việc nạp catalog đã từ chối — vì một tệp bị từ chối thường là lý do khiến một thực thể mà Release với tới bị thiếu. Một bản ghi tin cậy plugin nằm cạnh Release, có tồn tại nhưng không đọc được, bị từ chối kèm những gì không đọc được, vì một danh sách bỏ qua nó sẽ báo cáo không có plugin nào bị rút lại ở nơi không plugin nào kiểm tra được. Một Release có lockfile không còn khớp với những gì nó phân giải thành bị từ chối bằng điểm dừng do sai lệch mà một bản build in ra, như Hành vi khi gặp lỗi mô tả, vì các phiên bản được liệt kê sẽ là những phiên bản mà không bản build nào của Release đó dùng. Một danh sách rỗng không bao giờ là câu trả lời cho bất kỳ trường hợp nào trong số đó: nó sẽ báo cáo một đường dẫn gõ sai, hoặc một workspace bị hỏng, như một Release không phụ thuộc vào gì.
Ba mức chi tiết áp dụng như với mọi kind. --list chỉ in các tham chiếu, mỗi tham chiếu một dòng, để dùng với pipe. Mức mặc định thêm các danh tính đã phân giải, phiên bản mà mỗi tham chiếu phân giải thành, các tài liệu dùng chung được dựa vào, mọi ánh xạ Manifest có đích không triển khai kiểu mà nó được ánh xạ tới, và mọi thông báo ngừng khuyến nghị hay rút lại được ghi nhận đối với những gì Release phụ thuộc vào — trong lockfile của nó, đối với một tham chiếu đã ghim, và trong bản ghi tin cậy plugin nằm cạnh nó, đối với một plugin được gắn ở một vai trò trả về phán quyết chấp nhận hoặc từ chối — bằng đúng câu chữ mà aggrega build in ra cho cùng marker đó. --detail thêm kind của mỗi tham chiếu ở nơi vị trí tham chiếu có ghi nhận — một số vị trí trong tài liệu cho biết chúng trỏ tới kind nào còn số khác thì không, nên nó được báo cáo ở nơi đã biết thay vì được đoán từ hình dạng của tên.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)Ở nơi một workspace đã ghi lại những phiên bản mà một Release phân giải thành, bản ghi đó làm nền cho phép phân giải, nên các phiên bản được báo cáo là những phiên bản mà việc triển khai này được build từ đó, chứ không phải bất cứ thứ gì catalog tình cờ đang chứa hôm nay. Một workspace không có bản ghi như vậy sẽ phân giải theo catalog ở trạng thái hiện tại.
Mệnh đề kết nối, slot và độ nhạy cảm của attachment
Mỗi attachment Feature trong view của Release mang một mệnh đề nêu các dữ kiện mà trình biên dịch ghi nhận về chính attachment đó: nó lấp slot attachment nào, nó có xử lý dữ liệu được khai báo là nhạy cảm hay không, và FeatureRecipe hiện thực hóa nó — và, với một attachment được viết trên một trong các kết nối của component, kết nối mà nó được viết trên đó. Mệnh đề nằm giữa tên của attachment và ngoặc provenance của nó, và đọc giống hệt nhau ở cả hai dạng provenance dưới đây.
Một attachment được viết trên một kết nối được liệt kê bên dưới dòng của kết nối đó trong Uses:, không phải dưới Features:, vì vậy Features: chỉ chứa các attachment riêng của component. Dòng phía trên nêu kết nối bằng alias của nó và component mà nó vươn tới, còn mệnh đề riêng của nó nói phần còn lại:
[socket: <socket>]— socket mà kết nối được nối qua, điều mà dòng của kết nối không nêu. Nó đứng đầu mệnh đề vì nó thay đổi cách đọc phần còn lại: nửa slot theo sau nêu một slot do socket của kết nối khai báo, không phải một slot mà component khai báo cho các attachment của chính nó.[connection: <alias> through socket <socket>]— cùng dữ kiện đó cho một attachment có kết nối mà khốiUses:không hiển thị dòng nào, attachment này khi đó được liệt kê dướiFeatures:và nêu kết nối của nó tại đây. Dù theo cách nào, một kết nối được nêu một lần cho mỗi attachment, không bao giờ hai lần.[slot: <name>]— attachment lấp slot có tên<name>. Một slot được lấp bằng cách gắn một Feature dưới chính tên của slot, nên<name>là tên mà attachment được viết dưới đó, được đối chiếu với các slot đã khai báo:featuresSchemacủa Component chủ đối với một attachment của chính nó, vàfeaturesSchemamà socket của kết nối khai báo đối với một attachment được viết trên một kết nối.[free]— attachment không lấp slot đã khai báo nào: Component đã phân giải không khai báo slotfeaturesSchemanào có tên đó. Đây là một phát hiện, không phải một chẩn đoán. Một attachment dạng tự do được chấp nhận, và một người vận hành muốn cấm nó sẽ thể hiện điều đó dưới dạng một chính sách quản trị thay vì dựa vào công cụ để từ chối nó.[sensitive]— attachment xử lý dữ liệu mà một tác giả đã khai báo là nhạy cảm, vì Feature được gắn khai báo một leaf nhạy cảm, vì slot mà nó lấp khai báosensitive: true, hoặc cả hai.[realization: <name>:<version>]— FeatureRecipe mà Manifest của Release gắn cho attachment: theo tên riêng của attachment khi Manifest ánh xạ tên đó — với một attachment được viết trên một kết nối, là alias và slot nối với nhau bằng dấu chấm — nếu không thì theo kiểu Feature của nó. Đó là realization mà một lần build từ cùng các tài liệu dùng để render attachment, và là cùng giá trị mà đồ thị đã biên dịch mang trên attachment dưới dạngrealization(xem--ir-graph), vì vậy view này và đồ thị không thể nêu những realization khác nhau. Nó đứng cuối cùng trong mệnh đề.
Khi nhiều dữ kiện cùng áp dụng, chúng chung một mệnh đề. core/storage/s3-object-store khai báo một slot secret_access_key được đánh dấu sensitive: true, nên một credential được gắn dưới tên đó báo cáo cả hai dữ kiện, trong khi một Feature được gắn dưới một tên mà Component không khai báo slot nào thì không báo cáo slot lẫn độ nhạy cảm. Với một Manifest ánh xạ mỗi kiểu Feature tới một FeatureRecipe, mỗi dòng cũng nêu realization của nó:
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]Một component có socket models khai báo một slot credential được đánh dấu sensitive: true, nối một kết nối dưới alias gpt lấp slot đó, sẽ liệt kê attachment đó bên dưới kết nối — bên cạnh một credential của chính nó, vẫn nằm dưới Features::
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]Một attachment được viết trên một kết nối không bao giờ báo cáo [free]: một socket chỉ chấp nhận các slot mà nó khai báo, và một kết nối mang bất kỳ tên nào khác sẽ bị từ chối khi build được nạp.
Mệnh đề bị lược bỏ hoàn toàn khi không có dữ kiện nào áp dụng, và mỗi nửa được lược bỏ một cách độc lập:
- Không có nửa socket hoặc kết nối nghĩa là attachment được viết trên khối riêng của component, hoặc đến với nó từ một phạm vi rộng hơn hay qua việc mở rộng dựa trên annotation.
- Không có nửa slot nghĩa là tập slot đã khai báo của Component chủ không thể phân giải được — chẳng hạn, kiểu của nó không khớp với thực thể catalog nào. Điều này được cố ý phân biệt với
[free]:[free]trả lời “không có slot nào mang tên đó được khai báo”, còn một nửa vắng mặt nghĩa là câu hỏi hoàn toàn không thể trả lời được. - Không có
sensitiveghi nhận rằng không có khai báo nào đánh dấu attachment. Điều đó hẹp hơn một kết luận rằng attachment không mang gì bí mật; trục này báo cáo các khai báo, và không có gì được suy ra từ tên hay giá trị của một trường. - Không có nửa realization nghĩa là Manifest không gắn attachment với FeatureRecipe nào mà catalog đang chứa.
Một slot có tên khai báo đúng là free cũng được render thành [free], không thể phân biệt với một attachment dạng tự do — không có gì dành riêng từ đó trong không gian tên slot.
Ngữ pháp của ngoặc nguồn gốc IR
Mỗi phần gắn Feature trong chế độ xem Release mang một ngoặc nguồn gốc. Ngoặc có thể ở dạng gọn (một ngoặc cho mỗi Feature khi nguồn gốc của phần gắn đồng nhất trên mọi lá) hoặc dạng theo từng lá (một ngoặc cho mỗi lá khi các lá của phần gắn đến từ những nguồn khác nhau). Có ba loại nội dung ngoặc; chúng áp dụng giống hệt nhau cho cả hai dạng.
Ba loại nội dung ngoặc
-
[explicit]— phần gắn Feature được tác giả khai báo. Aggregate hoặc Release đã nêu rõ Feature trên nút liên quan. Các phần gắn tường minh là nguồn có độ ưu tiên cao nhất; chúng luôn thắng các đóng góp do annotation điều khiển tại cùng một lá. -
[annotation: <key> from <source>]— phần gắn Feature được điều khiển bởi annotation. Trình biên dịch tổng hợp nó vì một annotation trên<source>khớp với một ràng buộc Manifest khai báo Feature này.<key>là khóa annotation đã kích hoạt ràng buộc (ví dụ:business.aggrega.ai/team);<source>là thực thể mang annotation (aggregate,release,componenthoặcmanifest). Phần gắn được tổng hợp giống hệt về cấu trúc với một phần gắn tường minh — khâu kết xuất phía sau xử lý cả hai như nhau — nhưng ngoặc nguồn gốc phân biệt chúng để việc gỡ lỗi luôn xác định được. -
[explicit; overrides annotation: <key> from <source>]— một dạng theo từng lá, xuất hiện khi một khai báo tường minh của tác giả tại một lá đang lấn át một đóng góp từ annotation mà lẽ ra đã đặt cùng lá đó. Kết hợp giữa hai phía tạo ra trường hợp này: một annotation của Aggregate có thể cung cấp trụvalues:của một Feature, một annotation của Release cung cấp trụinfra:của nó, và một khai báo tường minh của Release trên cùng Feature ghi đè một lá infra. Ngoặc của lá ghi lại cả tác giả tường minh lẫn annotation bị lấn át; annotation bị lấn át không đóng góp vào đầu ra được kết xuất, nhưng sự hiện diện của nó xuất hiện trong chế độ xem inspect để người vận hành thấy annotation nào đã bị ghi đè và ở đâu.
Dạng gọn so với dạng theo từng lá
Trình biên dịch chọn giữa kết xuất dạng gọn và dạng theo từng lá bằng cách duyệt nguồn gốc theo từng lá của phần gắn và kiểm tra tính đồng nhất. Nguồn gốc của một phần gắn là đồng nhất khi mọi lá có giá trị (trên các trụ values: và infra: của Feature) có cùng xuất xứ (tường minh hay annotation), cùng khóa annotation khi do annotation điều khiển, cùng thực thể nguồn, và không lá nào mang dấu “overrides annotation”. Khi nguồn gốc đồng nhất, trình biên dịch xuất một ngoặc cho mỗi phần gắn:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Khi nguồn gốc khác nhau — một trường hợp điển hình là kết hợp giữa hai phía, trong đó một annotation của Aggregate cung cấp values: và một annotation của Release cung cấp infra: trên cùng một Feature — trình biên dịch xuất một ngoặc cho mỗi lá có giá trị:
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]Thứ tự duyệt là trụ values trước (theo thứ tự của tác giả), rồi đến trụ infra (cùng nguyên tắc). Tiền tố trụ (values. / infra.) và đường dẫn có dấu chấm bên trong trụ chỉ rõ chính xác lá mà mỗi ngoặc chú thích.
Giá trị được khai báo là nhạy cảm
Một lá mà schema của nó khai báo sensitive: true sẽ in văn bản cố định <redacted> thay cho giá trị của nó. Khóa, tiền tố pillar và ngoặc nguồn gốc đều được giữ lại — chỉ giá trị bị thay thế — nên bố cục vẫn cho biết một thực thể mang những lá nào và mỗi lá đến từ đâu. Có hai bề mặt đọc được chịu ảnh hưởng: khối Values: theo từng nút của một Aggregate, và khối attachment theo từng lá của một Release đã được phân giải — bao gồm cả một attachment được viết trên một kết nối, được in bên dưới dòng của kết nối đó, và nó che giấu đúng những lá mà cùng Feature đó che giấu khi chính component nắm giữ nó. Đồ thị đã biên dịch của một Release dưới --ir-graph che giấu cùng những lá đó ở dạng có cấu trúc được mô tả tại Đầu ra máy đọc được.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>Chỉ lá được khai báo mới bị che giấu, và mệnh đề [sensitive] ở cấp attachment không phải là chỉ thị che giấu: nó cho biết attachment xử lý dữ liệu bí mật, chứ không cho biết lá nào của nó mang dữ liệu đó. Các định vị đã công bố của một Feature thông tin xác thực — tên tài nguyên và khóa dữ liệu — là công khai và được cố ý để không khai báo trong catalog của thư viện chuẩn, vì vậy chúng được in rõ ràng bên cạnh dữ liệu không được in rõ ràng:
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]Không có gì được suy ra từ tên của một trường: một trường tên password không có khai báo sẽ in giá trị của nó, còn một trường đã khai báo tên key thì không. Việc che giấu chỉ áp dụng cho những gì công cụ in ra; nó không bao giờ ảnh hưởng đến một artifact đã render, và dist/ được xuất ra đúng như quá trình render đã tạo ra. Từ khóa và toàn bộ giới hạn của những gì việc khai báo nó đạt được có tại vocabulary/compact-form-authoring.md “Khai báo một lá là nhạy cảm”.
Hiển thị các giá trị bị che
--unredacted in ra các giá trị được khai báo là nhạy cảm thay vì che giấu chúng, trên mọi bề mặt inspect cùng lúc — cả các bố cục đọc được ở trên lẫn đồ thị đã biên dịch của một Release. Tùy chọn này tồn tại vì đôi khi giá trị bị che giấu lại chính là giá trị đang được điều tra: một thông tin xác thực đến từ sai attachment trông giống hệt thông tin đúng khi cả hai đều hiển thị là bị che giấu.
Nó chỉ có phạm vi trong lệnh mà nó được truyền vào. aggrega build và aggrega validate cũng nhận nó, khi đó nó chỉ tác động đến đồ thị mà --ir-graph trả về và không gì khác, và từ chối nó khi không có đồ thị nào được yêu cầu. aggrega build --trace-unredacted là cùng ý tưởng đó áp dụng cho các tệp trace của quá trình build, và không cờ nào trong hai cờ của build tác động đến đầu ra của cờ kia; một artifact đã render dưới dist/ không bị ảnh hưởng bởi bất kỳ cờ nào trong số đó, vì nó được xuất ra đúng như quá trình render đã tạo ra, bất kể truyền vào gì.
Khi đó, bất cứ nơi nào đầu ra đi đến đều mang các giá trị đó ở dạng rõ ràng — một terminal, một pipe, một tệp, một bản ghi màn hình, một báo cáo lỗi được dán vào. Khác với các tệp trace, vốn đều mở đầu bằng một header cho biết chúng được ghi lại mà không che giấu, đầu ra trên terminal không mang dấu hiệu nào như vậy: chỉ có dòng lệnh cho biết cờ đó đã được truyền vào.
Khi nào nên dùng inspect
- Gỡ lỗi “vì sao Feature này ở đây?” — các attachment do annotation sinh ra không hiển thị trong các tệp YAML của Aggregate và Release (annotation có ở đó, nhưng các attachment Feature mà chúng tổng hợp chỉ tồn tại trong IR). Inspect hiển thị chúng kèm nguồn gốc.
- Kiểm tra kế thừa schema —
aggrega inspect <ComponentName>hiển thị schema đã hợp nhất sau khi chuỗiextends:được phân giải; riêng tệp do tác giả viết chỉ cho thấy phần khác biệt cục bộ. - Chẩn đoán các kết quả bất ngờ khi kết hợp giữa hai phía — khi một annotation của Aggregate và một annotation của Release cùng cung cấp payload pillar trên cùng một Feature, các leaf đã phân giải có thể khó tái dựng trong đầu. Dạng ngoặc theo từng leaf làm cho việc phân giải trở nên rõ ràng.
- Kiểm tra xác minh trước khi triển khai —
aggrega inspect ./prod-release.yamlliệt kê mọi Feature trên mọi Component trước khiaggrega buildtạo ra artifact; người vận hành có thể xác nhận topology khớp với ý định trước khi commit các manifest đã render lên GitOps.
Về cơ chế bên dưới — cách annotation lan truyền, cách phân vùng phía-so-với-pillar định tuyến giá trị annotation vào các pillar của Feature, và cách nguyên tắc attachment tường minh được ưu tiên tương tác với các đóng góp do annotation sinh ra — xem providers/well-known-annotations.md và entities/manifest.md “Annotation-Driven Feature Bindings”.
Cú pháp
aggrega inspect [identifier] [flags]Mô tả
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--catalog | [] | Thư mục catalog; có thể lặp lại. Mỗi —catalog <dir> được thêm vào đầu ngăn xếp tìm kiếm catalog (kết quả khớp đầu tiên được dùng): catalog_dirs của workspace, hoặc, với một Release mà cấu hình workspace cấp thư mục riêng trong workspace.releases, thì các thư mục của Release đó; ngăn xếp kết thúc bằng thư mục có tên catalog ở gốc workspace nếu có. Một danh sách catalog_dirs được viết rỗng sẽ không đọc catalog cục bộ nào cả. |
--closure | false | Báo cáo bao đóng phụ thuộc của Release — mọi thực thể catalog mà nó với tới, ở phiên bản mà mỗi thực thể được phân giải — thay cho chế độ xem các node đã phân giải. Áp dụng cho một Release, loại duy nhất phân giải một bao đóng; mọi loại khác từ chối yêu cầu thay vì lặng lẽ bỏ qua nó. |
--color | auto | Tô màu đầu ra: auto|always|never. |
--detail | false | Render toàn bộ nội dung các trường. |
--flat | false | Render một thực thể dạng cây (Aggregate, Release) thành danh sách phẳng, mỗi node có tiền tố là đường dẫn chấm đầy đủ của nó. Không có tác dụng với các loại dạng bảng. |
--ir-graph | false | Ghi thêm đồ thị IR mà lần chạy này tính ra vào stdout, dưới dạng JSON, ngoài mọi thứ lệnh này vốn đã tạo ra. Các giá trị mà tác giả khai báo là nhạy cảm được giữ lại khỏi nó; truyền —unredacted để in chúng ra. Áp dụng cho một Release, loại duy nhất phân giải thành một đồ thị; mọi loại khác từ chối yêu cầu thay vì lặng lẽ bỏ qua nó |
--list | false | Chỉ render các định danh. |
--no-color | false | Tắt tô màu đầu ra (bí danh của —color=never). |
--output, -o | text | Định dạng đầu ra: text|yaml. |
--plugin | — | Đường dẫn hệ thống tệp tới một artifact <file.wasm> thô; suy ra và in các hàm host mà nó import, trước khi aggrega plugin sync ghi chúng vào một thực thể Plugin. Không nhận đối số định danh. |
--raw | false | Render thực thể đúng như khi viết, không phân giải. |
--release | — | Tra một tên catalog theo các điều kiện của tệp Release này: qua các thư mục catalog mà cấu hình workspace cấp cho Release đó, với —catalog được thêm vào đầu. Áp dụng cho một tên; một tệp hoặc một tham chiếu registry được inspect nguyên trạng và từ chối tùy chọn này. Đường dẫn tương đối được phân giải theo thư mục nơi bạn chạy lệnh, không theo thư mục gốc của workspace. Khi thư mục đó không thuộc workspace nào và không có gốc nào được chỉ định, một đường dẫn tuyệt đối sẽ tìm workspace từ thư mục riêng của Release |
--resolved | false | Render thực thể đã phân giải đầy đủ. |
--show-implements | false | Với một Recipe hoặc FeatureRecipe, phân giải spec.implements theo catalog và render Component hoặc Feature được liên kết. |
--unredacted | false | In các giá trị mà tác giả khai báo là nhạy cảm thay vì giữ lại chúng. Khi đó, mọi nơi đầu ra tới — terminal, pipe, tệp, bản ghi màn hình — đều mang các giá trị đó ở dạng rõ. |