Mạng xuyên ranh giới — một ý định, hai cách triển khai
Một stack gồm hai thành phần — giao diện cơ sở dữ liệu Adminer và cơ sở dữ liệu PostgreSQL — được chia qua hai ranh giới, trong đó Adminer phải kết nối tới cơ sở dữ liệu xuyên qua đường nối ranh giới. Cùng một ý định của nhà phát triển được triển khai theo hai cách, và sự tương phản chính là bài học:
- Cục bộ (Docker Compose): mỗi ranh giới là một mạng compose riêng, và một service trong mạng này không thể truy cập một service trong mạng kia theo tên. FeatureRecipe cho compose của Feature
core/compose-bridgetrong thư viện chuẩn tạo ra một gatewayaggrega-gwđể vượt qua đường nối đó. - Kubernetes (Helm): mỗi ranh giới là một namespace riêng, và một pod trong
namespace này truy cập một Service trong namespace khác bằng DNS liên namespace gốc
(
db-default.backend) — không cần cầu nối. Cơ sở dữ liệu công bố một tên service trần; feature định tuyếncore/k8s-dns-resolvercủa bên tiêu thụ bổ sung cho tên đó namespace đích.
compose-bridge chính là những gì namespace của Kubernetes + DNS liên namespace mang lại cho bạn
một cách tự nhiên. Việc vượt qua đường nối là mối quan tâm của Ops/Operator, khác nhau tùy theo đích;
ý định của nhà phát triển không thay đổi. Chính annotation ranh giới aggrega.ai/namespace
đó điều khiển việc đặt mạng compose trong một biến thể và việc đặt namespace
Kubernetes trong biến thể kia.
Ý định chung của nhà phát triển
aggregate.yaml giống hệt nhau cho cả hai biến thể:
components: adminer: type: core/devtool/adminer uses: databases: primary: target: db inject: env: - in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant from: host # ← the target db's provides.host db: type: core/datastore/postgresCạnh uses duy nhất chèn host của cơ sở dữ liệu vào ADMINER_DEFAULT_SERVER.
Host đó phân giải thành gì là mối quan tâm của Ops, được quyết định bên dưới Aggregate — vì vậy
cùng một cạnh cho ra aggrega-gw:5432 với compose và db-default.backend
với helm, mà không thay đổi ý định của nhà phát triển.
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 cross-boundary-networkingSau đó 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 cross-boundary-networkingBuild
Mỗi biến thể là một Release, được build dựa trên thư mục catalog riêng của nó, mỗi lần chạy một Release:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmVớ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 `cross-boundary-networking`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `cross-boundary-networking` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `cross-boundary-networking` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `cross-boundary-networking`, `release` đặt thành `release-compose.yaml`, `catalog_dirs` đặt thành một danh sách chứa `catalog-compose`, `auto_pull` đặt thành true và `write` đặt thành true. Sau đó gọi công cụ `build` theo cách tương tự với `release` đặt thành `release-helm.yaml` và `catalog_dirs` đặt thành một danh sách chứa `catalog-helm`. Hãy cho tôi biết mỗi lần build đã ghi những tệp nào; chúng nằm trong `cross-boundary-networking/dist/`.Biến thể A — cục bộ (Docker Compose): cầu nối
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeMột ranh giới cha bridge chứa hai ranh giới con, frontend (adminer) và backend (db), dùng chung một thư mục nên chúng được hợp nhất thành một tệp dist/bridge/compose/docker-compose.yaml duy nhất. Annotation aggrega.ai/namespace của mỗi ranh giới con trở thành một network của compose. core/compose-bridge, được gắn ở ranh giới cha (phạm vi ranh giới), suy ra một gateway aggrega-gw từ cạnh uses liên network. FeatureRecipe thư viện chuẩn của nó tính toán, một lần cho ranh giới, một bảng các cạnh cần bắc cầu — cả hai đầu nằm trong một tệp compose này, trên các network khác nhau — và mọi thứ bên dưới đều được các template của chính nó đọc từ bảng đó:
valuesMappingcủa nó ghi cấu hìnhstreamcủa nginx cho gateway, được cung cấp dưới dạng một config compose được mount (configs:ở cấp cao nhất, mount tại/etc/nginx/nginx.conf); cấu hình chứa mộtresolvervà một biếnproxy_passcho từng cạnh để upstream được phân giải tại thời điểm kết nối (ký tự$được thoát thành$$để phép nội suy của Compose giữ nguyên nó cho nginx);- cùng
valuesMappingđó nêu tên cả hai đầu dướix-aggrega-networks-ofcủa gateway, mà provider compose phân giải, nên gateway tham gia cả hai network được bắc cầu; injectMappingcủa nó, chạy cho adminer, ghi lạiADMINER_DEFAULT_SERVERcủa bên tiêu thụ thànhaggrega-gw:5432. Việc ghi lại này thay thế giá trị mà kết nốidatabasescủa chính adminer cung cấp; nếu một Feature khác gắn vào adminer đã cung cấp biến đó, quá trình build sẽ dừng và nêu tên cả hai thay vì thay thế nó.
Vì vậy lưu lượng đi theo adminer → aggrega-gw:5432 → proxy_pass db:5432, vượt qua
đường ranh giới network thông qua gateway.
Chạy thử
cd dist/bridge/composedocker compose upMở http://localhost:8080 (máy chủ được điền sẵn aggrega-gw:5432) và đăng nhập:
| Trường | Giá trị |
|---|---|
| Hệ thống | PostgreSQL |
| Máy chủ | aggrega-gw:5432 (điền sẵn) |
| Tên người dùng | appuser |
| Mật khẩu | apppass |
| Cơ sở dữ liệu | appdb |
Thông tin đăng nhập chỉ dành cho demo (được đặt trực tiếp trong recipe db để stack chạy được ngay); một triển khai thực tế sử dụng hệ thống con quản lý thông tin xác thực.
Biến thể B — Kubernetes (Helm): namespace + DNS xuyên namespace
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmCùng một Aggregate, được triển khai lên Kubernetes. Hai ranh giới ngang hàng, mỗi ranh giới có một annotation aggrega.ai/namespace riêng, được lan truyền xuống mọi tài nguyên dưới dạng
metadata.namespace:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendKhông có aggrega-gw. Recipe helm db công bố một tên service trần
trong provides.host — provider helm đặt tên cho Service được tổng hợp là
<rendered_name>-<service-key> (db-default), không kèm namespace. Bên tiêu thụ
gắn feature định tuyến core/k8s-dns-resolver (Release trỏ nó tới
ADMINER_DEFAULT_SERVER), và feature này bổ sung namespace của đích cho host trần đó ngay ở phía bên tiêu thụ — tạo ra tên DNS xuyên namespace
db-default.backend trước khi Adminer được render. Host được suy ra, không phải
viết tay vào bên cung cấp:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>Giá trị đó khớp từng byte với metadata.name +
metadata.namespace của Service db được render, và đó là toàn bộ bằng chứng: DNS xuyên namespace của Kubernetes là
một hợp đồng tất định, nên nếu host được render bằng với định danh Service được render thì nó sẽ phân giải được khi chạy — không cần gateway, không cần cluster đang chạy để kiểm chứng
việc kết nối.
Tính đối ngẫu
| compose (Biến thể A) | helm (Biến thể B) | |
|---|---|---|
| đường ranh giới | các mạng compose riêng biệt | các namespace riêng biệt |
| cơ chế vượt ranh giới | gateway core/compose-bridge (aggrega-gw) | DNS liên namespace gốc |
ADMINER_DEFAULT_SERVER phân giải thành | aggrega-gw:5432 (được viết lại) | db-default.backend (được định danh đầy đủ ở phía bên gọi) |
| tài nguyên bổ sung | service aggrega-gw + cấu hình của nó | không có |
cùng một aggrega.ai/namespace điều khiển | việc đặt vào mạng compose | việc đặt vào namespace k8s |
Một ý định của nhà phát triển; việc vượt qua ranh giới là cơ chế Ops/Operator riêng của từng provider. Cầu nối compose tồn tại vì một mạng compose phẳng không có DNS theo phạm vi namespace; Kubernetes cung cấp sẵn điều đó cho bạn.
Khi hai đầu được kết xuất dưới các provider khác nhau
Cả hai biến thể ở trên đều giữ một ý định duy nhất của nhà phát triển và để việc vượt ranh giới dựa trên một
chuỗi con trỏ tất định: provides.host của cơ sở dữ liệu đi qua
đường nối ranh giới như một con trỏ ổn định, và mỗi đích phân giải con trỏ đó theo cách riêng
của mình — một địa chỉ gateway của compose, hoặc một tên DNS liên namespace. Con trỏ
luôn vượt qua được, vì trình biên dịch chuyển các chuỗi giữa bên sản xuất và
bên tiêu thụ mà không diễn giải chúng.
Một provider có thể đi xa hơn và nối một tham chiếu chéo gốc giữa hai artifact
của chính nó đã được lắp ráp ở hai phía của đường nối — một tham chiếu trong từ vựng riêng của
provider đó mà nền tảng đích phân giải lúc triển khai. Provider
CloudFormation làm điều này cho một cạnh uses vượt qua các stack: stack bên
sản xuất công bố một Export và stack bên tiêu thụ đọc nó bằng
Fn::ImportValue (xem providers/cloudformation.md).
Một tham chiếu chéo gốc là một nâng cấp cùng provider — nó hoạt động vì cả hai
đầu dùng chung một từ vựng artifact, nên một phía có thể công bố một tham chiếu mà
phía kia biết cách phân giải.
Khi một cạnh uses vượt qua ranh giới giữa hai provider khác nhau — bên sản xuất được lắp ráp dưới một provider và bên tiêu thụ dưới một provider khác — thì không thể có tham chiếu chéo gốc. Một tham chiếu được tạo trong từ vựng của một provider không có ý nghĩa gì với provider kia, và trình biên dịch không chuyển dịch giữa chúng: nó chuyển các chuỗi, nó không suy luận ý nghĩa hay viết lại tham chiếu của một provider thành dạng của provider khác. Vì vậy con trỏ tất định của bên sản xuất vượt qua đường nối mà không thay đổi; khi một trong hai provider tự nối các tham chiếu chéo gốc của riêng nó, như CloudFormation làm, trình biên dịch phát ra một cảnh báo nêu tên cả hai điểm cuối, tên cả hai provider, và socket; và quá trình build hoàn tất trên con trỏ đó. Trình biên dịch tin tưởng tác giả và không dừng lại: một con trỏ tất định do tác giả cung cấp hoàn toàn có thể phân giải được qua đường nối — một tên DNS ổn định hoặc một chuỗi nội suy hạ tầng — và chỉ tác giả mới biết topology của đích.
Điều này giữ việc vượt đường nối ở đúng chỗ của nó. Việc một con trỏ liên provider có dùng được hay không là mối quan tâm triển khai thuộc về tác giả; việc chuyển dịch tham chiếu gốc của một provider sang dạng tiêu thụ của một provider khác là công việc mang quan điểm riêng, đặc thù cho từng provider, nằm bên ngoài phần lõi trung lập.
Bố cục
cross-boundary-networking/├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry├── aggregate.yaml # SHARED developer intent (both variants)├── release-compose.yaml # Variant A: parent bridge boundary + two networks├── manifest-compose.yaml├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)├── release-helm.yaml # Variant B: two namespace boundaries, no bridge├── manifest-helm.yaml└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)Ví dụ này sử dụng thư viện chuẩn. Mỗi biến thể được build với --catalog catalog-<variant>, thư mục cục bộ riêng của nó, và phân giải những gì thư mục đó không khai báo từ hub.aggrega.ai, registry mặc định mà .aggrega-config.yaml chỉ định, nên các thực thể cục bộ được phân giải trước các thực thể dùng chung. core/datastore/postgres, component giao diện core/devtool/adminer dùng chung, các Features core/compose-bridge và core/k8s-dns-resolver cùng các FeatureRecipes compose và helm của chúng, cùng các provider compose/helm đều đến từ catalog chuẩn. Phần giữ lại cục bộ là nội dung giảng dạy riêng của ví dụ: các recipe Adminer theo từng target. Recipe db của helm là helm/postgres của thư viện chuẩn, có provides.host là một tên service trần, tự chứa. Bên tiêu thụ định danh đầy đủ nó với namespace của target ở phía bên gọi thông qua feature định tuyến core/k8s-dns-resolver của thư viện chuẩn, nên recipe không mã hóa cứng namespace ranh giới nào.
Hai loại tệp gặp nhau trong một biến thể đã build: các đầu vào do tác giả viết (mọi thứ
ở trên) và đầu ra do trình biên dịch sinh ra trong dist/ (tệp
docker-compose.yaml đã hợp nhất, hoặc các manifest helm theo từng namespace) — bạn không viết
bất kỳ tệp nào thuộc loại sau. dist/ được aggrega build sinh lại và nằm trong gitignore.