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 existsBa 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 componentdbcó kiểucore/datastore/postgres, mộtappusesnó, 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èmcore/backupcho 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ó:
aggrega scaffold --example postgres-three-realizationsSau đó 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 postgres-three-realizationsBuild
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega 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:
rm -rf dist && aggrega build --release release-managed.yamlVớ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.
- 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.
- 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.netRecipe công bố tên đó làm host thay cho tham chiếu Terraform,
và ứng dụng nhận được nó:
- name: DB_HOST value: db.internal.example.net| biến | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
Đó 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:
[… 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: 5432Khô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- name: DB_HOST value: postgres.data.example.netTham 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 ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers onPhé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ến | tự lưu trữ | được quản lý | bên ngoài |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
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.