Ngăn xếp APISIX — một API gateway động được kết hợp dưới dạng module
Ví dụ này biên dịch một ngăn xếp nhỏ, có thật — một API gateway động — thành
các manifest Kubernetes được tổng hợp từ một Aggregate do Developer soạn.
Gateway không phải là một component đơn lẻ. Nó là một module: một aggregate con có thể tái sử dụng, kết hợp hai component đơn workload —
- một gateway kết thúc lưu lượng của client trên cổng proxy của nó và không giữ trạng thái cục bộ nào, và
- một store, etcd, giữ cấu hình của gateway và lưu trữ bền vững cấu hình đó trên một volume.
Module tự nối cạnh nội bộ của mình từ gateway tới store và xuất
gateway làm endpoint công khai proxy của nó. Aggregate cấp cao nhất nhập
module theo tên và kết xuất ngăn xếp đã kết hợp; operator định cỡ các component
nội bộ của module trong Release.
Các tệp
| Tệp | Vai trò |
|---|---|
aggregate.yaml | Ý định của Developer: nhập module API gateway (core/apisix) và truyền cho nó khóa Admin API của gateway từ một tham số của chính nó. |
manifest-helm-synth.yaml | Ánh xạ các kiểu gateway và store tới các Recipes synth helm của chúng, và ánh xạ Feature thông tin xác thực mà module gắn vào tới hiện thực đọc một Secret đã có sẵn trong namespace. |
release-helm-synth.yaml | Bản ghi của operator cho đích Kubernetes. Đặt tên Secret chứa khóa Admin API, và định cỡ các component nội bộ của module theo ID trong phạm vi module củ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ì
- Kết hợp dưới dạng module. Một năng lực nhiều workload — một API gateway mà thực chất là một proxy cộng với một kho cấu hình — được đóng gói thành một aggregate con kết hợp hai component đơn workload, chứ không phải một component nguyên khối. Module được nhập theo tên và tái sử dụng ở bất cứ đâu cần một gateway.
- Một cạnh nội bộ bên trong module. Gateway khai báo việc sử dụng
store; host và port
providescủa Recipe store được chuyển vào gateway và kết hợp thành kết nối etcd của nó. Trình biên dịch định tuyến các chuỗi mà không diễn giải chúng. - Một endpoint công khai. Module xuất gateway của nó dưới tên
proxy, tên công khai ổn định mà bên sử dụng kết nối tới — tách biệt khỏi tên các component nội bộ của module. - Operator định cỡ các component nội bộ. Release tham chiếu các component
nội bộ của module theo ID trong phạm vi module (
gateway.store,gateway.gateway) để đặt tài nguyên tính toán, mà Aggregate của developer không phải nêu lại kích cỡ vật lý. - Một tệp cấu hình được mount bên cạnh các tệp được ghi lúc chạy. Gateway đọc cấu hình từ một tệp trong thư mục mà nó cũng ghi vào khi khởi động. Recipe phát ra cấu hình đó dưới dạng ConfigMap và mount nó thành một tệp đơn, nhờ đó cấu hình gateway mà không che khuất các tệp gateway ghi vào đó.
- Khóa Admin API được đọc từ một Secret. Gateway quản trị các route của nó
thông qua Admin API, và khóa của nó đến qua một khe thông tin xác thực trên
gateway, khe mà gateway yêu cầu khi không có gì được nối vào socket models
của nó, như ở đây, nên không có khóa mặc định. Module nhận khóa dưới dạng
tham số
admin_key, và gắn Feature thông tin xác thựccore/referenced-secretvào khe với khóa đó; Aggregate này khai báo một tham số của riêng nó và truyền xuống, và Release cung cấp giá trị cho tham số đó. Manifest ánh xạ Feature tớik8s-existing-secret, nên giá trị là tên của một Secret đã tồn tại trong namespace: bản build không đọc khóa nào và không kết xuất khóa nào, và gateway đọc khóa từ Secret đó khi khởi động. Một Release không cung cấp giá trị sẽ dừng bản build, kèm tên tham số. - Image có thể tái tạo. Cả gateway và store đều ghim tag image tường minh, nên các manifest được kết xuất tham chiếu các image ổn định.
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 apisix-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 apisix-stackBuild
Workspace này không có .aggrega-config.yaml, nên các thực thể thư viện chuẩn được phân giải từ registry hub, hub.aggrega.ai, và không cần cờ catalog; --auto-pull ghi trong lúc build lockfile mà một bản clone mới còn thiếu:
aggrega build --release release-helm-synth.yaml --auto-pullCác artifact được kết xuất nằm trong dist/. Đích Kubernetes kết xuất manifest
thuần ở chế độ ngoại tuyến — không cần kéo chart.
Trước khi áp dụng chúng, hãy tạo Secret mà Release đặt tên, apisix-admin-key,
trong namespace đích, chứa một khóa của riêng bạn dưới data key
admin-key. Khóa không được để trống, vì điều đó làm gateway dừng khi khởi động,
và không được là giá trị mà APISIX đọc thành số hoặc true hay false, chẳng hạn
một khóa toàn chữ số, vì khi đó APISIX không bao giờ so khớp nó với khóa mà một
request đưa ra.
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 `apisix-stack`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `apisix-stack` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `apisix-stack` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `apisix-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 bản build đã ghi những tệp nào; chúng nằm trong `apisix-stack/dist/`.Ngăn xếp đã kết hợp trông như thế nào
Gateway được kết xuất thành một Deployment không trạng thái cộng với một Service ClusterIP trên cổng proxy. Cấu hình của nó được cung cấp dưới dạng ConfigMap mount thành một tệp đơn vào thư mục conf của container; cấu hình chứa tên Service trong cluster của store và, tại vị trí của khóa Admin API, tên của biến môi trường mà APISIX đọc khóa từ đó khi nạp tệp:
apisix: node_listen: 9080deployment: role: traditional role_traditional: config_provider: etcd admin: [… omitted: the client range the Admin API accepts] admin_key: - name: admin key: ${{APISIX_ADMIN_KEY}} role: admin admin_listen: ip: 0.0.0.0 port: 9180 etcd: host: - "http://gateway-zdstore-default:2379" prefix: "/apisix" timeout: 30Deployment cung cấp biến đó từ Secret, nên khóa không xuất hiện trong tệp được kết xuất nào:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-keyStore được kết xuất thành một StatefulSet với một persistent volume mount tại
/etcd-data, cộng với một Service ClusterIP và một headless Service.