Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

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-bridge trong thư viện chuẩn tạo ra một gateway aggrega-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ến core/k8s-dns-resolver củ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/postgres

Cạ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ó:

Terminal window
aggrega scaffold --example cross-boundary-networking

Sau đó 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:

Terminal window
cd cross-boundary-networking

Build

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:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

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 `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

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

Mộ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 đó:

  • valuesMapping của nó ghi cấu hình stream củ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ột resolver và một biến proxy_pass cho 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ưới x-aggrega-networks-of của gateway, mà provider compose phân giải, nên gateway tham gia cả hai network được bắc cầu;
  • injectMapping của nó, chạy cho adminer, ghi lại ADMINER_DEFAULT_SERVER của bên tiêu thụ thành aggrega-gw:5432. Việc ghi lại này thay thế giá trị mà kết nối databases củ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ử

Terminal window
cd dist/bridge/compose
docker compose up

Mở http://localhost:8080 (máy chủ được điền sẵn aggrega-gw:5432) và đăng nhập:

TrườngGiá trị
Hệ thốngPostgreSQL
Máy chủaggrega-gw:5432 (điền sẵn)
Tên người dùngappuser
Mật khẩuapppass
Cơ sở dữ liệuappdb

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

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Cù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: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

Khô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:

dist/frontend/helm/adminer-deployment.yaml
- 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ớicác mạng compose riêng biệtcác namespace riêng biệt
cơ chế vượt ranh giớigateway core/compose-bridge (aggrega-gw)DNS liên namespace gốc
ADMINER_DEFAULT_SERVER phân giải thànhaggrega-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ổ sungservice aggrega-gw + cấu hình của nókhông có
cùng một aggrega.ai/namespace điều khiểnviệc đặt vào mạng composeviệ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.