Các Features thông tin xác thực
Trang này giải thích một ý tưởng, đó là các Features thông tin xác thực của thư viện chuẩn và cách một Manifest chọn thứ hiện thực hóa từng cái, và không phải là một không gian làm việc có thể chạy được. Một ý định của nhà phát triển, hai dạng chuyển giao thông tin xác thực build một Aggregate với hai cách hiện thực hóa của cùng một thông tin xác thực; hãy ghi nó vào một thư mục của riêng bạn bằng:
aggrega scaffold --example credential-shape-per-targetSau đó nó in ra các lệnh cần chạy tiếp theo:
cd credential-shape-per-targetaggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pullMột thông tin xác thực lấp đầy một slot mà một Component khai báo trong featuresSchema của nó (xem entities/component.md); slot, Feature lấp đầy nó và FeatureRecipe mà Manifest liên kết tạo thành toàn bộ đường đi từ phần đính kèm của một tác giả đến một khối lượng công việc đang chạy.
Họ Feature thông tin xác thực
Một Feature thông tin xác thực mang nhãn feature.aggrega.ai/kind: secret. Nhãn này là siêu dữ liệu của catalog, mô tả thứ mà phần đính kèm tạo ra; không có nhánh nào của trình biên dịch đọc nó, và một Feature thông tin xác thực được đính kèm dưới features: như mọi Feature khác, bởi nhà phát triển trong Aggregate hoặc bởi người vận hành trong Release.
Thư viện chuẩn chia các Features thông tin xác thực theo điều mà cách hiện thực hóa làm với bí mật:
core/secret-valueđưa một giá trị vào đường ống inject của component, nơi Recipe của nó đọc giá trị đó — một giá trị chart, một biến môi trường.core/secret-providedcũng cho ra một giá trị, nhưng thay vào đó công bố nó dưới dạng một khóaprovides, nên chính khốiinject:của phần đính kèm trên một slot trong suốt cho biết giá trị đi đâu.core/referenced-secretchỉ định một tài nguyên bí mật — một Kubernetes Secret, một secret của AWS Secrets Manager, một mục Vault — do cách hiện thực hóa của nó tạo ra hoặc đã tồn tại sẵn, và công bốnamevàkeycủa tài nguyên đó, mà bên tiêu thụ đọc dưới dạng.features.<slot>.provides.namevà.features.<slot>.provides.key.core/referenced-secret-sethiện thực hóa một tài nguyên như vậy chứa một tập khóa dữ liệu do tác giả cung cấp, và chỉ công bố bộ định vị của nó, dành cho bên tiêu thụ mà đích của nó đã cố định tên các khóa nó đọc. Docker Compose không có tài nguyên như vậy, nên ở đó hiện thực của nó thay vào đó chuyển các khóa dưới dạng giá trị, như mô tả bên dưới. MariaDB (chart Bitnami) — một Secret thông tin xác thực nhiều khóa sử dụng nó.core/generated-secretkhông tạo ra gì: engine đích tự sinh và quản lý thông tin xác thực, như một cơ sở dữ liệu được quản lý làm với mật khẩu quản trị của nó. Người vận hành đính kèm nó trong Release, vì việc engine có sở hữu thông tin xác thực hay không phụ thuộc vào Recipe mà Manifest chọn; Terraform RDS (artifact HCL nội tuyến) liên kết một slot bắt buộc theo cách này.core/random-passwordrender một yêu cầu để đích sinh mật khẩu vào một tài nguyên bí mật, và công bố bộ định vị của tài nguyên đó nhưcore/referenced-secret. Không ai viết thông tin xác thực và đầu ra được render không chứa nó.
Chúng ngang hàng — cùng nhãn, cùng bề mặt đính kèm, cùng slot — nên một slot luôn được lấp đầy, và điều thay đổi giữa các Releases là thứ lấp đầy nó. Một Feature thông tin xác thực khai báo hợp đồng provides buộc mọi FeatureRecipe hiện thực nó phải công bố các khóa đó, và bản build dừng lại nếu có một FeatureRecipe không làm vậy; đó là điều giúp việc đọc của bên tiêu thụ an toàn.
core/random-password cần có thứ gì đó ở đích để rút ra giá trị, vì bản build không bao giờ làm việc đó: trên Kubernetes là một controller (External Secrets Operator, hoặc kubernetes-secret-generator) mà Release xác nhận bằng infra.control_plane_present: true; trên Terraform là một tài nguyên random_password; trên CloudFormation là một secret của Secrets Manager tự sinh chuỗi của nó. Không có cách hiện thực hóa nào được cung cấp cho Docker Compose, nên một bản build liên kết nó ở đó sẽ dừng lại. Mỗi yêu cầu tự rút ra giá trị riêng, nên hai component dùng chung một mật khẩu được sinh ra bằng cách đính kèm nó một lần, với name được cố định, và đọc nó ở nơi khác qua core/referenced-secret được liên kết với helm/k8s-existing-secret.
Ai đặt tên cho thông tin xác thực: values hoặc infra, chính xác một trong hai
core/secret-value, core/secret-provided, core/referenced-secret và core/referenced-secret-set chấp nhận locator của thông tin xác thực từ một trong hai tác giả: nhà phát triển viết nó trong values của attachment trong Aggregate, người vận hành viết trong infra của attachment trong Release. Leaf giống nhau ở cả hai — origin, hoặc entries đối với tập hợp — và mọi cách hiện thực hóa đều đọc pillar nào đang mang nó.
Dạng của người vận hành là điều giúp một thông tin xác thực dùng được ở nơi nhà phát triển không thể viết nó: trên một kết nối do Release nối, và trên một attachment chỉ riêng Release tạo ra, vì Release không viết values ở đâu cả.
# Release: the operator wires the connection and names the secret.spec: components: router: uses: models: gpt: target: gpt features: credential: type: core/referenced-secret infra: origin: openai-team-aChính xác một trong hai. Mỗi pillar được xác thực riêng, nên không schema nào có thể bắt buộc locator; thay vào đó, assertions riêng của mỗi Feature giữ quy tắc này, và một attachment mang locator ở cả hai pillar, hoặc không ở pillar nào, sẽ dừng bản build (E0033) và nêu tên Feature, attachment và component. Đó là hợp đồng của các thực thể trong catalog: trình biên dịch đánh giá assertion của chúng như đánh giá assertion của bất kỳ Feature nào.
Mọi thứ khác giữ nguyên pillar của nó. key vẫn là một leaf của values, nên một attachment chỉ do Release tạo ra sẽ đọc khóa dữ liệu mặc định, value. Khai báo origin ở cả hai pillar chính là điều mà cảnh báo chồng lấn pillar tìm kiếm, nên việc nạp các Features này sẽ báo cáo nó — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Ở đây sự chồng lấn chính là hợp đồng; cảnh báo này không thay đổi kết luận nào và không thay đổi byte nào được render.
Manifest chọn cách hiện thực hóa
Nhiều FeatureRecipes có thể triển khai một Feature cho cùng một đích, và Manifest sẽ chọn. core/referenced-secret có ba FeatureRecipes trên Kubernetes, và nơi thông tin xác thực được lưu quyết định giữa chúng:
helm/k8s-secret-from-parameterghi giá trị mà tác giả cung cấp vào một Secret mà nó xuất ra, nên dữ liệu nằm trong đầu ra được render: dành cho việc đánh giá và làm việc cục bộ.helm/k8s-external-secretrender mộtExternalSecretchỉ định một mục trong secret store, mà External Secrets Operator trong cluster sẽ reconcile thành một Secret.helm/k8s-existing-secretkhông xuất ra gì: nó đọcoriginlà tên của một Secret đã tồn tại và công bố nó đúng như đã viết.
Hai FeatureRecipe đầu suy ra tên Secret theo cùng một cách, từ tên được render của host và tên của slot, nên bên tiêu thụ đọc cùng một locator từ cả hai và tham chiếu được render của nó không đổi; đó là điều ví dụ cho thấy. FeatureRecipe thứ ba công bố chính tên của Secret đã có, nên việc bind nó cố ý thay đổi tham chiếu của bên tiêu thụ.
core/secret-value được hiện thực hóa trên Docker Compose bởi compose/dotenv-secret, thứ ghi giá trị vào environment của service đúng như đã viết: một origin viết dưới dạng ${DB_PASSWORD} nằm trong đó dưới dạng tham chiếu ấy, mà Docker Compose điền từ shell của bạn hoặc một tệp .env khi stack khởi động. Trên Kubernetes, helm/env-secret đưa giá trị vào inject pipe, và helm/k8s-secret-from-value còn ghi nó vào một Secret và công bố bộ định vị của nó, dành cho bên tiêu thụ đọc thông tin xác thực theo tham chiếu. Không cách hiện thực hóa nào trên Kubernetes chấp nhận một tham chiếu biến Compose, thứ mà ở đó không gì điền vào.
core/referenced-secret được hiện thực trên Docker Compose bởi compose/dotenv-referenced-secret. Compose không có tài nguyên secret nào để tham chiếu, nên origin chính là thông tin xác thực chứ không phải tên của một Secret: nó được chuyển vào inject pipe dưới key của phần đính kèm, và một Recipe Compose đọc slot sẽ ghi nó vào tệp được xuất ra đúng như đã viết, nên một origin viết là ${DB_PASSWORD} nằm trong tệp dưới dạng tham chiếu đó. Nó không tạo tài nguyên nào, nên tên nó công bố là rỗng và khóa nó công bố là values.key.
core/referenced-secret-set được hiện thực trên Docker Compose bởi compose/dotenv-secret-set, vốn chuyển từng mục vào inject pipe dưới dạng một biến đặt tên theo khóa của nó, được ghi vào environment của service đúng như đã viết, nên một mục có giá trị ${GITHUB_TOKEN} nằm trong tệp dưới dạng tham chiếu đó. Nó không tạo tài nguyên nào, nên bộ định vị nó công bố là rỗng: một bên tiêu thụ trên Compose đọc các mục từ inject pipe của chính nó thay vì tham chiếu một Secret theo tên, như compose/mcp và compose/mcp-stdio-bridge từ 1.1.0 làm cho server_env của một máy chủ Model Context Protocol.
Tên FeatureRecipe được cung cấp cho nhiều hơn một đích, chẳng hạn provided-secret, được ghi kèm đích của nó trong Manifest, compose/provided-secret:1.0.0, vì tên trần khớp với cả hai.
Một tên, công bố một lần
Recipe của bên tiêu thụ không bao giờ tự suy ra tên của Secret mà một thông tin xác thực tạo ra: nó đọc bộ định vị mà thông tin xác thực công bố, existingSecret: "{{ .features.root_password.provides.name }}". Tên được viết một lần, trên provides của FeatureRecipe, nên thay đổi cách ghép tên chỉ là một chỉnh sửa tại đó. Chuyển giao thông tin xác thực — secretKeyRef đầu cuối build đường dẫn có thể tham chiếu trên Kubernetes và đường dẫn được inject trên Docker Compose, và Chia sẻ một thông tin xác thực — theo từng bên tiêu thụ, dùng chung, và cả hai cùng lúc cho thấy nhiều bên tiêu thụ giữ khóa riêng hoặc dùng chung một khóa.