Harbor stack — một container registry được triển khai dưới dạng một release
Ví dụ này biên dịch một container registry thực sự thành các manifest Kubernetes từ một
Aggregate do Developer viết.
Một container registry gồm nhiều dịch vụ phối hợp với nhau — một control plane gồm API và token-service, một kho blob OCI cùng controller của nó, một web console, một tầng worker bất đồng bộ, một trình quét lỗ hổng, một backend quan hệ, một bộ đệm key-value, và một reverse proxy đứng trước tất cả. Catalog mô tả toàn bộ những thứ đó như một Component, vì chính những người duy trì registry phát hành một Helm chart triển khai toàn bộ registry dưới dạng một release duy nhất, theo thứ tự mà các dịch vụ của nó cần. Component khai báo registry; Recipe bao bọc chart đó.
Registry được import dưới dạng một module: một sub-aggregate có thể tái sử dụng, kết hợp Component và xuất địa chỉ được công bố của nó. Aggregate cấp cao nhất import module theo tên và truyền cho nó ba khóa của registry; operator định kích thước cho component của module trong Release.
Các tệp
| Tệp | Vai trò |
|---|---|
aggregate.yaml | Ý định của Developer: nhập module container registry (core/harbor) và truyền cho nó ba khóa của registry từ các tham số của chính mình. |
manifest-helm-synth.yaml | Ánh xạ loại component của registry tới Recipe bao bọc Helm chart của nó, và Feature thông tin xác thực tới cách hiện thực đọc một Secret đã có sẵn trong namespace — ngoại trừ mật khẩu của quản trị viên, được gắn theo tên tới cách hiện thực phát ra một Secret từ tham số của module. |
release-helm-synth.yaml | Bản ghi của operator cho đích Kubernetes. Nêu tên các Secret chứa ba khóa mà Aggregate truyền xuống, định cỡ component của module theo ID trong phạm vi module của nó, và gắn vào đó khóa ký token, secret dùng chung của các dịch vụ và khóa dùng để mã hóa thông tin xác thực được lưu trữ bằng cách nêu tên các Secret chứa chúng; mọi thứ khác được để cho giá trị mặc định của schema. |
Ví dụ này minh họa điều gì
- Một sản phẩm đa dịch vụ dưới dạng một Component. Điều khiến registry là một Component thay vì nhiều Component không phải là kích thước của nó mà là nơi phần kết nối của nó được duy trì: định tuyến reverse proxy, khóa của token service mà control plane dùng để kiểm tra mọi lần pull và push, các thiết lập kết nối mà mỗi dịch vụ đọc cho backend và cache, việc chia cơ sở dữ liệu logic để giữ các keyspace cache của các dịch vụ tách biệt, và thứ tự khởi động — tất cả được những người phát hành sản phẩm giữ đồng bộ với sản phẩm, bên trong chart. Người dùng chỉ cần khai báo một registry và nhận được những thứ đó ăn khớp với nhau.
- Một chart được bao bọc. Recipe nêu tên chart trong
source:và phủ mộtvaluesMapping:lên nó — template values là toàn bộ phần hiện thực, và provider Helm render các template riêng của chart dựa trên nó. Không có workload nào được tổng hợp ở đây. - Một đầu vào bên ngoài được ghim phiên bản. Chart là một đầu vào mà bản build tải về, nên nó được
ghim như mọi phụ thuộc khác: lockfile ghi lại phiên bản của chart, URL đã phân giải
và digest của tarball, dưới
source_artifacts. Một bản build với lockfile đã được điền sẽ lấy chart từ kho nội dung và xác minh nó với digest đó. - Một địa chỉ công bố cho cả một nền tảng. Reverse proxy của chart
định tuyến đường dẫn trình duyệt
/tới console và các đường dẫn registry và API (/v2/,/api/,/service/,/c/) tới control plane, nên một client container đăng nhập, push và pull trên cùng host mà trình duyệt dùng để truy cập console. Service đó là thứ màprovides.hostcông bố, và người dùng không cần địa chỉ thứ hai để truy cập nhóm đường dẫn nào. - Hai tên công khai cho nó. Module xuất địa chỉ duy nhất đó dưới tên
registry, endpoint mà các client image và API giao tiếp, và dưới tênui, endpoint web. Cả hai đều phân giải về địa chỉ phục vụ cả hai nhóm đường dẫn, nên người dùng kết nối tới tên nào mô tả đúng ý định của mình. - Operator định cỡ component của một module. Release tham chiếu component của module
bằng ID theo phạm vi module (
harbor.registry) để thiết lập tài nguyên tính toán, mà Aggregate của developer không cần khai báo lại kích thước vật lý. - Quy tắc đầy đủ trên một giá trị nhóm.
infra.computechứa một khóa CPU và một khóa bộ nhớ, và Recipe dừng lại khi một nhóm để trống bất kỳ khóa nào trong hai. Một control plane được render với giới hạn CPU mà không có giới hạn bộ nhớ khác biệt đáng kể so với control plane mà các giá trị mặc định đã khai báo của Component mô tả, và không có gì trong đầu ra đã render cho biết điều đó — nên bản build dừng lại và nêu tên khóa còn thiếu. Một khóa mà nhóm bỏ qua sẽ nhận giá trị mặc định của Component. - Sáu khóa không có giá trị mặc định. Khóa mà token service dùng để ký các token của registry, cùng với chứng chỉ của nó; ba secret mà các dịch vụ riêng của registry dùng để xác thực lẫn nhau và ký trạng thái upload; khóa chống giả mạo yêu cầu; và khóa mà control plane dùng để mã hóa thông tin xác thực được lưu trữ đều không có giá trị mặc định: một khóa mà mọi người đọc catalog đều nắm giữ sẽ cho phép bất kỳ ai tạo token mà registry tin cậy hoặc đọc những gì nó lưu trữ. Component khai báo các slot đó là bắt buộc, nên một bản build để trống một slot sẽ dừng lại và nêu tên slot đó. Bản build không đọc và không render giá trị nào trong sáu giá trị: mọi workload đọc từng giá trị từ một Secret mà nó nêu tên.
- Ba khóa mà Release gắn vào. Module không gắn
khóa ký token, secret dùng chung của control plane, hay khóa dùng để mã hóa
thông tin xác thực được lưu trữ, nên Release gắn cả ba vào
component của module,
token_key,core_secretvàsecret_key, mỗi khóa thông quacore/referenced-secretvớiinfra.originnêu tên một Secret, và Manifest ràng buộc Feature vớik8s-existing-secret. Control plane mount khóa ký token và khóa mã hóa từ các Secret mà chúng nêu tên, và các dịch vụ đọc secret dùng chung từ Secret của chúng. - Thông tin xác thực mà module điền. Mật khẩu của tài khoản quản trị, khóa
chống giả mạo yêu cầu liên trang, secret dùng chung của tầng worker và secret trạng thái upload
của blob store cũng là các slot thông tin xác thực trên Component, và
module điền từng slot từ một tham số riêng của nó (
admin_password,csrf_key,jobservice_secret,registry_http_secret) thông qua Feature thông tin xác thựccore/referenced-secret, nên mọi workload đọc chúng từ một Secret theo tên. Vì module gắn Feature đó, Manifest ánh xạ nó. Ba khóa này cũng không có giá trị mặc định trong module, nên Aggregate khai báo các tham số riêng và truyền chúng xuống quaaggregates.harbor.parameters, Release đáp ứng chúng, vàk8s-existing-secretđọc mỗi giá trị như tên của một Secret đã tồn tại trong namespace; một Release không cung cấp giá trị sẽ làm bản build dừng lại, nêu tên tham số. Ví dụ này để mật khẩu quản trị ở giá trị mặc định dành cho phát triển của module, và Manifest ràng buộc riêng phần gắn đó theo tên vớik8s-secret-from-parameter, thứ tạo ra một Secret chứa mật khẩu đó. Các mật khẩu còn lại được ghi vào cấu hình mà Release render, nên chúng được thay thế bằng cách thiết lậpinfra; nếu không thiết lập, mỗi mật khẩu nhận một giá trị phát triển mà Recipe nêu. - Đầu ra tất định trên một chart vốn sẽ tự sinh dữ liệu. Nếu để mặc, chart này tự tạo secret khi không được cung cấp — các secret dùng chung và ký token của control plane, secret của tầng worker và của blob store, khóa chống giả mạo yêu cầu, và mật khẩu đã băm của blob store, thứ mà nó băm lại với salt mới ở mỗi lần render. Thay vào đó, mỗi giá trị đều được cung cấp: sáu khóa luôn từ các Secret mà Release nêu tên, và các mật khẩu từ thông tin xác thực được gắn theo tên khi slot được điền và từ một giá trị phát triển cố định khi không, nên hai lần render với cùng đầu vào tạo ra các byte giống hệt nhau.
- Image có thể tái tạo. Mọi image mà registry chạy đều được ghim vào một
tag tường minh. Sản phẩm phát hành tất cả trên cùng một tag, nên
infra.engine_versionchọn tất cả cùng lúc;infra.overrides.imagethay thế phần ghim của một dịch vụ, vàinfra.overrides.image_prefixchuyển tất cả cùng nhau cho một Release kéo từ một mirror.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example harbor-stackSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd harbor-stackBuild
Workspace này không có .aggrega-config.yaml, nên các thực thể của thư viện chuẩn được phân giải từ registry hub, hub.aggrega.ai, và không cần cờ catalog. Recipe tải về một chart, vì vậy trước tiên hãy phân giải các phụ thuộc vào lockfile:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlCác artifact được render nằm trong dist/.
Trước khi áp dụng chúng, hãy tạo sáu Secret mà Release nêu tên trong namespace
nơi registry được triển khai: harbor-token-key, chứa một khóa riêng RSA dưới
khóa dữ liệu tls.key và một chứng chỉ cho khóa đó dưới tls.crt;
harbor-core-secret, chứa một secret 16 ký tự dưới khóa dữ liệu secret;
harbor-secret-key, chứa một khóa 16 ký tự dưới secretKey;
harbor-csrf-key, chứa một khóa 32 ký tự dưới CSRF_KEY; và
harbor-jobservice-secret cùng harbor-registry-http-secret, chứa một
secret 16 ký tự dưới JOBSERVICE_SECRET và REGISTRY_HTTP_SECRET. Ví
dụ:
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"Một registry mà các dịch vụ của nó không tìm thấy các Secret này sẽ không khởi động.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `harbor-stack`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `harbor-stack` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `harbor-stack` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `harbor-stack`, `release` đặt thành `release-helm-synth.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết lần build đã ghi những tệp nào; chúng nằm trong `harbor-stack/dist/`.Registry sau khi kết hợp trông như thế nào
Bản build xuất ra các tài nguyên mà chart định nghĩa cho cấu hình này:
các Deployment cho reverse proxy, console, control plane, tầng worker
và blob store; các StatefulSet cho backend, cache và
scanner; các persistent volume claim cho blob store và cho log của tầng worker;
các ConfigMap và Secret mà mỗi dịch vụ đọc; và các Service đứng trước
chúng. Bên cạnh đó, Feature thông tin xác thực xuất ra một Secret,
harbor-zdregistry-admin-password, chứa giá trị mặc định dành cho môi trường phát triển của module
cho mật khẩu quản trị viên, mà control plane đọc từ Secret này thay vì
từ Secret riêng của chart. Không có Secret nào được xuất ra cho bất kỳ khóa nào trong sáu khóa:
control plane mount khóa ký token từ harbor-token-key và
khóa mã hóa từ harbor-secret-key, còn các dịch vụ đọc các khóa còn lại từ
harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret và
harbor-registry-http-secret, tức các Secret mà Release chỉ định.
Chỉ đúng một trong các Service đó là địa chỉ mà bên tiêu thụ kết nối tới —
dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:
apiVersion: v1kind: Servicemetadata: name: harbor-zdregistry [… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]spec: type: ClusterIP ports: - name: http port: 80 targetPort: 8080 selector: release: harbor-zdregistry app: "harbor" component: nginxSelector của nó chỉ đến reverse proxy, chính điều này mang lại cho registry một
địa chỉ duy nhất. port theo infra.port; proxy phía sau lắng nghe trên cổng mà
chart cố định và Service chuyển tiếp tới đó, nên thay đổi infra.port sẽ thay đổi
địa chỉ được công bố chứ không thay đổi listener.
Đặt tên: núm điều chỉnh công bố một địa chỉ không phải là núm điều chỉnh đặt tên tài nguyên
Chart này suy ra phần lớn tên tài nguyên của nó từ một núm điều chỉnh tên ở cấp cao nhất rồi
thêm hậu tố vào chúng — Service của control plane là <instance>-core, của
console là <instance>-portal, của blob store là <instance>-registry, và tương tự
cho worker tier, scanner, backend và cache. Không có gì được đặt theo
tên trần.
Service được công bố được đặt tên bởi một núm điều chỉnh riêng, thuộc phạm vi exposure, mà giá trị
mặc định của chính nó là một chuỗi cố định, độc lập với tên ở cấp cao nhất. Một Recipe chỉ ghim
núm điều chỉnh cấp cao nhất sẽ công bố một địa chỉ mà không Service nào đáp ứng, và hai
instance trong cùng một namespace sẽ cùng phát ra một Service dưới chuỗi cố định đó và
xung đột. Vì vậy Recipe đặt cả hai núm điều chỉnh từ ID của instance, đó là lý do
Service được phát ra ở trên được đặt tên theo instance và lý do provides.host chỉ đến
một địa chỉ có tồn tại.
Điều này đáng đọc kỹ khi bao bọc bất kỳ chart nền tảng nào: provides.host
phải chỉ đến Service mà chart thực sự tạo ra, và núm điều chỉnh nào quyết định điều đó
là một thuộc tính của chart chứ không phải một quy ước chung giữa các chart.
Những gì cấu hình này không bao gồm
Ingress của chart được để tắt và thay vào đó reverse proxy được expose dưới dạng một Service nội bộ trong cluster, vì Component công bố một địa chỉ trong cluster chứ không phải một hostname bên ngoài. Một endpoint bên ngoài duy nhất được lắp ráp ở tầng ingress, định tuyến đến địa chỉ mà module này xuất ra. Bảo mật tầng truyền tải bị tắt, vì nguồn chứng chỉ riêng của chart tạo ra một certificate authority và một chứng chỉ đã ký tại thời điểm render, điều mà hai lần render cùng một đầu vào sẽ không tái tạo giống nhau. Monitor của Prometheus-operator bị tắt.
Metrics của registry cũng bị tắt. values.metrics_enabled của Component
bật chúng cho control plane, worker tier, blob store và một
exporter được thêm vào, đồng thời công bố bốn Service để một scraper phát hiện; cùng
thiết lập đó của chart cũng mở debug listener của blob store — profiling,
execution trace và biến runtime, không có kiểm tra bên gọi — cho mọi
bên gọi trong cluster. Module để giá trị đó ở mặc định là false, vì vậy
ví dụ này không render metrics nào; một Aggregate tự khai báo Component có thể
đặt giá trị đó. Dù vậy, image của exporter vẫn được ghim cùng với phần còn lại.