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ột hợp đồng, ba cách hiện thực

Một cơ sở dữ liệu PostgreSQL và ứng dụng đọc nó, được triển khai theo ba cách khác nhau từ một Aggregate không thay đổi: PostgreSQL chạy trong cluster, PostgreSQL dưới dạng một instance đám mây được quản lý, và một máy chủ PostgreSQL đã tồn tại từ trước khi Release này được triển khai.

Bài học nằm ở những gì không thay đổi. Ứng dụng nêu tên các khóa nó cần từ cơ sở dữ liệu và tên gọi cho chúng, một lần duy nhất. Nó không bao giờ biết cái nào trong ba cái đã trả lời. Trình biên dịch cũng không bao giờ biết: nó đọc các khóa mà Recipe được chọn đã công bố và định tuyến các chuỗi.

Điều duy nhất thay đổi

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

Ba Recipes triển khai cùng một Component. Mỗi Recipe công bố cùng các khóa provides — host, port, user, database, protocol, và các khóa cho biết nơi một trình thu thập tìm thấy số liệu của cơ sở dữ liệu, để trống ở cả ba. Cái nào chạy chỉ là một dòng duy nhất trong Manifest.

Các tệp

  • aggregate.yaml — ý định của nhà phát triển, và là cùng một tài liệu cho cả ba triển khai: một component db có kiểu core/datastore/postgres, một app uses nó, và năm khóa mà ứng dụng yêu cầu. Không có gì ở đây nêu tên một đích triển khai, một đám mây hay một Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — các ánh xạ của Ops. Mỗi ánh xạ chọn cách hiện thực của nó trong một dòng: Recipe nào được gắn với kiểu component PostgreSQL. Ánh xạ được quản lý còn gắn Feature sao lưu mà các Releases của nó đính kèm.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — cấu hình kích thước của người vận hành trong từng Release: dung lượng lưu trữ và phiên bản engine cho triển khai trong cluster, dung lượng lưu trữ, HA và một đính kèm core/backup cho triển khai được quản lý, và địa chỉ của máy chủ hiện có cho triển khai được tham chiếu.
  • release-managed-dns.yaml — Release được quản lý thêm một lần nữa, với tên DNS mà người vận hành đặt cho instance, để ứng dụng nhận được một tên mà nó có thể phân giải.
  • catalog/ — Component riêng của ứng dụng và Recipe duy nhất render nó. Mọi thứ ở phía cơ sở dữ liệu đều lấy từ thư viện chuẩn mà không sửa đổi.

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 postgres-three-realizations

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 postgres-three-realizations

Build

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull ghi tệp khóa của mỗi Release trong lần build đầu tiên của nó; các lần build sau không cần cờ này. Mỗi lệnh ghi vào dist/, và một lần build thêm các tệp của nó thay vì xóa những gì lần trước để lại. Hãy xóa dist/ giữa các lần chạy để đọc riêng đầu ra của một cách hiện thực:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

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ỉ 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 Workspace chưa có thư mục `postgres-three-realizations`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `postgres-three-realizations` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `postgres-three-realizations` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` và `release-external.yaml` — mỗi lần với `workspace_root` đặt thành `postgres-three-realizations`, `release` đặt thành tệp đó, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết mỗi bản dựng đã ghi những tệp nào; chúng nằm trong `postgres-three-realizations/dist/`.

Mỗi cách hiện thực render ra gì

Tự lưu trữ — bản triển khai tự chạy máy chủ

helm/postgres tổng hợp cơ sở dữ liệu bên trong cluster: một StatefulSet, một Service ClusterIP và một Service headless. provides.host là tên trần của Service đó, nên ứng dụng truy cập nó qua DNS nội bộ cluster.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Được quản lý — một nhà cung cấp đám mây chạy máy chủ

terraform/postgres-rds phát ra một aws_db_instance dưới dạng Terraform HCL, và thông số kích thước ha cùng đính kèm core/backup của người vận hành được ánh xạ vào các thiết lập gốc của instance: retention_days: 14 của đính kèm trở thành backup_retention_period = 14 của instance. Ứng dụng vẫn render sang Kubernetes: hai phía của bản triển khai này gặp nhau tại hợp đồng đã công bố của cơ sở dữ liệu, không phải tại một target chung.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Giá trị đó không phải là một hostname, và không có gì trong bản build này biến nó thành hostname. Địa chỉ của một instance RDS chưa tồn tại cho đến khi instance được tạo, nên một trình biên dịch chạy trước (ahead of time) không có gì để tra cứu. Thứ mà Recipe công bố là một tham chiếu Terraform tới một output của chính module cơ sở dữ liệu; trình biên dịch chuyển nó qua cạnh mà không thay đổi, Recipe của ứng dụng nhận nó nguyên văn, và nó được render vào manifest Kubernetes dưới dạng chính các ký tự hiển thị ở trên. Container được trao đúng đoạn văn bản đó.

DB_PORT thì khác: nó render thành "5432", vì Recipe đặt cổng của instance từ Release và công bố chính giá trị đó, một giá trị đã biết trước khi bất cứ thứ gì tồn tại.

Kết nối gốc giữa hai component là việc một target thực hiện bên trong output của chính nó, nên ở đây không có gì để làm. Hai đầu của cạnh này render qua các target khác nhau — cơ sở dữ liệu sang Terraform HCL, ứng dụng sang một manifest Kubernetes — và một tham chiếu Terraform chỉ có ý nghĩa bên trong một cấu hình Terraform. Khi vượt qua ranh giới đó, giá trị đã công bố được chuyển giao dưới dạng văn bản như mọi chuỗi khác. Một bên tiêu thụ được render trên Terraform dưới dạng một Recipe source:, trong cùng cấu hình gốc với cơ sở dữ liệu, sẽ nhận cùng tham chiếu đó như một đối số của module của nó, và ở đó Terraform phân giải nó.

Đây là nguyên tắc chung chứ không phải một trường hợp đặc biệt cho RDS: mọi thứ phụ thuộc vào trạng thái của một hệ thống đang chạy được biểu diễn dưới dạng một con trỏ tất định mà runtime phân giải, không bao giờ là một giá trị mà trình biên dịch tự lấy về. Phần việc của trình biên dịch là chuyển giao con trỏ không thay đổi. Làm cho nó phân giải được tại nơi nó đến là việc của tác giả Recipe: công bố một địa chỉ mà phía tiêu thụ dùng được, hoặc cho cả hai component các Recipes render vào cùng một target.

Đặt cho instance một tên mà ứng dụng có thể phân giải

terraform/postgres-rds nhận cách đầu tiên trong số đó như một tùy chọn do người vận hành đặt. release-managed-dns.yaml là Release được quản lý với một bổ sung duy nhất, tên DNS mà người vận hành đặt cho instance:

db:
infra:
overrides:
host: db.internal.example.net

Recipe công bố tên đó làm host thay cho tham chiếu Terraform, và ứng dụng nhận được nó:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
biếnrelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

Đó là dòng duy nhất của output thay đổi. Recipe không phát ra bản ghi DNS nào và không có alias nào cho tên đó, và bản build không tra cứu nó: trình biên dịch chuyển nó y hệt như đã chuyển tham chiếu. Việc trỏ db.internal.example.net tới instance khi nó đã tồn tại — một bản ghi trong vùng DNS riêng của người vận hành, trỏ tới địa chỉ của instance — là việc của người vận hành, nằm ngoài Release. Khóa này chính là khóa mà cách hiện thực tham chiếu bên dưới đọc cho cùng địa chỉ đó; Recipe này nhận nó dưới dạng một tên trần hoặc một địa chỉ IP, và một giá trị mang scheme, đường dẫn, người dùng hoặc cổng sẽ dừng bản build, vì cổng là infra.port của Release và bên tiêu thụ ghép kết nối của nó từ hai giá trị này.

Một bên tiêu thụ được render vào cùng cấu hình Terraform với cơ sở dữ liệu cũng nhận được tên đó, và cùng với đó mất đi thứ tự mà tham chiếu đã đem lại: Terraform xử lý một module sau module mà nó tham chiếu, còn một cái tên thì không tham chiếu gì cả. Đặt bên tiêu thụ đó vào một ranh giới riêng dùng chung directory: của cơ sở dữ liệu và mang một syncWave: muộn hơn sẽ khôi phục thứ tự.

Bên ngoài — không ai trong bản triển khai này chạy máy chủ

helm/postgres-external không cấp phát gì cả. Toàn bộ output của nó là một Service ánh xạ một tên trong cluster tới địa chỉ mà Release cung cấp:

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

Không StatefulSet, không volume, không container — vòng đời của máy chủ nằm hoàn toàn bên ngoài bản triển khai này. Địa chỉ đến từ Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Tham chiếu một máy chủ không giống với việc tiếp quản nó. Recipe này truy cập một máy chủ vẫn thuộc quyền sở hữu bên ngoài; không có gì ở đây đưa nó vào sự quản lý của bản triển khai, và không có gì ở đây sẽ thay đổi nó.

Bỏ trống địa chỉ thì bản build dừng lại và báo rõ điều đó. Một máy chủ được tham chiếu hoặc có địa chỉ hoặc không có gì, nên Recipe từ chối thay vì phát ra một Service làm alias cho một tên rỗng:

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

Phép so sánh là mục đích chính

Môi trường đã kết xuất của ứng dụng, cả ba đặt cạnh nhau:

biếntự lưu trữđược quản lýbên ngoài
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Cùng các biến, cùng thứ tự, lần nào cũng vậy. Chỉ chuỗi đằng sau một trong số chúng thay đổi. Recipe của ứng dụng không đặt tên biến DB_ nào: nó xuất ra bất cứ thứ gì mà cạnh uses đã phân giải, đó là lý do một Recipe kết xuất không thay đổi trên cả ba cơ sở dữ liệu.

Và trình biên dịch không biết bất kỳ chuỗi nào trong số đó là gì. db-default là tên một Service của Kubernetes, ${module.db.address} là một tham chiếu Terraform, postgres.data.example.net là một tên DNS — với trình biên dịch, chúng là ba chuỗi mà một Recipe đã công bố dưới khóa host và một cạnh yêu cầu được chuyển giao dưới dạng DB_HOST. Nó không kiểm tra xem chuỗi nào trong số đó có định tuyến được không, hay một cổng có phải là số không, hay một thành phần tên db có phải là cơ sở dữ liệu không. Nó đã khớp cạnh theo nhãn mà Component mang, đọc khóa mà hợp đồng khai báo, và chuyển văn bản đi.

Đường ranh giới nằm ở đâu

Mỗi trong ba bản triển khai được chọn bởi một ánh xạ của Ops, và tài liệu của nhà phát triển không hề bị thay đổi bởi lựa chọn đó. Đó chính là sự phân tách mà toàn bộ ví dụ này tồn tại để làm cho cụ thể:

  • nhà phát triển nói ứng dụng cần gì từ một cơ sở dữ liệu;
  • Ops nói một cơ sở dữ liệu được tạo thành từ những gì — mỗi cách hiện thực là một Recipe;
  • người vận hành nói bản triển khai này nhận cách nào, và định kích thước cho nó.

Ngày mai hãy thêm một cách hiện thực thứ tư — một đám mây khác, một nhà vận hành khác, một dịch vụ Compose cho công việc cục bộ — và đó chỉ là thêm một Recipe công bố cùng các khóa đó, cộng với một dòng Manifest. Tệp aggregate.yaml trong thư mục này không thay đổi.