Compose Provider
Compose provider kết xuất các Aggrega Recipes thành một tệp Docker Compose. Provider lắp ráp theo từng (path, provider): các thành phần đóng góp compose của mọi ranh giới được định tuyến đến bộ lắp ráp có khóa là directory: đã được đánh giá của ranh giới, nối với subDirectory: của từng component, và bộ lắp ráp đó xuất ra một docker-compose.yaml chứa mọi thành phần đóng góp tại đường dẫn đó. Hai ranh giới anh em được đánh giá ra cùng một đường dẫn sẽ gộp thành một tệp compose hợp nhất duy nhất — ví dụ điển hình là một ranh giới cha cùng hai ranh giới con có directory: "{{ .parent_boundary.directory }}" (mẫu compose-bridge).
Các loại đầu vào được hỗ trợ
Compose provider chấp nhận cả ba loại đầu vào của Recipe:
- Chế độ sourced. Một Recipe có
source:trỏ tới một tệp compose có sẵn cùng vớivaluesMapping:tạo ra một tài liệu overlay. Tệp compose gốc được nạp, overlay được đánh giá, và hai tài liệu được hợp nhất sâu theo ngữ nghĩa overlay gốc của docker-compose. - Chế độ Workload. Một Recipe có
workload:(khai báo trực tiếp hoặc nạp qua$import:) khai báo một tài liệuWorkload. Provider tổng hợp một hoặc nhiều service compose từ đặc tả Workload. - Chế độ artifacts. Các mục
artifacts:của một Recipe được đánh giá thành các đoạn compose, và chúng được hợp nhất vào tệp đã lắp ráp theo các quy tắc trong Các đoạn compose do artifacts tạo ra. Artifacts có thể đi kèm một source hoặc một Workload, và cũng có thể là toàn bộ đầu ra của một Recipe: một Recipe khai báoartifacts:mà không cósource:lẫnworkload:vẫn được kết xuất ở đây, đóng góp bất cứ thứ gì các đoạn của nó khai báo. Đó là cách một component chỉ gồm tài nguyên — một bộ network và volume dùng chung, một cấu hình được khởi tạo sẵn — đến được một triển khai compose mà không cần một Workload giữ chỗ đại diện cho phần tính toán mà nó không có.
Ba loại này kết hợp theo kiểu cộng dồn, và một Recipe không khai báo loại nào sẽ bị từ chối khi được nạp. Một valuesMapping: không có source: đi kèm cũng bị từ chối khi Recipe được nạp, bất kể nó chỉ định provider nào: không có gì để áp dụng overlay lên, và chẩn đoán yêu cầu bạn khai báo con trỏ source: hoặc bỏ valuesMapping:.
Ánh xạ tính năng Workload
Khi một Recipe khai báo workload:, provider chuyển đổi hình dạng Workload do nền tảng sở hữu thành các nguyên thủy compose. Việc ánh xạ được cố ý giữ hẹp — bề mặt của Compose nghèo hình dạng hơn Kubernetes, và một số tính năng của Workload bị suy giảm về tương đương compose gần nhất với mất mát được ghi lại.
Các trường container
| Trường Workload | Trường Compose |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint (dạng danh sách) — nó ghi đè điểm vào của image, và đó là khóa compose làm việc này |
args | command (dạng danh sách) — nó cung cấp các đối số mà điểm vào nhận, và đó là thứ mà command của compose ghi đè |
variables | environment (dạng map) |
attachments[as: env] | mục environment có giá trị rỗng, kèm một cảnh báo nêu tên mục đó (xem Những gì compose provider không cung cấp) |
attachments[as: file] | bind-mount dạng dài trong volumes, chỉ đọc |
volumeMounts | nguyên thủy compose mà biến thể Volume được tham chiếu ánh xạ tới — một mục dạng dài trong volumes, một mục tmpfs: cấp service, hoặc một tham chiếu configs: cấp service (xem Volumes) |
ports | ngầm định (các container compose để lộ các cổng mà image lắng nghe) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables và attachments[as: env] cùng nằm trong một map environment, các mục attachment trước và variables sau, mỗi loại theo thứ tự được viết — đúng thứ tự mà helm provider ghi ra, nên một Workload tạo ra một chuỗi biến môi trường như nhau trên mọi đích. Compose không mở rộng tham chiếu $(NAME) nào giữa các mục môi trường của một service, nên trên compose thứ tự đó không mang ý nghĩa gì lúc chạy. Vì map chỉ giữ mỗi tên một lần, một container đưa cùng một tên vừa là mục variables vừa là mục attachments được cung cấp as: env sẽ dừng bản build thay vì giữ một trong hai giá trị (xem A container gives one environment variable two values (Một container gán hai giá trị cho một biến môi trường)).
Tài nguyên container
resources của một container được đưa vào khối deploy.resources của compose, mà docker compose tôn trọng ở chế độ không phải swarm. requests của Kubernetes biểu thị mức tối thiểu được đảm bảo, nên chúng trở thành reservations của compose; limits biểu thị mức trần cứng, nên vẫn là limits.
| Trường Workload | Trường Compose | Chuyển đổi |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | Số lõi dạng thập phân. Số lõi viết dưới dạng số trần (2, 0.5) được xuất ra như đã viết; mọi dạng khác được chuyển đổi từ giá trị của nó (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | Chuyển đổi tương tự |
resources.requests.memory | deploy.resources.reservations.memory | Số byte chính xác, được chuyển đổi từ giá trị dù viết ở dạng nào — 8Gi thành 8589934592, 1.5Gi thành 1610612736, 1e3 thành 1000 |
resources.limits.memory | deploy.resources.limits.memory | Chuyển đổi tương tự |
nvidia.com/gpu, trong resources.limits, resources.requests hoặc cả hai | deploy.resources.reservations.devices | Một mục thiết bị NVIDIA trên service của container — driver: nvidia, count: là số GPU, capabilities: [gpu]. Số lượng là của limit nếu có viết limit — số mà Kubernetes lập lịch cho một tài nguyên mở rộng — và của request trong trường hợp còn lại. Số lượng 0 không yêu cầu GPU nào và không ghi mục nào |
mọi khóa tài nguyên mở rộng khác — amd.com/gpu và mọi <domain>/<name> khác | — | Không có tương đương compose trên một host đơn. Khóa bị loại bỏ và bản build đưa ra một cảnh báo unsupported-field nêu tên nó, mỗi khóa riêng biệt một cảnh báo dù bao nhiêu trong số requests và limits mang nó. Giá trị của nó không được xuất ra, nên không được kiểm tra |
Mỗi giá trị cpu, memory và nvidia.com/gpu được đọc như một số lượng, theo dạng nêu trong Workload → Số lượng tài nguyên, trên Workload như các template của Recipe đã đánh giá nó. Hai trường hợp dừng bản build với TRANSLATION_ERROR, và lỗi cho biết đã gặp trường hợp nào, nêu đường dẫn của container, giá trị là request hay limit, tài nguyên và giá trị:
- một giá trị không phải là số lượng —
lots,1.5 cores, hoặcmmà một template rỗng để lại trong"{{ .infra.cpu }}m"; - một số lượng mà compose không thể biểu diễn chính xác — một lượng âm; một lượng bộ nhớ không phải là số byte nguyên (
1500m,4u) hoặc lớn hơn 9223372036854775807 byte (8Ei); một lượng cpu mịn hơn chín chữ số thập phân của một lõi, độ chính xác mịn nhất mà chính một số lượng Kubernetes giữ, hoặc lớn hơn 9223372036.854775807 lõi; một số GPU không phải là số thiết bị nguyên (0.5,500m).
Một container có request và limit nvidia.com/gpu yêu cầu số lượng khác nhau cũng dừng theo cách tương tự, nêu cả hai đường dẫn: compose chỉ dành một số lượng cho một service, nên nếu không thì bản chuyển đổi sẽ phải chọn một. Hãy viết cùng một số lượng ở cả hai, hoặc chỉ viết limit.
Không có gì được làm tròn, và không giá trị nào được xuất ra mang nghĩa khác.
Một request GPU dành riêng GPU NVIDIA. Một container của Workload yêu cầu nvidia.com/gpu: "1" tạo ra một service mang phần dành riêng này, bên cạnh mọi cpus và memory mà các request của nó dành riêng:
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose giao các GPU đã dành riêng cho container khi host Docker có đủ số GPU NVIDIA đó và được thiết lập để cấp chúng cho container; bản build không thể nhìn thấy host, nên một tệp dành riêng GPU được lắp ráp như nhau ở bất cứ nơi nào nó sẽ chạy. Mục này luôn nêu số lượng, vì Compose đọc một mục thiết bị không có số lượng là mọi GPU trên host. Chỉ khóa NVIDIA được chuyển đổi: amd.com/gpu và khóa của mọi nhà cung cấp khác vẫn nhận cảnh báo của hàng khóa bị loại bỏ. Hàng runtimeClassName trong Các trường cấp pod không thay đổi — compose không có tương đương runtime-class, nên một Workload nêu tên một runtime hỗ trợ GPU được báo rằng runtime đã bị bỏ qua, trong khi số GPU của nó vẫn được dành riêng.
Probe
Ba khe probe của một Workload (live, ready, startup) gộp lại thành một healthcheck duy nhất của compose cho mỗi service, với thứ tự ưu tiên live > ready > startup (tín hiệu liveness chuẩn nhất thắng). Khi việc gộp đó loại bỏ một khe mà tác giả đã khai báo, bản build đưa ra một cảnh báo unsupported-field nêu tên khe được chuyển đổi và các khe bị loại bỏ, để ý định không đến được phần nào của đầu ra được báo cáo thay vì bị mất. Một khối health khai báo một khe được chuyển đổi không mất mát và không đưa ra gì, trừ khi khe đó đặt successThreshold: healthcheck của compose không có trường cho nó, nên giá trị do tác giả viết — kể cả 1 — bị bỏ qua kèm một cảnh báo unsupported-field nêu tên nó (containers.<name>.health.<slot>.successThreshold), và phần còn lại của khe được chuyển đổi như bảng dưới đây cho thấy.
| Hình dạng probe của Workload | healthcheck.test của Compose |
|---|---|
http: /path | ["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"] |
tcp: <port> | ["CMD-SHELL", "nc -z localhost <port>"] |
exec: [cmd, ...] | ["CMD", cmd, ...] |
Dạng HTTP yêu cầu container khai báo ít nhất một cổng có tên; bộ tổng hợp chọn tên cổng đứng đầu theo thứ tự bảng chữ cái và dùng số của nó để dựng URL curl. Các container không khai báo cổng nào không thể dùng probe HTTP — trình biên dịch dừng với TRANSLATION_ERROR nêu tên probe vi phạm.
Các trường thời gian chờ của probe ánh xạ tới các chuỗi thời lượng kiểu compose:
| Trường Workload | Trường healthcheck của Compose |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
Volume
Compose có một primitive config riêng, và đó là thứ mà một volume configmap được chuyển thành. Compose không có tương đương Kubernetes cho Secret hay cho các mẫu volume theo từng bản sao, nên các biến thể đó bị suy giảm thành primitive compose gần nhất:
| Biến thể volume của Workload | Bản chuyển đổi Compose | Ghi chú về mất mát |
|---|---|---|
ephemeral | mục danh sách tmpfs: ở cấp service | sizeLimit không được giữ lại (dạng rút gọn tmpfs của compose không có kích thước). Một sizeLimit được khai báo sẽ phát sinh cảnh báo unsupported-field nêu tên nó tại tọa độ khai báo (volumes.<name>.ephemeral.sizeLimit), bất kể có container nào mount volume hay không; bỏ trường này đi thì không phát sinh gì |
configmap | tham chiếu configs: ở cấp service nêu tên configmap, được mount tại đường dẫn mount của volume | 🔴 Đường dẫn mount là đường dẫn của một tệp duy nhất, không phải của một thư mục. Compose ghi nội dung của config vào chính xác đường dẫn đích, trong khi một đích Kubernetes mount một ConfigMap tại một đường dẫn sẽ tạo ra một thư mục chứa mỗi khóa một tệp. Vì vậy cùng một path: được khai báo biểu thị một tệp ở đây và một thư mục ở kia: hãy trỏ mount của volume configmap vào tên tệp mà container cần đọc (/seed/config.json), không phải vào thư mục chứa nó, và một Recipe được viết cho cả hai đích sẽ mang một đường dẫn khác nhau cho mỗi đích. Không gì trong quá trình build có thể phát hiện một đường dẫn được viết cho dạng của đích kia — đường dẫn là một chuỗi mờ mà compiler chuyển qua nguyên vẹn, và đầu ra được tạo hợp lệ theo cả hai cách. Tham chiếu là theo tên, đúng như cách một đích Kubernetes tham chiếu một tài nguyên ConfigMap — không gì đọc nội dung của config. Mục configs: cấp cao nhất tương ứng đến từ đầu vào artifacts: của Recipe, có đoạn compose khai báo nó với content: nội tuyến; một tham chiếu không có mục như vậy sẽ dừng build (xem Các đoạn compose do artifacts tạo ra). Một tham chiếu configs: chỉ mang tên config và đường dẫn mount, không gì khác, nên readOnly của mount không có biểu đạt riêng |
secret | bind-mount dạng dài trong volumes, chỉ đọc | Một volume secret cố ý không theo cách chuyển đổi của configmap: một mục configs: nội tuyến sẽ ghi giá trị của secret vào tệp compose được tạo dưới dạng văn bản thuần, mà compiler không bao giờ phân giải một secret thành văn bản thuần — một secret vẫn là một con trỏ qua mọi giai đoạn của build. Nguồn bind là tên source của secret, được phân giải như một đường dẫn mà người vận hành làm cho truy cập được trên máy chủ compose, độc lập với build |
persistent | volume có tên + khai báo volumes: { <volume-name>: {} } cấp cao nhất, được đặt tên theo Cách suy ra tên volume | Lớp lưu trữ, chế độ truy cập và kích thước không được giữ lại (compose không có hình dạng tương đương). Một class hoặc accessModes được viết ra sẽ phát sinh một cảnh báo unsupported-field nêu tên nó tại tọa độ nơi nó được viết (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); bỏ qua cả hai thì không phát sinh gì. size bắt buộc không phát sinh cảnh báo — xem bên dưới |
persistentTemplate | volume có tên + khai báo cấp cao nhất, được đặt tên theo cùng cách (giống persistent) | Đi kèm form: stateful; compose không có primitive tạo mẫu volume theo từng bản sao, nên hành vi theo từng bản sao bị mất, và một cảnh báo unsupported-field cho biết volume đã trở thành một volume duy nhất mà mọi bản sao dùng chung. Lớp lưu trữ, chế độ truy cập và kích thước không được giữ lại, giống hệt như với persistent: một class hoặc accessModes được viết ra sẽ phát sinh một cảnh báo unsupported-field tại volumes.<name>.persistentTemplate.class hoặc volumes.<name>.persistentTemplate.accessModes, còn size bắt buộc thì không phát sinh cảnh báo nào |
subPath của một mount gắn một phần của volume ở nơi compose có dạng cho việc đó. Một mục volumeMounts chỉ đến một volume persistent hoặc persistentTemplate với subPath sẽ trở thành một mục volumes dạng đầy đủ mang volume.subpath, vì vậy mount nhìn thấy thư mục hoặc tệp được nêu tên bên trong volume thay vì thư mục gốc của nó, và hai mount của cùng một volume với hai giá trị subPath khác nhau nhìn thấy hai phần khác nhau của volume đó:
volumes: - type: volume source: store--data target: /var/lib/app/db volume: subpath: db - type: volume source: store--data target: /var/lib/app/uploads volume: subpath: uploadsMột mount được viết mà không có subPath không mang khối volume:. Một subPath trên mount của volume ephemeral, configmap hoặc secret sẽ dừng bản build với TRANSLATION_ERROR, nêu tên component, container, đường dẫn đã viết của mount (containers.<name>.volumeMounts[<i>]), volume và subPath: các biến thể đó đến compose lần lượt dưới dạng một mục tmpfs, một tham chiếu configs: và một bind mount, không cái nào trong số đó gắn một phần của những gì nó cung cấp, nên nếu không dừng lại thì mount sẽ nhìn thấy toàn bộ volume. Hãy xóa subPath khỏi mount như vậy, hoặc gắn một volume persistent. Docker Compose đọc volume.subpath từ bản phát hành 2.26.0, trên Docker Engine 26.0 trở lên; bản build không thể nhìn thấy máy chủ sẽ chạy tệp, nên một tệp mang nó được lắp ráp theo cùng một cách bất kể nó sẽ chạy ở đâu.
Một volume cho biết nó là biến thể nào và không gì hơn. Một volume secret có đúng một cách chuyển đổi — bind mount chỉ đọc ở trên — và một volume không có trường as: để chọn cách khác. Việc cung cấp những gì một slot đã công bố dưới dạng biến môi trường là một mục attachments của container (as: env) chứ không phải một volume; compose làm gì với mục đó được trình bày tại Những gì compose provider không cung cấp.
Ba biến thể mang kích thước lưu trữ, và chỉ một trong số đó cảnh báo rằng kích thước đã bị bỏ. Khác biệt nằm ở chỗ bạn có được lựa chọn hay không. sizeLimit của một volume ephemeral là tùy chọn, nên việc viết nó là một quyết định, và cảnh báo cho bạn biết giá trị đó không định hình gì trên đích này và có thể xóa đi — cảnh báo chỉ mang tính tư vấn và nằm ngoài luồng, tệp được tạo giống hệt từng byte như khi không có nó, và --no-unsupported-field-warnings tắt nó cùng với cả lớp cảnh báo. size của một volume persistent hoặc persistentTemplate là bắt buộc, nên không phiên bản nào của tài liệu bỏ nó đi: một cảnh báo mỗi lần build ở đó sẽ xuất hiện với mọi workload stateful mà không nêu gì bạn có thể thay đổi, nên khác biệt này được giải thích ở đây thay vì được báo cáo mỗi lần build. Khi nhắm tới compose, size, class và accessModes của một volume persistent không định hình gì trong tệp được tạo — thứ bạn nhận được là một volume có tên thông thường, với kích thước và nền lưu trữ theo mặc định của volume driver trên máy chủ compose. class và accessModes là tùy chọn, nên mỗi trường bạn viết ra đều được báo cáo giống như sizeLimit của một volume ephemeral: một cảnh báo unsupported-field cho mỗi trường, mang tính tư vấn và nằm ngoài luồng, được tắt bằng cùng một cờ. Hãy định kích thước bộ lưu trữ bên dưới trên máy chủ, hoặc trên đích Kubernetes nơi các trường này thực sự đi tới đầu ra.
Một volume không được container nào mount sẽ phát sinh cảnh báo unsupported-field nêu tên nó tại tọa độ khai báo (volumes.<name>), vì khi đó những gì đi tới tệp được tạo khác biệt rõ rệt theo biến thể. persistent và persistentTemplate vẫn tạo khai báo cấp cao nhất của chúng, nên volume được tạo ra mà không gì dùng đến. ephemeral, configmap và secret không có biểu đạt nào ngoài chính mount — mỗi loại lần lượt được chuyển thành thứ được ghi tại đường dẫn mount, một mục tmpfs, một tham chiếu configs hoặc một bind-mount — nên khi không có gì mount, volume bạn khai báo hoàn toàn không để lại dấu vết trong đầu ra. Trường hợp thứ hai này là lý do cảnh báo tồn tại: nếu không có nó, một volume configmap mà bạn quên mount sẽ đơn giản là vắng mặt, không có gì trong tệp được tạo để nhận ra. Mọi container của workload đều được tính là bên mount, kể cả init container, nên một volume chỉ được một init container mount vẫn được nối và không phát sinh gì. Cảnh báo chỉ mang tính tư vấn và nằm ngoài luồng — tệp được tạo giống hệt từng byte như khi không có nó — và --no-unsupported-field-warnings tắt cả lớp cảnh báo này.
Cách suy ra tên volume
Một volume persistent hoặc persistentTemplate trở thành một named volume của compose: một mục volumes: cấp cao nhất, được tham chiếu bởi mọi container gắn nó. Một volume compose là bộ nhớ dùng chung, và khối volumes: cấp cao nhất hợp nhất các mục của nó theo tên — vì vậy hai volume được khai báo mà rơi vào cùng một tên sẽ trở thành một volume mà cả hai container cùng ghi vào, không có gì trong tệp được xuất ra cho thấy rằng ý định là hai volume. Do đó, tên được xây dựng từ hai định danh cùng nhau cho biết đó là volume nào: <component> mà volume thuộc về, và tên mà Workload đặt cho volume dưới volumes:.
Tên volume compose chấp nhận một tập ký tự hẹp hơn so với những gì mỗi định danh có thể chứa: chữ cái, chữ số, dấu chấm, dấu gạch dưới và dấu gạch nối. Thay vì thay thế một ký tự mà compose không chấp nhận, quá trình suy ra sẽ viết nó ra, nên hai volume khác nhau dù chỉ một chút sẽ cho ra hai tên — và một tên đã ghép có thể được đọc ngược lại thành hai định danh tạo nên nó.
- Chữ cái, chữ số, dấu chấm và dấu gạch dưới được giữ nguyên đúng như khi khai báo.
- Dấu gạch nối được giữ nguyên như khi khai báo ở bất cứ đâu mà ký tự sau nó được giữ nguyên trực tiếp và không phải là chữ thường
z. Dấu gạch nối theo sau bởi chữ thườngzmở đầu một chuỗi thoát, nên một dấu gạch nối được khai báo ở vị trí đó sẽ tự nó được viết ra —api-zonetrở thànhapi-zhzone, đây chính là điều cho phép đọc ngược bất kỳ tên nào mà không cần đoán. Dấu gạch nối không có gì phía sau cũng được viết ra vì cùng lý do, nêndb-cho radb-zh. - Mọi ký tự khác được viết thành
-ztheo sau bởi một chữ cái định danh nó:scho dấu phân cách đường dẫn,hcho dấu gạch nối mà quy tắc trên không giữ. Bất kỳ ký tự nào khác — kể cả dấu cách và chữ cái không thuộc ASCII — được viết thànhxvà code point thập lục phân sáu chữ số của ký tự đó, còn một byte không bắt đầu ký tự nào được viết thànhbvà giá trị hai chữ số của chính nó, nên một tên không phải là văn bản hợp lệ vẫn được viết ra một cách phân biệt thay vì bị gộp lại. - Giá trị rỗng được viết là
-ze, điều mà không giá trị không rỗng nào có thể tạo ra. - Hai định danh được nối bằng
--. Một định danh đã mã hóa không bao giờ chứa cặp đó, nên tên đã nối cho biết rõ ràng nơi một định danh kết thúc và định danh kia bắt đầu.
Vì vậy, component store với một volume mà Workload gọi là data cho ra tên volume store--data, và db-server với data cho ra db-server--data. Cùng một đầu vào luôn tạo ra cùng một tên.
Dấu nối kép là điều làm cho cặp định danh không mơ hồ, và dấu nối một ký tự thì không thể. Mỗi định danh đều có thể tự chứa dấu gạch nối, nên dấu nối một gạch để lại một tên có thể chia tách ở nhiều chỗ: db với volume tên data-cache và db-data với volume tên cache đều sẽ thành db-data-cache, và vì khối cấp cao nhất hợp nhất theo tên, hai component sẽ dùng chung một volume mà không có gì trong tệp được xuất ra cho thấy điều đó. Một định danh đã mã hóa không bao giờ chứa cặp dấu gạch nối, nên dấu nối kép không cho phép cách đọc thứ hai: hai trường hợp trên thành db--data-cache và db-data--cache.
Thay đổi một trong hai định danh sẽ đổi tên volume compose, và compose không đổi tên volume tại chỗ. Volume được tạo mới dưới tên mới trong khi volume cũ vẫn còn lại cùng dữ liệu bên trong, nên container khởi động với bộ nhớ trống và nội dung nằm trong một volume không được gắn vào đâu. Chỉ đổi tên một định danh như một sự thay thế cần lập kế hoạch — sao lưu, sao chép sang, hoặc lên lịch — thay vì như một thay đổi để triển khai.
Dạng controller
form của Workload chọn một dạng controller trừu tượng (xem entities/workload.md). Compose kết xuất stateless và stateful (và giá trị mặc định rỗng, được coi là stateless) thành các service chạy lâu dài; dạng stateful bổ sung named volume cho một volume đi kèm persistentTemplate. Các dạng daemon, scheduled và task không có ánh xạ compose đơn máy chủ rõ ràng, nên một Workload khai báo một trong các dạng này nhắm tới một boundary compose sẽ dừng với TRANSLATION_ERROR nêu tên dạng đó và tập được hỗ trợ — compose không hạ cấp một dạng không được hỗ trợ thành một service thông thường làm sai lệch ý định. Một Workload dạng reference khai báo một endpoint bên ngoài và không có container nào, nên compose không phát ra service nào cho nó.
Vì không có service nào được phát ra cho một Workload reference, không gì đọc đường ống phân phối của component mà nó hiện thực hóa: một thông tin xác thực được gắn vào component đó — được phân phối trên đường ống của nó bởi dotenv-secret, hoặc bởi khối inject: riêng của một attachment — sẽ không đến được tệp đầu ra nào. Vì vậy, mọi Compose Recipe của thư viện chuẩn hiện thực hóa một dịch vụ bên ngoài theo cách này, và có Component khai báo một khe thông tin xác thực, đều từ chối thông tin xác thực điền vào khe đó: bản build dừng lại và nêu tên khe và component, thay vì thành công khi thiếu thông tin xác thực. Trên compose, thông tin xác thực cho một dịch vụ bên ngoài được gắn vào component gọi dịch vụ đó, dưới biến môi trường mà component đó đọc. Sự từ chối đó là khẳng định riêng của từng Recipe, và nó chạy trước khi provider này kết xuất bất cứ thứ gì. Provider này cũng từ chối ngay tại node, bất kể Recipe đến từ danh mục nào: một attachment trên node reference có nội dung được khai báo là nhạy cảm — Feature của nó khai báo một trường sensitive: true, hoặc khe mà nó điền vào khai báo như vậy — sẽ dừng bản build với TRANSLATION_ERROR (E0288), nêu tên node và mọi attachment như vậy, bất kể có khe nào khai báo tên mà nó được gắn dưới đó hay không. Một attachment không mang gì được khai báo là nhạy cảm sẽ không bị từ chối ở đây. Các Components đó khai báo các khe thông tin xác thực của chúng là tùy chọn, nên trên compose một khe để trống không làm dừng gì cả. Ở nơi việc hiện thực hóa trên Kubernetes cần thông tin xác thực — các Recipes helm của twilio, vonage, telnyx, bland, letta, retell và vapi — Recipe đó thay vào đó yêu cầu khe, và dừng bản build nêu tên khe khi nó trống.
Công khai service
Trường type của một mục services trong Workload quyết định compose có công khai cổng hay không, và trên địa chỉ máy chủ nào:
| Loại service của Workload | Hành vi của compose |
|---|---|
ClusterIP | Không công khai ports: — service chỉ truy cập được trên mạng compose |
NodePort | Công khai ports: [<host>:<container>], trên mọi giao diện của máy chủ |
LoadBalancer | Công khai ports: [<host>:<container>], trên mọi giao diện của máy chủ (compose không có tương đương managed-loadbalancer; việc công khai cổng máy chủ là phép tương tự gần nhất) |
Loopback | Công khai ports: [127.0.0.1:<host>:<container>] — truy cập được từ chính máy chủ và không từ nơi nào khác |
Headless | Không công khai ports: |
Số nào ở phía nào. Một mục service nêu một cổng container và gán cho nó một số, giống như cách một Kubernetes Service ánh xạ port của nó lên một targetPort. Số của mục là phía <host> của cặp được publish, và số của cổng container mà tên đó phân giải tới là phía <container>. Vì vậy, một container khai báo http: 8080 và một mục NodePort viết http: 8081 sẽ publish 8081:8080: cổng 8081 của host đến được cổng mà container phục vụ. Một mục mang chính số của cổng container sẽ publish số đó ở cả hai phía, 8080:8080. Một peer trên mạng compose truy cập service bằng tên service của nó trên cổng của container, không bao giờ trên cổng đã publish — cổng đã publish thuộc về host — nên một Recipe publish một cổng do nó tự chọn vẫn trao cho các bên tiêu thụ của nó cổng của container.
Một mục Loopback chỉ bind địa chỉ loopback IPv4. Địa chỉ loopback IPv6 ::1 không được bind: cú pháp cổng của compose mang một địa chỉ máy chủ cho mỗi mục, và một máy chủ có giao diện loopback không mang địa chỉ IPv6 sẽ không thể bind nó, nên service sẽ không khởi động được ở đó. Các client trên máy chủ truy cập cổng tại 127.0.0.1.
Khi nhiều service trên cùng một Workload công khai cùng một cổng container với cùng một số, cổng được công khai một lần, và phạm vi rộng nhất thắng: bất kỳ tham chiếu NodePort hoặc LoadBalancer nào cũng công khai cổng trên mọi giao diện máy chủ, kể cả khi một mục Loopback cũng nêu tên nó và bất kể mục nào được khai báo trước; một cổng chỉ được các mục Loopback nêu tên sẽ được công khai trên 127.0.0.1. Một cổng container được công khai với hai số sẽ được công khai hai lần, mỗi số một lần. Các cổng được công khai được liệt kê theo thứ tự cổng container, và theo cổng được công khai trong cùng một cổng container.
Giao thức truyền tải của cổng. Một mục được công khai mang giao thức truyền tải được khai báo trên cổng container mà nó nêu tên, dưới dạng hậu tố /protocol của compose: 53:53/udp, hoặc 127.0.0.1:53:53/udp cho một mục Loopback. Một cổng không khai báo giao thức truyền tải được công khai dưới dạng <host>:<container> không có hậu tố, để giá trị mặc định của chính compose có hiệu lực. Compose viết giao thức truyền tải của cổng được công khai là tcp hoặc udp; một cổng khai báo SCTP không có cách viết trong compose, nên nó dừng với TRANSLATION_ERROR thay vì công khai một cổng mang giao thức truyền tải khác. Một cổng container không được service nào công khai thì không xuất hiện ở bất kỳ phần nào của tệp compose, nên giao thức truyền tải khai báo trên cổng đó không có chỗ để được viết ra và không gây dừng.
Workloads nhiều container
Một Workload có nhiều container trở thành một service chính cộng với một service sidecar cho mỗi container không phải container chính. Container chính là container có tên main (nếu có) hoặc container đầu tiên theo thứ tự khai báo. Các sidecar dùng chung network namespace của service chính thông qua network_mode: "service:<main>" — primitive của compose gần nhất với mô hình mạng dùng chung của một pod Kubernetes.
Cách một dịch vụ sidecar hoặc init được đặt tên
Dịch vụ chính mang tên <component> nguyên dạng. Mọi dịch vụ khác mà Workload tạo ra — một cho mỗi sidecar, và một cho mỗi container init — được đặt tên từ hai danh tính kết hợp: <component>, và tên của container, tức là khóa của nó dưới containers: đối với một sidecar và name của nó đối với một container init, hoặc tên theo vị trí init-<index> mà một mục init không có tên nhận. Khối services: được lắp ráp chứa một dịch vụ cho mỗi tên, vì vậy tên được xây dựng sao cho hai container khác nhau ở bất kỳ danh tính nào luôn ra hai tên khác nhau.
Mỗi danh tính được viết ra đúng như hai phần của một tên volume — một chữ cái, một chữ số, một dấu chấm và một dấu gạch dưới giữ như khi viết, một dấu gạch nối được giữ ở nơi các quy tắc ở đó giữ nó, và mọi ký tự khác được viết lại — và hai phần được nối bằng --, chuỗi mà không danh tính đã viết lại nào chứa. Vì vậy thành phần api với một sidecar logger chạy nó dưới tên api--logger, container init import-seed của platform chạy dưới tên platform--import-seed, và một mục init đầu tiên không có tên của api chạy dưới tên api--init-0. Một tên container chứa ký tự mà tên dịch vụ không chấp nhận sẽ được viết lại thay vì được xuất ra như khi viết: một container init tên warm cache/x của api chạy dưới tên api--warm-zx000020cache-zsx.
Phép nối kép giữ các container của hai thành phần tách biệt. api với một container warm-cache và api-warm với một container cache chạy dưới tên api--warm-cache và api-warm--cache, là hai dịch vụ, trong khi phép nối bằng một dấu gạch nối sẽ viết cả hai thành api-warm-cache.
Sidecar và container init dùng chung một cách đặt tên này, vì vậy một mục containers và một mục initContainers mang cùng tên sẽ ra cùng một tên dịch vụ, và bản build dừng lại ở cặp đó thay vì chạy một container thế chỗ container kia (xem Init container).
Dịch vụ riêng của một thành phần không nhận một trong các tên này. Dịch vụ chính được đặt theo tên thành phần, và một dấu gạch nối kép được viết trong tên của thành phần cũng được viết lại ở đó — một thành phần tên api--prep chạy dưới tên api-zh-prep — nên nó không bao giờ mang phép nối --. Ở nơi các dịch vụ của hai thành phần khác nhau vẫn trùng một tên trong cùng một tệp compose — chẳng hạn qua một dịch vụ mà một artifact tự đặt tên — bản build dừng lại và nêu tên cả hai, như Đầu ra theo từng (path, provider) mô tả.
Đổi tên thành phần hoặc tên container sẽ đổi tên dịch vụ. Compose coi một dịch vụ dưới tên mới là một dịch vụ mới, nên container của nó được tạo mới hoàn toàn dưới tên mới.
Các trường cấp pod
Các trường cấp pod của Workload chỉ áp dụng cho service chính — các sidecar dùng chung network namespace của service chính — và một init service cũng tuân theo quy tắc này. Ngoại lệ duy nhất là người dùng của pod: một pod chạy mọi container của nó dưới podSecurityContext.runAsUser và runAsGroup, nên chúng đến được mọi service mà Workload tạo ra, kể cả các service sidecar và init.
Một số trường ánh xạ sang một trường của service compose:
| Trường Workload | Trường Compose |
|---|---|
podSecurityContext.runAsUser / runAsGroup | user ("1000", hoặc 1000:3000 khi có nhóm) trên mọi service của Workload. Một container đặt securityContext.runAsUser của riêng nó sẽ thay vào đó chạy dưới người dùng đó trên service của riêng nó, cùng runAsGroup của riêng nó nếu nó có đặt |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | một mục extra_hosts cho mỗi hostname, theo thứ tự tác giả viết |
hostNetwork: true | network_mode: host |
Chạy trên mạng của node. Một workload khai báo hostNetwork: true nhận network_mode: host trên service của chính nó, và service đó khi ấy không được gắn vào mạng của boundary: compose từ chối một service khai báo cả networks: lẫn network_mode:, nên hai thứ này là lựa chọn thay thế cho nhau chứ không cộng thêm. Hệ quả thực tế là điều mà host networking luôn mang theo — các peer không còn truy cập service bằng tên service compose qua mạng đó, vì nó không còn nằm trên mạng đó; chúng truy cập nó qua chính các địa chỉ của host, đúng như điều khai báo yêu cầu. Mọi service khác trên boundary không bị ảnh hưởng.
Hai dạng kết hợp với nó. Một sidecar vẫn trỏ tới service chính (network_mode: "service:<main>"), nên nó theo service chính lên mạng của host mà không cần tự khai báo gì — giống như cách các container của một pod Kubernetes dùng chung một namespace. Một init service thì không: nó tự tham gia mạng của boundary, vì dùng chung namespace của service chính sẽ khiến việc service chính chờ nó trở thành vòng lặp. Vì vậy, một workload có cả hostNetwork và initContainers chạy service của chính nó trên mạng của host trong khi các init service vẫn ở trên mạng của boundary, hẹp hơn dạng pod mà nó mô phỏng; một cảnh báo unsupported-field nêu rõ khác biệt đó thay vì để bạn phát hiện khi chạy.
Các trường còn lại không có tương đương trên một host. Không trường nào bị bỏ qua trong im lặng: mỗi trường được khai báo sẽ phát ra một cảnh báo unsupported-field nêu tên trường, nhờ đó tác giả biết thiết lập nào mà đích không thể đáp ứng thay vì phát hiện ra từ stack đang chạy.
| Trường Workload | Vì sao compose không thể đáp ứng |
|---|---|
scheduling | Việc bố trí — nodeSelector, affinity, tolerations, topologySpreadConstraints — giả định có một scheduler chọn giữa các node. Compose chạy trên một host |
replicas | Số replica của chính compose nằm dưới deploy: và là một tính năng của chế độ swarm |
runtimeClassName | Việc chọn một container runtime khác — chẳng hạn một runtime hỗ trợ GPU — không có cách biểu đạt trong compose |
priorityClassName | Thứ tự preemption giả định có một scheduler |
serviceAccount | Danh tính Workload là một khái niệm của cluster |
imagePullSecrets | Thông tin xác thực registry trên một host compose là trạng thái đăng nhập của chính host, không phải một trường của file |
dnsPolicy, dnsConfig.options | Compose cung cấp dns và dns_search và không có gì chi tiết hơn |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user mang một người dùng và một nhóm; nhóm sở hữu các volume của pod, và các nhóm bổ sung cho các tiến trình của nó, không được chuyển đổi |
podSecurityContext.runAsGroup, khi pod không đặt runAsUser, hoặc khi một container — chính, sidecar hay init — đặt runAsUser của riêng nó mà không có runAsGroup | user chỉ nêu một nhóm khi đi kèm một người dùng, và người dùng riêng của container thế chỗ người dùng của pod, nên nhóm của pod không đến được service nào được viết theo cách đó |
securityContext cấp container được chuyển đổi một phần: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot và allowPrivilegeEscalation không có cách biểu đạt trong compose và phát ra cùng cảnh báo unsupported-field, và một runAsGroup của container được viết mà không có runAsUser bên cạnh cũng vậy: khi đó service chạy dưới người dùng của pod nếu pod có đặt, không kèm nhóm đó.
Mọi cảnh báo trong phần này chỉ mang tính tham khảo và nằm ngoài luồng: bản build vẫn thành công, và file được xuất ra giống hệt từng byte so với khi không có cảnh báo. --no-unsupported-field-warnings tắt loại cảnh báo này.
Init container
Các mục initContainers của một Workload trở thành các service riêng, theo cách dùng chạy-đến-khi-hoàn-tất của compose. Mỗi mục thêm một service, được đặt tên từ <component> và name của mục theo cùng cách đặt tên mà các sidecar dùng — <component>--<container-name> cho một tên thông thường; một mục bỏ qua name sẽ nhận tên theo vị trí init-<index> mà tài liệu tham khảo Workload mô tả, và được đặt tên từ tên đó.
Thứ tự mà hợp đồng soạn thảo cam kết — các init container chạy đến khi hoàn tất theo thứ tự chúng được viết, và mọi container khác chỉ khởi động sau khi tất cả chúng đã kết thúc — được biểu diễn bằng dạng đầy đủ của depends_on:
- Mỗi init service sau service đầu tiên chờ service đứng trước nó với
condition: service_completed_successfully. - Service chính, và mọi sidecar service, chờ init service cuối cùng với cùng điều kiện đó. Chờ service cuối cùng là đủ vì các init service tạo thành một chuỗi.
- Mỗi init service mang
restart: "no". Một init service chạy một lần; một service khởi động lại sẽ không bao giờ đạt đến trạng thái hoàn tất mà các service phụ thuộc vào nó đang chờ, nên mộtrestartPolicyđược khai báo trên một init container không thay đổi điều này.
services: platform: image: platform:1.0 depends_on: platform--verify-seed: condition: service_completed_successfully platform--import-seed: image: platform:1.0 restart: "no" platform--verify-seed: image: platform:1.0 depends_on: platform--import-seed: condition: service_completed_successfully restart: "no"Một init container được chuyển đổi đúng như mọi container khác: image của nó (bao gồm việc ghi lại registry mà một annotation aggrega.ai/image-registry áp dụng), command, args, variables, attachments, volumeMounts và securityContext đều được đưa vào init service. Chính điều đó giúp cấu hình mà một init container mang theo — thường nhất là một tệp nó mount và ghi vào một volume mà container chính cũng mount — được giữ lại trên đích compose thay vì bị mất cùng container. Một dạng mà compose không biểu diễn được sẽ thất bại với init container giống như với container thông thường: một lifecycle hoặc envFrom được khai báo sẽ dừng với một TRANSLATION_ERROR nêu tên init container mà nó xuất phát.
Hai điểm khác biệt so với service chính xuất phát từ việc init service là một service không phải service chính:
- Các trường Workload cấp pod không được áp dụng, cùng quy tắc mà các sidecar tuân theo — ngoại trừ người dùng của pod, vốn đến được mọi service như Các trường cấp pod mô tả.
- Một init service tham gia trực tiếp vào mạng của boundary của nó thay vì chia sẻ network namespace của service chính như một sidecar. Nó buộc phải vậy: service chính chờ init service, và việc chia sẻ một namespace tự nó đã là một sự phụ thuộc vào service chính, điều này sẽ khép việc chờ thành một vòng lặp mà compose từ chối khởi động. Do đó, một init container kết nối tới các service khác trên mạng boundary bằng tên service, nhưng không chia sẻ
localhostcủa service chính.
Các init service và sidecar service dùng chung một không gian tên, vì một cách đặt tên đặt tên cho cả hai, nên một mục initContainers và một mục containers không được mang cùng tên. Khi điều đó xảy ra, trình biên dịch dừng với một TRANSLATION_ERROR nêu tên node, tên container và tên service mà cả hai muốn dùng, thay vì để một service lặng lẽ thay thế service kia.
Việc phát ra điều kiện hoàn tất không nâng phiên bản Compose tối thiểu. condition và các giá trị của nó thuộc về Compose Specification cơ bản — khác với các trường restart và required nằm cạnh chúng trong cùng khối dạng đầy đủ, vốn được đặc tả gắn với các bản phát hành Compose cụ thể. Mỗi phiên bản tối thiểu mà đầu ra của compose provider yêu cầu đi kèm với cấu trúc cần đến nó: ≥ 2.23.1 cho configs.content nội tuyến, ≥ 2.26.0 cho subPath của một mount (xem Volume), và 2.38 cho các model. Phiên bản đầu tiên áp dụng cho mọi đầu ra compose mang một config với content: nội tuyến, vốn là cách mà cả tệp phía sau một volume configmap lẫn config phía sau một cạnh liên mạng được bắc cầu được đưa vào — không chỉ một đường soạn thảo.
Service tham gia mạng nào
Mọi service đều tham gia một mạng Docker; các sidecar kế thừa mạng này thông qua tham chiếu network_mode tới service chính. Mạng mà một node thuộc về được đọc từ annotation aggrega.ai/namespace trên node đó, và quay về đường dẫn của tệp compose khi node không mang annotation như vậy — tức thư mục mà tệp được ghi vào bên dưới thư mục đầu ra của bản build, chẳng hạn bridge/compose đối với một boundary có directory: là bridge. Vì thế mọi node không có annotation trong một tệp compose đều tham gia một mạng được đặt tên theo đường dẫn của tệp, bất kể nó nằm trong boundary nào: các boundary không có annotation dùng chung một tệp compose sẽ dùng chung mạng đó, và aggrega.ai/namespace là thứ tách chúng ra. Các node mang annotation khác nhau thuộc về một mạng cho mỗi annotation riêng biệt. Cách suy ra tên mạng là tên mà danh tính đó tạo ra.
Cách suy ra tên mạng
Một mạng compose là kết nối L3 dùng chung, và khối networks: cấp cao nhất hợp nhất các mục của nó theo tên — vì thế hai danh tính đi đến cùng một tên sẽ trở thành một mạng mà cả hai nhóm service cùng nằm trên đó, tiếp cận nhau bằng tên service, mà không có gì trong tệp được sinh ra cho thấy rằng ý định là hai mạng. Do đó, tên được xây dựng từ danh tính cho biết đó là mạng nào: annotation aggrega.ai/namespace của node, hoặc đường dẫn của tệp compose khi node không mang annotation nào.
Tên mạng compose chấp nhận một tập ký tự hẹp hơn so với những gì mỗi danh tính có thể chứa: chữ cái, chữ số, dấu chấm, dấu gạch dưới và dấu gạch nối. Thay vì thay thế một ký tự mà compose không chấp nhận, phép suy ra viết nó ra một cách tường minh, nhờ đó hai danh tính khác nhau dù chỉ một chút sẽ dẫn đến hai mạng — và một tên có thể được đọc ngược lại thành danh tính mà nó được xây dựng từ đó.
- Chữ cái, chữ số, dấu chấm và dấu gạch dưới được giữ nguyên đúng như khi viết, với đúng kiểu chữ hoa/thường ban đầu. Vì vậy
prodvàProdlà hai mạng, không phải một. - Dấu gạch nối được giữ nguyên như khi khai báo ở bất cứ đâu mà ký tự sau nó được giữ nguyên trực tiếp và không phải là chữ thường
z. Dấu gạch nối theo sau bởi chữ thườngzmở đầu một chuỗi thoát, nên một dấu gạch nối được khai báo ở vị trí đó sẽ tự nó được viết ra —api-zonetrở thànhapi-zhzone, đây chính là điều cho phép đọc ngược bất kỳ tên nào mà không cần đoán. Dấu gạch nối không có gì phía sau cũng được viết ra vì cùng lý do, nêndb-cho radb-zh. - Mọi ký tự khác được viết thành
-ztheo sau là một chữ cái đặt tên cho nó:scho dấu phân cách đường dẫn,hcho dấu gạch nối mà quy tắc ở trên không giữ lại. Mọi ký tự còn lại — kể cả dấu cách và chữ cái không thuộc ASCII — được viết thànhxcùng mã điểm thập lục phân sáu chữ số của ký tự đó, và một byte không bắt đầu ký tự nào được viết thànhbcùng giá trị hai chữ số của chính nó, nhờ đó một danh tính không phải văn bản hợp lệ vẫn được viết ra một cách riêng biệt thay vì bị gộp lại. - Một danh tính hoàn toàn vắng mặt — một node không có annotation
aggrega.ai/namespacetrong một tệp compose không có đường dẫn — được viết thành-ze, điều mà không danh tính nào do tác giả viết có thể tạo ra. Do đó, một mạng không có danh tính sẽ không bao giờ dùng chung kết nối với một mạng có danh tính được viết theo một cách cụ thể nào đó.
Như vậy, namespace prod cho ra mạng prod, core-net cho ra core-net, và một tệp compose tại dist/app/compose cho ra dist-zsapp-zscompose. Cùng một đầu vào luôn tạo ra cùng một tên.
Namespace và đường dẫn của tệp compose được viết vào cùng một không gian. Chúng là hai cách đặt tên cho cùng một thứ — node nằm trên mạng nào — vì thế một node có namespace là app/compose và một node không có namespace trong tệp compose tại app/compose sẽ cố ý thuộc về cùng một mạng, giống hệt như hai boundary mang cùng annotation aggrega.ai/namespace. Khi bạn muốn tách hai node ra, hãy cho chúng các danh tính khác nhau.
Thay đổi danh tính của một node sẽ đổi tên mạng compose, và compose không đổi tên mạng tại chỗ. Mạng được tạo mới dưới tên mới và mọi service trên đó được tạo lại để gắn vào mạng này, trong khi mạng cũ vẫn còn lại cho đến khi có thứ gì đó xóa nó. Mạng không chứa dữ liệu, nên không có gì bị mất — nhưng các container trên đó sẽ khởi động lại, và bất cứ thứ gì đang giữ kết nối qua thời điểm thay đổi sẽ thấy kết nối bị ngắt. Hãy coi việc thay đổi annotation namespace, hoặc thư mục mà một tệp compose được ghi vào, là một lần triển khai lại cần được lên kế hoạch, thay vì một giá trị để điều chỉnh tại chỗ.
Khi hai boundary gộp vào một đường dẫn assembly (dùng chung directory:), các node không có annotation aggrega.ai/namespace của chúng dùng chung mạng duy nhất của tệp; hãy cho mỗi boundary annotation aggrega.ai/namespace riêng và tệp docker-compose.yaml được hợp nhất sẽ khai báo một mục networks: cấp cao nhất cho mỗi annotation. Các service từ các boundary khác nhau trong cùng một tệp compose có thể giao tiếp bằng tên service của chúng thông qua cơ chế phân giải DNS mặc định của compose, tùy theo các quy tắc khả năng tiếp cận liên mạng của chính compose. Định tuyến L4 liên mạng trong một tệp compose duy nhất là điều mà Feature compose-bridge của thư viện chuẩn cho phép, dưới dạng nội dung catalog mà provider này không chứa chút logic nào: khi được gắn tại boundary tổ tiên chung, FeatureRecipe của nó suy ra một gateway từ các cạnh uses của boundary có hai đầu được lắp ráp vào chính tệp compose của boundary và nằm trên các mạng khác nhau của tệp đó — một service aggrega-gw có cấu hình nginx stream làm proxy cho từng cạnh được bắc cầu (một khối server cho mỗi cạnh, trên cổng của đích với phương án dự phòng khi xung đột theo portBase) — và injectMapping của chính nó viết lại biến môi trường host của từng consumer thành aggrega-gw:<port>, hoặc thành aggrega-gw kèm biến cổng được viết lại thành cổng lắng nghe khi cùng một kết nối cung cấp cả hai. Việc viết lại đó thay thế giá trị mà chính kết nối của consumer đã cung cấp; nếu một Feature khác gắn vào consumer cũng cung cấp cùng biến đó, quá trình build sẽ dừng lại và nêu tên cả hai thay vì thay thế nó. valuesMapping của FeatureRecipe ghi cấu hình đó dưới dạng một compose config được mount — một mục configs: cấp cao nhất với content: nội tuyến, được tham chiếu từ gateway và mount tại /etc/nginx/nginx.conf; đây không phải là việc mà người vận hành phải tự mount — và nêu tên mọi endpoint được bắc cầu dưới x-aggrega-networks-of của gateway, mà provider này phân giải thành các mạng nơi các endpoint đó được đặt (bên dưới). Một cạnh có hai đầu được lắp ráp vào hai tệp compose sẽ không được bắc cầu và giữ tên riêng của đích; một boundary không có gì để bắc cầu vẫn mang gateway ở trạng thái nhàn rỗi, không có cấu hình và không có mạng nào ngoài mạng của chính nó; và một cầu được gắn tại một boundary có tệp compose không chứa component nào sẽ dừng bản build thay vì ghi gateway vào hư không. Cấu hình stream mang một chỉ thị resolver và làm proxy thông qua một biến riêng cho từng cạnh (set $uN <host>; proxy_pass $uN) để mỗi upstream được phân giải tại thời điểm kết nối thay vì một lần lúc khởi động — nếu không, một proxy_pass trần tới một đích chưa chạy sẽ khiến gateway thất bại khi khởi động. (Ký tự $ trong các biến đó được thoát thành $$ bên trong configs.content để cơ chế nội suy $ của chính Docker Compose để lại một $ nguyên văn cho nginx.) configs.content nội tuyến yêu cầu Docker Compose ≥ 2.23.1. Xem mẫu compose-bridge.
Tham gia mạng của các component khác — x-aggrega-networks-of
Một service mà fragment viết ra — một tệp compose nguồn sau khi overlay của nó được hợp nhất vào, hoặc một phần thân artifacts: — có thể tham gia mạng của các component khác được lắp ráp vào cùng tệp compose bằng cách nêu tên chúng dưới khóa mở rộng x-aggrega-networks-of: một danh sách các id component, tức các id mà Aggregate đặt cho các component của nó, mà một FeatureRecipe phạm vi boundary đọc như các khóa của .boundary.components và như source và target trong các danh sách cạnh .boundary của nó. Provider phân giải từng id thành mạng mà component đó được đặt vào trong tệp này, theo cùng cách đặt mà mọi node nhận được, và thêm các mạng đó vào service, mỗi mạng một lần và theo thứ tự tên, đứng trước mạng riêng của service, mà service vẫn tham gia. Bản thân khóa này bị loại khỏi tệp được lắp ráp. Provider đọc các id như những tham chiếu cần phân giải và không đọc gì về việc service làm gì, nên bất kỳ Recipe hay FeatureRecipe nào cũng có thể dùng khóa này; gateway của compose bridge tham gia mạng của các endpoint mà nó chuyển tiếp giữa chúng theo cách này.
# written by a FeatureRecipe attached at the boundary `bridge`, whose file holds adminer (namespace frontend) and db (namespace backend)services: probe-svc: image: busybox x-aggrega-networks-of: ["adminer", "db"]# dist/bridge/compose/docker-compose.yaml (abridged)services: probe-svc: image: busybox networks: - backend - frontend - bridge-zscomposeBa trường hợp dừng bản build với TRANSLATION_ERROR khi tệp được lắp ráp, mỗi trường hợp đều nêu tên service:
- Một id mà không component nào được lắp ráp vào tệp này mang — chẳng hạn một component được lắp ráp vào một tệp compose khác. Một mạng thuộc về một tệp, nên thông báo nêu tên id và tệp chứa service. Chỉ nêu tên các component được lắp ráp vào cùng tệp, hoặc xóa id.
- Một giá trị không phải là danh sách chuỗi. Khóa này nhận một danh sách các id component, ngay cả khi chỉ có một id.
- Khóa này trên một service có viết
network_mode. Compose không cho phép một service cónetwork_modetham gia các mạng; hãy xóa một trong hai.
Suy luận depends_on
Compose provider tự động suy ra depends_on từ các cạnh uses của IR. Với mỗi cạnh mà cả nguồn lẫn đích đều đóng góp service vào tệp compose đã hợp nhất, provider thêm depends_on: [<target>] vào service nguồn.
Phụ thuộc được đặt lên chính service của component nguồn, và không lên service nào khác mà component đó đóng góp. Một component cũng khai báo init container sẽ đóng góp một service chạy đến khi hoàn tất cho mỗi mục, và không service nào trong số đó nhận phụ thuộc suy ra từ cạnh — một cạnh gọi tên component, còn một init service mang tên riêng của nó. Vì vậy, một init container cần truy cập đích của cạnh, chẳng hạn một lần migration schema trên cơ sở dữ liệu mà component uses, không có thứ tự nào đối với đích đó và có thể chạy trước khi đích truy cập được, trong khi chính service của component chờ cả chuỗi init hoàn tất lẫn đích đã khởi động.
Các mục suy ra từ cạnh được phát ra không có cổng chặn: chúng mang ngữ nghĩa service_started bất kể đích có khai báo healthcheck hay không. Việc chặn chúng theo tình trạng sức khỏe của đích — điều sẽ cho phép runtime compose chặn khởi động cho đến khi healthcheck của đích báo healthy — là có thể biểu đạt được, và một cạnh uses không yêu cầu điều đó. Một wave gọi tên cùng cặp đó là thứ duy nhất thay đổi điều kiện trên một mục suy ra từ cạnh, và nó làm vậy vì wave yêu cầu, chứ không phải vì cạnh yêu cầu.
Các mục suy ra từ cạnh được phát ra theo thứ tự bảng chữ cái của đích để đầu ra ổn định. Các cạnh có nguồn hoặc đích được phục vụ bởi một provider khác (helm hoặc helm-chart) bị bỏ qua — depends_on chỉ áp dụng trong tập con được compose phục vụ của Release.
depends_on của một service được phát ra theo một trong hai dạng của compose, không bao giờ trộn lẫn, vì compose yêu cầu một điều kiện trên mọi mục của dạng dài:
- Danh sách dạng ngắn (
depends_on: [<service-name>]) khi không mục nào trên service đó mang điều kiện. Đó là mọi service mà các phụ thuộc duy nhất đến từ các cạnhuses. - Ánh xạ dạng dài khi bất kỳ mục nào mang điều kiện — điều này xảy ra khi service cũng chờ một init container, hoặc khi một deployment wave sắp thứ tự nó. Khi đó, các mục suy ra từ cạnh phát ra
condition: service_startedtường minh, mà Compose Specification định nghĩa là tương đương với dạng ngắn, nên ý nghĩa của chúng không thay đổi.
Trong một service, các nguồn giữ thứ tự riêng và không xen kẽ: phần chờ chuỗi init, có thứ tự là thứ tự tác giả viết danh sách, được phát ra trước, rồi đến các mục suy ra từ cạnh xếp theo bảng chữ cái, rồi đến các mục suy ra từ wave xếp theo bảng chữ cái.
Sắp thứ tự theo đợt triển khai
Giá trị syncWave: của một ranh giới Release sắp thứ tự các service của tệp compose mà ranh giới đó được kết xuất vào. Mọi component trong ranh giới đều kế thừa đợt (wave) của ranh giới, và khi nhiều ranh giới dùng chung một directory: — khiến phần đóng góp của chúng gộp lại thành một docker-compose.yaml duy nhất — tệp đã hợp nhất chứa nhiều hơn một đợt và provider biểu diễn thứ tự giữa chúng bằng depends_on.
Mỗi service chờ mọi service của đợt liền trước có service, và không chờ đợt nào sớm hơn đợt đó. Compose giải quyết phần còn lại theo tính bắc cầu: một service ở đợt 2 chờ đợt 1, đợt này lại chờ đợt 0, nên toàn bộ chuỗi được sắp thứ tự trong khi danh sách của mỗi service chỉ có kích thước của một đợt thay vì của cả tệp. Các đợt không cần liên tiếp, và giá trị âm là bình thường — -1 là lựa chọn phổ biến cho một migration chạy trước mọi thứ khác.
Điều kiện phụ thuộc vào những gì đích có thể đáp ứng. Một đợt có nghĩa là nhóm trước đã sẵn sàng trước khi nhóm sau khởi động, tức là sự sẵn sàng chứ không phải việc khởi chạy tiến trình, nên:
- khi service đích khai báo
healthcheck, việc chờ làcondition: service_healthy; - khi không khai báo, việc chờ là
condition: service_started, vì một service không có healthcheck không bao giờ có thể báo cáo healthy và một việc chờ dựa trên health đối với nó sẽ không bao giờ được thỏa mãn — tệp sẽ không bao giờ khởi động được.
Điều kiện yếu hơn hiển thị trong tệp được sinh ra bên cạnh điều kiện mạnh hơn, và bản build còn nêu tên từng service như vậy trong một cảnh báo, để tác giả nào mong đợi thứ tự theo sự sẵn sàng biết được phần nào của đợt họ khai báo chỉ được thực hiện như thứ tự khởi động. Cảnh báo chỉ mang tính tham khảo: bản build thành công và các byte được kết xuất giống hệt như khi không có cảnh báo. Thêm một khối health: vào container đó là cách nâng cấp việc chờ. --no-unsupported-field-warnings tắt loại cảnh báo này.
Đợt vẫn được ghi lại dưới dạng nhãn. Thứ tự được thêm bên cạnh nhãn aggrega.ai/sync-wave, không thay thế nó: nhãn là nơi người đọc kiểm tra tệp được sinh ra thấy một service đến từ đợt nào, điều mà các mục depends_on không nêu.
Khi một đợt và một cạnh uses cùng chỉ một cặp, một mục mang cả hai. Compose chấp nhận một mục cho mỗi phụ thuộc, nên một service vừa uses một đích vừa nằm ở đợt sau đích đó sẽ sinh ra một mục duy nhất theo điều kiện của đợt — yêu cầu của đợt là yêu cầu mạnh hơn trong hai và là yêu cầu được biểu diễn.
Một ranh giới có mọi component nằm trong cùng một đợt không sinh ra gì từ cơ chế này. Một Release không khai báo syncWave nào cũng vậy: mọi bên đóng góp mang giá trị mặc định 0 của trường, tệp đã hợp nhất chỉ chứa một đợt, và đầu ra giống hệt như khi provider không biểu diễn thứ tự đợt nào.
Thứ tự giữa hai tệp compose không thể biểu diễn, và cũng không được mô phỏng gần đúng. depends_on chỉ một service trong cùng tệp, và các ranh giới được đánh giá thành các đường dẫn lắp ráp khác nhau sẽ tạo ra các tệp docker-compose.yaml khác nhau mà runtime compose coi là các dự án độc lập. Vì vậy một đợt sắp thứ tự mọi service trong tệp mà nó được kết xuất vào và không gì bên ngoài tệp đó. Việc sắp thứ tự hai dự án compose là việc của người vận hành, giống như định tuyến giữa các tệp; khai báo một directory: dùng chung là cách đưa hai ranh giới vào một tệp, và đó là một quyết định về hình dạng đầu ra nên đưa ra vì lý do riêng của nó chứ không phải để có được thứ tự.
Một cạnh uses trỏ tới một đợt muộn hơn được phát ra đúng như đã viết, và được báo cáo. depends_on được phát ra phản ánh những gì đã khai báo — cả các cạnh uses lẫn các đợt. Một cạnh có bên tiêu thụ nằm ở đợt sớm hơn đích mà nó sử dụng thì khẳng định điều ngược lại với những gì các đợt khẳng định: cạnh khiến bên tiêu thụ chờ đích, trong khi các đợt khiến đích chờ bên tiêu thụ, qua mọi đợt nằm giữa chúng. Tệp được hợp nhất thể hiện cả hai, tạo thành một tập phụ thuộc vòng mà Docker Compose từ chối khởi động. Bản build nêu tên từng cạnh như vậy trong một cảnh báo nêu rõ cả hai service và cả hai đợt, để vòng lặp lộ ra khi bạn build thay vì tại docker compose up. Cảnh báo mang tính tư vấn — bản build thành công và các byte được render giống hệt như khi không có nó — và --no-unsupported-field-warnings không tắt nó, vì không có gì bị bỏ đi: hai khai báo đều được thể hiện, và cùng nhau chúng không thể khởi động. Nó chỉ bao phủ cặp trực tiếp: nó nêu tên hai service mà một cạnh kết nối thay vì truy vết toàn bộ vòng lặp. Mọi vòng lặp được tạo từ các cạnh uses và các đợt cùng nhau đều đi qua ít nhất một cạnh như vậy, nên luôn được báo cáo; một vòng lặp chỉ do các cạnh uses tạo thành, không liên quan tới đợt nào, và một vòng lặp được khép lại bởi một mục depends_on viết trong một tệp compose mà Recipe cung cấp, đều được phát ra đúng như đã viết và không được báo cáo. Hãy giữ hướng cạnh và thứ tự đợt nhất quán: đặt bên tiêu thụ vào đợt của đích hoặc một đợt muộn hơn, hoặc đặt đích vào đợt của bên tiêu thụ hoặc một đợt sớm hơn.
# release.yaml fragment — three boundaries collapsing onto one compose fileboundaries: data: directory: ./dist/cluster syncWave: -1 components: migrator: {} # no health: block core: directory: ./dist/cluster syncWave: 0 components: store: {} # declares health: edge: directory: ./dist/cluster syncWave: 1 components: frontend: {} # uses: store# dist/cluster/compose/docker-compose.yaml (abridged)services: frontend: labels: aggrega.ai/sync-wave: "1" depends_on: store: condition: service_healthy # store declares a healthcheck migrator: labels: aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing store: depends_on: migrator: condition: service_started # migrator declares no healthcheck healthcheck: test: [CMD-SHELL, "nc -z localhost 5432"]frontend không nêu tên migrator: thứ tự chỉ vươn tới đợt liền trước và compose nối chuỗi phần còn lại thông qua store.
Chế độ sourced
source: của compose provider chỉ định một tệp YAML docker-compose mà provider có thể đọc và phân tích, và nó chấp nhận cả hai dạng mà trường source: nhận: một chuỗi đường dẫn hệ thống tệp đơn thuần, và một đối tượng có cấu trúc mà url: của nó mang vị trí. Bất cứ khi nào vị trí đó là một đường dẫn hệ thống tệp, nó được neo vào thư mục chứa recipe.yaml khai báo nó, không phải vào thư mục nơi bản dựng được gọi, và nó phải nằm bên trong thư mục đó: một đường dẫn leo ra khỏi thư mục đó, hoặc một đường dẫn tuyệt đối, sẽ bị từ chối, vì mọi tệp mà một bản phát hành của Recipe mang theo đều được lấy từ thư mục của nó — xem entities/recipe.md “Content paths stay inside the Recipe’s own directory”. Tệp được chỉ định theo cách này được phát hành cùng với Recipe, còn một tệp nằm cạnh Recipe mà không có gì nó khai báo chỉ định thì không.
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"Ở dạng có cấu trúc, những gì url: mang quyết định liệu có gì được tải về hay không. Một fragment được phát hành qua https:// được tải về và ghim với kind: compose-https-fragment; aggrega pull lấy nó về và bản dựng đọc nó từ bộ nhớ đệm. Một url: chỉ định một đường dẫn hệ thống tệp thì không được tải về — nó được đọc từ đĩa, được neo đúng như dạng chuỗi đơn thuần ở trên, và aggrega pin ghi lại digest của tệp mà nó chỉ định trong entity.lock nằm cạnh Recipe, thứ mà bản dựng sau đó so sánh trước khi fragment được đọc. Việc vendor một fragment từ xa về cục bộ và trỏ source: vào bản sao đã vendor được hỗ trợ như một phương án thay cho việc tải về, và không bắt buộc. Schema chấp nhận một đối tượng có cấu trúc mở.
Một Recipe với source: <path-to-compose-file> và valuesMapping: chạy pipeline sau:
- Tệp compose cơ sở tại
<path>được đọc và phân tích dưới dạng YAML. - Template
valuesMappingđược đánh giá dựa trên ngữ cảnh template của Recipe. Đầu ra của nó được coi là một tài liệu overlay compose — một tệp compose một phần bổ sung hoặc ghi đè các trường trong tệp cơ sở. - Tệp cơ sở và overlay được hợp nhất sâu theo ngữ nghĩa overlay gốc của docker-compose.
Các quy tắc hợp nhất sâu:
- Giá trị vô hướng: overlay thắng. Khi cả tệp cơ sở và overlay cùng đặt một trường vô hướng, giá trị của overlay thay thế giá trị của tệp cơ sở.
- Map: hợp nhất đệ quy. Khi cả tệp cơ sở và overlay cùng đặt một trường map, việc hợp nhất đi đệ quy vào map đó. Các khóa có mặt ở cả hai tuân theo cùng các quy tắc; các khóa chỉ có ở một bên được giữ nguyên.
- Danh sách: thay thế. Khi cả tệp cơ sở và overlay cùng đặt một trường danh sách, danh sách của overlay thay thế hoàn toàn danh sách của tệp cơ sở (không hợp nhất hay nối thêm theo từng phần tử). Điều này khớp với hành vi của
docker compose -f base.yaml -f overlay.yaml config. null: thay thế, và được giữ lại. Một khóa mà overlay đặt thànhnulltrên một service — một trong các khóa riêng của service, chẳng hạnuser,commandhoặchealthcheck, một mụcenvironment, một nhãn, hoặc một khóa nằm ngay dướihealthcheckhoặcdeploy— thay thế giá trị của tệp cơ sở như mọi giá trị vô hướng và được ghi vào tệp compose dưới dạngkey: null; nó không xóa khóa. Khi provider ghi một giá trị của riêng nó vào khóa đó, tệp sẽ mang giá trị của provider thay vào đó:labels: nullđể lại các nhãn nguồn gốc mà provider gắn, vànetworks: nullđể lại mạng mà nó gắn vào. Mộtnullđược viết ở bất kỳ chỗ nào khác trong overlay nằm ngoài quy tắc này. Ý nghĩa của mộtnullkhi đó là cách Compose hiểu thuộc tính ấy — ví dụ, một mụcenvironmentkhông có giá trị sẽ lấy giá trị từ môi trường nơidocker composechạy.
Mọi nhãn mà tác giả của một service đã viết đều được giữ lại. labels: của một service trong tệp cơ sở hoặc overlay có thể được viết dưới dạng map hoặc dưới dạng danh sách các mục key=value của Compose, và mỗi nhãn đến tệp compose bên cạnh các nhãn nguồn gốc mà provider đóng dấu. Một mục danh sách được đọc như cách Compose đọc nó: phần văn bản trước dấu = đầu tiên là tên nhãn và phần văn bản sau đó là giá trị, còn một mục không có = là một nhãn có giá trị rỗng. Một số hoặc một giá trị true/false được viết dưới dạng văn bản của nó, nên replicas-hint: 2 đến tệp dưới dạng replicas-hint: "2", và một nhãn được viết là null vẫn giữ null. Khi một nhãn do tác giả viết và một nhãn nguồn gốc dùng chung một khóa, tệp mang giá trị nguồn gốc. Một giá trị labels: không phải map cũng không phải danh sách, và một mục danh sách không phải văn bản, sẽ dừng bản build, nêu tên tệp nguồn và service. Nhãn service trong phần thân artifacts: dùng dạng map: một danh sách ở đó sẽ dừng bản build, nêu tên artifact và service.
Tài liệu đã hợp nhất sau đó đi vào bước hợp nhất cấp Release cùng với mọi đóng góp ở chế độ synthesized, với cùng cơ chế mạng theo từng ranh giới và suy luận depends_on.
Loại bỏ services, volumes và configs. Overlay không thể xóa bất cứ thứ gì khỏi tệp cơ sở — một giá trị overlay thay thế, nó không bao giờ xóa — vì vậy với một tệp được tải về có kèm một service mà Release không được chạy, các mục omits: của một Recipe hoặc một FeatureRecipe chính là để dùng cho việc đó. Provider này tuân theo chúng ở chế độ này và không ở chế độ nào khác: một Workload synthesized và một phần thân artifacts: được render mà không có chúng. Một mục chỉ định một đơn vị cấp cao nhất của tệp bằng kind của nó — service, volume hoặc config — và name của nó, tức khóa của đơn vị dưới services:, volumes: hoặc configs:, được so sánh chính xác. Một tệp compose không có namespace, nên một mục mang namespace, giống như một mục chỉ định bất kỳ kind nào khác, sẽ dừng bản dựng khi component được render, nêu tên mục đó và các kind mà provider này chấp nhận; mọi mục đều được kiểm tra trước khi bất cứ thứ gì bị loại bỏ. Các mục được đối chiếu với tệp sau khi overlay ở trên đã được hợp nhất vào, nên một đơn vị do overlay thêm vào bị loại bỏ đúng như một đơn vị do tệp cơ sở khai báo, và trước khi provider thêm bất cứ thứ gì của riêng nó, nên một mục không bao giờ chỉ định thứ đó. Một đơn vị mà một mục chỉ định sẽ bị xóa, và một phần mà mọi đơn vị của nó đều bị loại bỏ cũng bị xóa theo; mọi đơn vị khác được ghi đúng như khi không có các mục. Các mục chỉ tác động đến tệp của Recipe hoặc FeatureRecipe khai báo chúng và không gì khác: những gì một component khác hoặc một Feature được gắn đóng góp vào cùng docker-compose.yaml không bị đụng đến, kể cả một đơn vị có cùng khóa. Provider báo cáo mỗi mục đã loại bỏ bao nhiêu đơn vị, và một mục không loại bỏ đơn vị nào sẽ dừng bản dựng; xem An omits entry left out nothing the source rendered (Một mục omits không loại bỏ gì trong những gì nguồn đã render).
Một đơn vị đã bị loại bỏ không được tiếp tục được chỉ định bởi phần còn lại, vì compose từ chối một tệp chỉ định một service, một volume hoặc một config mà nó không khai báo. Khi các đơn vị đã bị xóa, mọi tham chiếu mà tệp vẫn còn trỏ đến một trong số chúng sẽ dừng bản dựng, và thông báo nêu tên từng service hoặc job tham chiếu, đơn vị mà nó chỉ định và trường chứa tham chiếu. Một tham chiếu là thứ mà Compose Specification định nghĩa là một mục của tệp chỉ định một mục khác:
- một service, được chỉ định bởi
depends_onở cả hai dạng, bởilinks(SERVICEhoặcSERVICE:ALIAS), bởivolumes_from(SERVICEhoặcSERVICE:MODE), bởinetwork_mode,ipc,pidhoặcutsđược đặt thànhservice:<name>, bởiextendschỉ định một service của cùng tệp, hoặc bởi một giá trịbuild.additional_contextslàservice:<name>; - một volume, được chỉ định làm nguồn của một mục
volumes:— dạng ngắnSOURCE:TARGETkhi nguồn là một tên chứ không phải đường dẫn, và dạng dài củatype: volume; - một config, được chỉ định bởi một mục
configs:, ở cả hai dạng.
Các hook pre_start của một service và mỗi mục jobs: cấp cao nhất cũng được đọc, để tìm các tham chiếu mà specification cho phép mỗi thứ mang. Một số giá trị chỉ trông giống tham chiếu và không được đọc như tham chiếu: một mục volumes_from hoặc network_mode bắt đầu bằng container: chỉ định một container, external_links chỉ định một container mà tệp này không khai báo, một extends có file: chỉ định một service của tệp khác, và một credential_spec.config có thể chỉ định một config do nền tảng nắm giữ chứ không phải do tệp. Mọi giá trị được so sánh đúng như được viết, nên một tham chiếu được viết thông qua ${VARIABLE} không phải là tham chiếu mà bước kiểm tra này thấy, và một tham chiếu đến một đơn vị mà tệp chưa bao giờ khai báo được để nguyên.
Bước kiểm tra chỉ đọc riêng tệp của Recipe hoặc FeatureRecipe khai báo, nên một tham chiếu đến một service đã bị loại bỏ sẽ dừng bản dựng ngay cả khi một contributor khác tại cùng đường dẫn assembly khai báo một service cùng tên. Để giữ tham chiếu, hãy giữ đơn vị. Để bỏ nó, hãy thay đổi mục tham chiếu qua valuesMapping: — một danh sách ở đó thay thế danh sách của tệp cơ sở, nên depends_on: [] sẽ xóa sạch một danh sách — hoặc loại bỏ luôn cả service tham chiếu.
Đầu ra theo từng (path, provider)
Mỗi đường dẫn lắp ráp compose tạo ra một docker-compose.yaml. Các boundary được đánh giá thành các đường dẫn khác nhau sẽ tạo ra các tệp compose khác nhau; các boundary có chung đường dẫn đã đánh giá sẽ tạo ra một tệp compose hợp nhất chứa mọi thành phần đóng góp tại đường dẫn đó. Đường dẫn là directory: của boundary nối với subDirectory: theo từng component (mặc định là {{ .capability }}, nên theo mặc định các thành phần đóng góp compose nằm trong thư mục con compose/).
Xung đột tên service trong cùng một đường dẫn lắp ráp sẽ dừng bản build. Khi hai node khác nhau đóng góp các service có cùng instance ID tại cùng một bộ (path, provider), trình biên dịch dừng lại và chẩn đoán nêu tên mọi bộ (boundary, node) đóng góp theo thứ tự bảng chữ cái. Tác giả giải quyết xung đột bằng cách đổi tên một trong các thành phần đóng góp (thường bằng cách điều chỉnh định danh của node để bộ tổng hợp tạo ra tên service khác), hoặc bằng cách định tuyến các thành phần đóng góp đến các đường dẫn khác nhau qua các khai báo directory: khác nhau.
Các volume cấp cao nhất được hợp nhất trong một đường dẫn lắp ráp, và hai thành phần đóng góp có thể khai báo cùng một tên miễn là chúng thống nhất về nó. Một thành phần đóng góp là một fragment, nên hai fragment của một component — tệp compose riêng của nó và một mục artifacts:, hoặc hai mục artifacts: — là hai thành phần đóng góp, đúng như hai component. Một volume có tên là một volume vật lý, nên hai khai báo giống hệt nhau đều mô tả đúng mục mà tệp lắp ráp cuối cùng có, và nó giữ một mục duy nhất dưới tên đó. Một volume do provider suy ra không mang phần thân, nên hai volume như vậy luôn thống nhất một cách hiển nhiên, và dù sao chúng cũng không thể gặp nhau (xem Cách suy ra tên volume).
Một mục volumes: do tác giả viết là thứ cần chú ý, vì nó có thể mang phần thân riêng — một driver, driver_opts hoặc labels. Khi hai thành phần đóng góp khai báo cùng một tên với phần thân khác nhau, bản build dừng với TRANSLATION_ERROR, nêu tên volume và mọi bộ (boundary, node, fragment) đóng góp. Hai tác giả bất đồng về một volume duy nhất không có câu trả lời nào để bộ lắp ráp chọn: giữ một phần thân bất kỳ sẽ loại bỏ những gì tác giả kia đã viết, khỏi một bản build lẽ ra thành công. Hãy giải quyết bằng cách làm cho hai khai báo giống hệt nhau, khi cả hai tác giả muốn nói cùng một volume, hoặc đổi tên một trong hai, khi họ muốn nói hai volume. Các network cấp cao nhất gồm một network cho mỗi chú thích aggrega.ai/namespace riêng biệt, cộng thêm một network được đặt tên theo đường dẫn của tệp compose dành cho các node không mang chú thích nào, được đặt tên theo Cách suy ra tên network; hai boundary đóng góp có cùng chú thích aggrega.ai/namespace được hợp nhất thành một network duy nhất dùng chung cho cả hai, cũng như hai boundary không có chú thích dùng chung tệp.
Mọi khóa mà một fragment viết ra đều được mang theo hoặc bị từ chối
Một fragment — một tệp compose nguồn sau khi overlay của nó được hợp nhất vào, hoặc một phần thân artifacts: được đánh giá thành YAML compose — chỉ đến được docker-compose.yaml đã lắp ráp thông qua các khóa mà provider mang theo, và tập khóa đó là cố định. Mỗi khóa mà fragment viết ra hoặc được mang vào tệp đã lắp ráp đúng như đã viết, hoặc bị từ chối kèm tên; không khóa nào bị bỏ đi mà không có lời nào. Một fragment là một tệp compose, nên nó là một tài liệu YAML.
- Được mang theo. Ở cấp cao nhất:
services,volumes,configsvàmodels. Trên một service:image,pull_policy,command,entrypoint,environment,env_file,ports,labels,volumes,tmpfs,networks,network_mode,depends_on,healthcheck,restart,user,working_dir,privileged,read_only,cap_add,cap_drop,configs,models,deploy,stop_grace_period,dns,dns_search,extra_hostsvàprofiles. Bên trong các khối mà provider mô tả:deploy.resourcescùnglimits(cpus,memory) vàreservations(cpus,memory,devices, vàdriver,count,device_ids,capabilitiesvàoptionscủa mỗi mục thiết bị) của nó;test,interval,timeout,retriesvàstart_periodcủa mộthealthcheck;type,source,target,read_onlyvàvolume.subpathcủa một mụcvolumes:dạng đầy đủ;sourcevàtargetcủa một mụcconfigs:dạng đầy đủ;conditioncủa một mụcdepends_on:dạng đầy đủ;driver,driver_optsvàlabelscủa một volume cấp cao nhất;contentcủa một config cấp cao nhất. Phần thân của một model và mụcmodels:dạng đầy đủ của một service mang theo mọi thành viên, như Models mô tả. Một thành viên mở rộng — một khóa bắt đầu bằngx-— được mang theo ở cấp cao nhất và trên một service, như Các thành viên mở rộng mô tả. - Bị từ chối. Bất kỳ khóa nào khác —
stdin_opentrên một service,secrets:hoặcname:cấp cao nhất,deploy.replicas,restart:hoặcrequired:bên trong một mụcdepends_on:dạng đầy đủ, một khóax-bên trong phần thân của một volume cấp cao nhất hoặc mộthealthcheck— đều dừng bản build vớiTRANSLATION_ERROR, nêu tên mọi khóa như vậy, đường dẫn của nó trong fragment (services.migrate.stdin_open), fragment và component, và nêu hai nơi mà một khóa như vậy xuất phát. Một là chính fragment, và cách sửa là xóa khóa khỏi nó. Hai là một Recipe có nguồn mà không khai báovaluesMapping:: khi đó các giá trị của node được phủ lên tệp compose nguyên trạng, nên mỗi khóa giá trị đến như một khóa cấp cao nhất của fragment, và cách sửa là khai báo mộtvaluesMapping:đặt mỗi giá trị dưới một khóa mà provider mang theo. Một khóa mà khóa hợp nhất YAML (<<: *anchor) đưa vào một khối được đánh giá tại nơi nó đến, như thể được viết ở đó. Một fragment được render từ nguồn có tên<component>.compose-fragment.yaml; một fragmentartifacts:mang tên mà Recipe của nó đặt cho nó. - Bị từ chối toàn bộ: một mạng riêng của fragment. Một mục dưới
networks:cấp cao nhất của fragment sẽ dừng bản build vớiTRANSLATION_ERRORbất kể phần thân của nó chứa gì — một mục rỗng, mộtdriver, hay bất cứ thứ gì khác — nêu tên mục đó (networks.back), fragment và component, vì tệp đã lắp ráp chỉ chứa các mạng mà provider suy ra (xem Service tham gia mạng nào). Hãy xóa mục đó: một service tham gia mạng của component của chính nó mà không cần khai báo gì, annotationaggrega.ai/namespacechọn mạng mà một component tham gia, một service nêu tên các component có mạng mà nó cũng tham gia dướix-aggrega-networks-of, và Featurecompose-bridgeđịnh tuyến giữa các service trên các mạng khác nhau. Mộtnetworks: {}rỗng không khai báo gì và không bị từ chối, còn danh sáchnetworks:riêng của một service được mang theo như trên. - Bị từ chối toàn bộ: một fragment gồm nhiều hơn một tài liệu. Một phần thân
artifacts:chứa hai hoặc nhiều tài liệu YAML được phân tách bằng---sẽ dừng bản build vớiTRANSLATION_ERROR, nêu tên fragment, component và số tài liệu nó chứa, vì việc hợp nhất đọc một fragment như một tệp compose và nếu không thì mọi tài liệu sau tài liệu đầu tiên sẽ bị thiếu trong tệp đã lắp ráp. Hãy viết fragment thành một tài liệu, hoặc cho mỗi tài liệu một mụcartifacts:riêng. Một tài liệu không chứa gì — tài liệu rỗng mà một---ở cuối mở ra — không được tính. Một tệp compose nguồn gồm nhiều tài liệu không bao giờ trở thành một fragment như vậy: nó bị từ chối khi tệp được đọc.
Provider không đọc ý nghĩa của khóa nào: một khóa được mang theo vì nó nằm trong tập ở trên và bị từ chối vì nó không nằm trong đó.
Các thành viên mở rộng được mang theo đúng như khi viết
Compose Specification dành riêng các khóa bắt đầu bằng x- cho phần mở rộng: dữ liệu mà một công cụ đọc tệp có thể dùng và bản thân Compose bỏ qua. Các thành viên mở rộng của một fragment ở cấp cao nhất và trên một service đến được tệp đã lắp ráp đúng như khi viết, sau mọi khóa mà provider mô hình hóa ở cấp đó, theo thứ tự fragment chứa chúng; provider không đọc bất cứ thứ gì bên trong chúng, ngoại trừ x-aggrega-networks-of của một service, thứ mà nó phân giải thành các mạng service tham gia và loại khỏi tệp đã lắp ráp (xem Tham gia mạng của các component khác). Một phần thân artifacts: chứa chúng theo thứ tự nó viết. Các khóa của một tệp compose có nguồn đến fragment của nó theo thứ tự tên sau khi lớp phủ được hợp nhất, nên các thành viên mở rộng của nó được viết theo thứ tự tên.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualMột thành viên đến được qua một alias YAML được viết ra đầy đủ, và không anchor nào được mang theo, nên tệp đã lắp ráp không bao giờ chứa một alias thiếu anchor của nó; đây là điều cho phép một thành viên cấp cao nhất chứa một anchor mà khóa merge của một service (<<: *base) đưa vào. Các thành viên của một service đi cùng service đó. Các thành viên cấp cao nhất được hợp trong một đường dẫn lắp ráp theo quy tắc mà volume tuân theo: hai fragment viết cùng một thành viên với nội dung giống nhau để lại một mục duy nhất, dù chúng viết theo kiểu block hay flow, còn hai fragment viết nó với nội dung khác nhau sẽ dừng build với TRANSLATION_ERROR, nêu tên thành viên và mọi bộ (boundary, node, fragment) đóng góp — kể cả hai fragment của cùng một component. Hãy làm cho hai khai báo giống hệt nhau, hoặc đặt tên khác cho một trong hai.
profiles đặt một service sau một Compose profile. Một service liệt kê profiles: sẽ không được docker compose up khởi động trừ khi một trong các profile của nó được bật, và được docker compose run --rm <service> khởi động theo yêu cầu — đây là dạng compose của một tác vụ chạy theo nhu cầu. Danh sách được mang theo đúng như fragment viết, theo thứ tự của nó:
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]Models
Phần models: cấp cao nhất của một tệp compose khai báo các mô hình AI mà các service của tệp sử dụng, và một service được cấp một mô hình thông qua mục models: của chính nó. Provider mang cả hai từ một fragment vào docker-compose.yaml đã lắp ráp, theo cách viết riêng của Compose, dù fragment là một tệp compose nguồn hay một phần thân artifacts: được đánh giá thành YAML compose. Một Workload không khai báo mô hình nào, nên một Recipe ở chế độ Workload không đóng góp mô hình nào.
- Phần thân của một mô hình được ghi đúng như fragment đã viết.
model— định danh OCI artifact của mô hình —context_sizevàruntime_flagsgiữ nguyên tên, và mọi thành viên khác, kể cả một phần mở rộngx-, được mang theo bên cạnh chúng. Trong một mô hình, ba thành viên có tên đứng trước và phần còn lại theo sau theo thứ tự khóa, và các mô hình được ghi theo thứ tự tên, nên cùng một đầu vào tạo ra một tệp giống hệt từng byte. Provider không đọc gì trong phần thân: nó không kiểm tra định danh, và không biết gì về thứ sẽ phục vụ mô hình. - Tham chiếu của một service giữ nguyên dạng của nó. Dạng ngắn liệt kê tên mô hình (
models: [llm]); dạng dài ánh xạ mỗi mô hình tớiendpoint_varvàmodel_var, tên của các biến nhận địa chỉ của model runner và định danh của mô hình. Dạng nào cũng được ghi theo dạng và thứ tự mà fragment đã dùng, và đi cùng service của nó. Khi dạng dài để một biến không có tên, Compose sẽ đặt tên cho nó khi chạy tệp. - Các mô hình được hợp nhất trong một đường dẫn lắp ráp, theo quy tắc mà volume tuân theo. Hai thành phần đóng góp khai báo cùng một tên mô hình với phần thân xuất ra giống hệt nhau để lại một mục duy nhất dưới tên đó; hai thành phần khai báo nó với phần thân khác nhau sẽ dừng bản build với
TRANSLATION_ERROR, nêu tên mô hình và mọi bộ(boundary, node, fragment)đóng góp. Hai fragment của cùng một component ở đây cũng là hai thành phần đóng góp. Hãy làm cho các khai báo giống hệt nhau khi cả hai thành phần đóng góp muốn nói một mô hình, hoặc đặt tên khác cho một trong hai. - Mọi tham chiếu đều nêu tên một mô hình đã khai báo. Sau khi các fragment của đường dẫn lắp ráp được hợp nhất, một service được cấp một mô hình mà không thành phần đóng góp nào tại đường dẫn đó khai báo sẽ dừng bản build với
TRANSLATION_ERROR, nêu tên service và mô hình. Việc kiểm tra chạy trên tập hợp đã hoàn tất, nên một component có thể cấp cho service của mình một mô hình mà một component khác tại cùng đường dẫn lắp ráp khai báo. - Một mục
omits:không thể loại bỏ một mô hình.service,volumevàconfiglà các kind mà provider này chấp nhận, và một mục nêu tên một mô hình sẽ dừng bản build giống như một mục nêu tên bất kỳ kind nào khác.
Các mô hình được phục vụ khi tệp chạy, không phải khi nó được build. Docker Compose 2.38 trở lên, trên một nền tảng hỗ trợ Compose models như Docker Model Runner, sẽ kéo về và chạy từng mô hình mà một service được cấp, bỏ qua mọi mô hình khác trừ khi khởi động với --all-resources, và đặt, trong mỗi service được cấp mô hình, các biến mà tham chiếu của nó nêu tên thành địa chỉ của model runner và định danh của mô hình. Bản build không thể thấy máy chủ sẽ chạy tệp, nên nó không kiểm tra phiên bản Compose lẫn nền tảng: một tệp mang mô hình được lắp ráp theo cùng một cách bất kể thứ gì chạy nó.
Một Feature được gắn vào một component đóng góp vào cùng một tệp
Một Feature được gắn vào một component đóng góp các service của nó vào docker-compose.yaml mà component chủ được lắp ráp vào, theo cùng điều kiện như Recipe riêng của component chủ. Không có tệp thứ hai bên cạnh: một đường dẫn lắp ráp tạo ra một tài liệu, nên các service của một Feature được gắn hoặc nằm trong tài liệu đó, hoặc hoàn toàn không được triển khai. Tháo Feature ra sẽ loại bỏ chính xác các service đó và giữ nguyên các service riêng của component chủ.
Chúng là các thành phần đóng góp tại đường dẫn lắp ráp đó như mọi thành phần khác, nên mọi điều ở trên áp dụng cho chúng không thay đổi — quy tắc tên service, và yêu cầu rằng hai thành phần đóng góp khai báo cùng một tên volume hoặc config cấp cao nhất phải thống nhất về nó. Chúng cũng tham gia cùng network với phần còn lại của boundary, nên một component và một Feature được gắn vào nó có thể tiếp cận nhau bằng tên service mà không cần khai báo gì thêm.
Mỗi service mà một Feature đóng góp mang định danh được tạo cho lần gắn đó thay vì định danh của component chủ, nên hai bên vẫn phân biệt được trong một tài liệu mà cả hai cùng đóng góp. Nhãn và chú thích trình bày cách định danh đó được xây dựng.
Đây là một cơ chế khác với khối attachments: cấp container của một Workload, và hai cơ chế này dễ bị đọc nhầm là một vì chúng dùng chung một từ. Gắn một Feature vào một component sẽ thêm service vào tài liệu đã lắp ráp; một mục attachments: của container đọc một thông tin xác thực mà một slot đã công bố vào chính container đó, và được trình bày trong Các trường của container.
Các fragment compose do artifacts sinh ra
Khi khối artifacts: của một Recipe được đánh giá thành YAML compose — một fragment mang các khối services:, volumes:, configs:, models: hoặc networks: riêng của nó (mỗi mục viết inline hoặc được nạp theo từng mục bằng $import:) — việc hợp nhất vào bản lắp ráp theo từng (path, provider) tuân theo các quy tắc riêng cho từng dạng:
services:từ artifacts được hợp nhất vào tệp compose đã lắp ráp cùng với các service theo từng component. Một tên service do hai component khác nhau đóng góp tại cùng một đường dẫn lắp ráp sẽ làm dừng build, và chẩn đoán nêu tên mọi bên đóng góp. Một xung đột bên trong một component duy nhất — giữa fragment artifact của chính component đó và các service được tổng hợp cho nó — không bị phát hiện, và phần đóng góp sau thay thế phần trước, vì vậy hãy giữ tên service do artifact viết khác với các tên<component>và<component>--<container-name>mà bộ tổng hợp tạo ra (xem Cách một sidecar hoặc init service được đặt tên).volumes:từ artifacts được hợp nhất vào khốivolumes:cấp cao nhất. Hai mục cùng đi đến một tên sẽ để lại một mục duy nhất dưới tên đó khi chúng khai báo giống hệt nhau, theo cùng quy tắc với các volume theo từng component; hai mục khai báo khác nhau sẽ làm dừng build, dù chúng đến từ hai component hay từ hai fragment của cùng một component — hai mụcartifacts:của nó, hoặc một trong số đó và tệp compose của chính component. Vì một fragment artifact tự viết phần thân của mình, đây là con đường mà hai bên đóng góp dễ bất đồng nhất. Hãy giữ tên volume do artifact viết khác với các tên khác tại đường dẫn lắp ráp của nó, kể cả với dạng<component>--<volume-name>mà phép suy ra tạo ra — trừ khi hai bên đóng góp có ý mô tả một volume dùng chung, khi đó các khai báo của chúng phải khớp nhau.configs:từ artifacts được hợp nhất vào khốiconfigs:cấp cao nhất. Đây là cách tệp đứng sau một volumeconfigmapđến được bản lắp ráp: volume trở thành một tham chiếuconfigs:cấp service nêu tên configmap, và fragment artifact khai báo một mục cùng tên vớicontent:inline. Khi các fragment của đường dẫn lắp ráp đã được hợp lại, mọi tham chiếu cấp service phải phân giải được đến một mục đã khai báo, nếu không build sẽ dừng vớiTRANSLATION_ERROR, nêu tên từng tham chiếu chưa phân giải — service, tên config và đường dẫn mount. Việc kiểm tra chạy trên phép hợp đã hoàn tất thay vì theo từng component, nên một component có thể tham chiếu một config mà component khác tại cùng đường dẫn lắp ráp khai báo. Phép hợp hòa giải theo tên khi các bên đóng góp thống nhất: hai bên khai báo cùng một tên config vớicontent:giống hệt nhau để lại một mục duy nhất mà cả hai đều mô tả. Hai bên khai báo cùng một tên vớicontent:khác nhau sẽ làm dừng build vớiTRANSLATION_ERROR, nêu tên config và mọi bộ(boundary, node, fragment)đóng góp, kể cả hai fragment của cùng một component — một mục config luôn mang nội dung, nên giữ lại bất kỳ khai báo nào cũng sẽ loại bỏ một tệp mà một tác giả đã viết. Hãy giữ tên config khác biệt giữa mọi bên đóng góp tại đường dẫn lắp ráp của nó, hoặc làm cho các khai báo giống hệt nhau khi hai bên đóng góp có ý cung cấp một tệp dùng chung.models:từ artifacts được hợp nhất vào khốimodels:cấp cao nhất, và tham chiếumodels:của một service đi cùng service đó, theo các quy tắc trong Models: hai bên đóng góp khai báo cùng một tên model phải khai báo giống hệt nhau, và mọi tham chiếu phải nêu tên một model mà một bên đóng góp nào đó tại đường dẫn lắp ráp khai báo.networks:từ artifacts bị từ chối. Compose provider suy ra các mạng từ annotation của boundary (một mạng cho mỗi annotationaggrega.ai/namespaceriêng biệt, cộng thêm một mạng được đặt theo đường dẫn của tệp compose mà mọi node không có annotation đó tham gia, mỗi mạng được đặt tên theo Cách suy ra tên mạng), nên một khai báo mạng do artifact cung cấp không có chỗ trong tệp đã lắp ráp: bất kỳ mục nào cũng dừng build, nêu tên mục và fragment, theo các quy tắc trong Mọi khóa mà một fragment viết đều được mang theo hoặc bị từ chối. Hãy xóa mục đó và định hình mạng qua annotationaggrega.ai/namespace, hoặc cho một service tham gia mạng của các component được nêu tên quax-aggrega-networks-of; tác giả cần định tuyến giữa các mạng trong một tệp compose duy nhất dùngcompose-bridgeFeature.- Các thành viên mở rộng từ artifacts được mang theo. Một khóa
x-cấp cao nhất được viết sau các phần khác của tệp đã lắp ráp, theo thứ tự đã viết, theo các quy tắc trong Các thành viên mở rộng được mang theo đúng như khi viết. - Mọi khóa cấp cao nhất khác từ artifacts đều dừng build.
services:,volumes:,configs:,models:và các thành viên mở rộng là toàn bộ những gì bộ lắp ráp mang theo từ một fragment. Một khốisecrets:và mộtname:cấp cao nhất đều dừng build, nêu tên khóa và fragment, theo các quy tắc trong Mọi khóa mà một fragment viết đều được mang theo hoặc bị từ chối. - Một phần thân
artifacts:là một tài liệu. Một phần thân chứa nhiều tài liệu YAML sẽ dừng build, nêu tên fragment và số tài liệu nó chứa; hãy cho mỗi tài liệu một mụcartifacts:riêng.
Sự bất đối xứng giữa bốn khối đầu và networks: mang tính cấu trúc: services:, volumes:, configs: và models: mang nội dung theo từng Recipe mà bộ lắp ráp tích lũy vào tệp đã lắp ráp; networks: là hạ tầng theo từng boundary mà bộ lắp ráp suy ra từ trạng thái boundary. Artifacts có thể mở rộng nhóm thứ nhất; chỉ annotation của boundary mới định hình được nhóm thứ hai, đó là lý do mục mạng riêng của một artifact bị từ chối. Các thành viên mở rộng là dữ liệu mà Compose Specification định nghĩa cho các công cụ khác, nên chúng được mang theo đúng như khi viết. Mọi thứ khác là một dạng mà tài liệu đã lắp ráp không có chỗ cho, đó là lý do nó bị từ chối thay vì được hợp nhất.
Những gì compose provider không cung cấp
- Định tuyến L4 giữa các mạng trong cùng một tệp compose. Provider đặt mỗi node vào mạng của nó và cho một service tham gia các mạng mà
x-aggrega-networks-ofnêu tên, và tự nó không định tuyến gì giữa các mạng. Một service trong mạng A muốn kết nối tới một service trong mạng B bằng bất kỳ cách nào khác ngoài DNS mặc định của docker-compose đều cần đếncompose-bridgeFeature, có FeatureRecipe viết gateway và phần viết lại. - Định tuyến giữa các tệp compose. Các boundary được đánh giá thành những đường dẫn assembly khác nhau sẽ tạo ra các tệp
docker-compose.yamlkhác nhau; runtime của compose coi chúng là các dự án độc lập, vàcompose-bridgeFeature để nguyên kết nối giữa hai tệp như đã viết. Việc giao tiếp giữa các tệp thuộc trách nhiệm của người vận hành (công bố cổng trên host, dùng chung mạng bên ngoài, hoặc gộp các boundary về một đường dẫn thông qua mộtdirectory:dùng chung). - Lấy giá trị biến môi trường từ một attachment. Compose không có primitive nào cho việc này, nên một mục
attachmentscủa Workload vớias: envsẽ xuất ra tên biến với giá trị rỗng thay vì một tham chiếu được phân giải lúc chạy. Placeholder này là có chủ ý — một biến có mặt nhưng rỗng sẽ hiển thị cho bất kỳ ai gỡ lỗi container, trong khi một biến vắng mặt thì không để lại gì để xem xét — và bản build thông báo điều đó thay vì để người dùng tự phát hiện: mỗi mục như vậy phát ra một cảnh báounsupported-fieldnêu tên mục tại tọa độ đã viết của nó (containers.<name>.attachments.<KEY>, hoặcinitContainers[<i>].attachments.<KEY>), để tác giả biết biến nào nhận giá trị rỗng và nó thuộc container nào. Cảnh báo chỉ mang tính tư vấn: bản build vẫn thành công, và tệp được render giống hệt từng byte so với khi không có cảnh báo.--no-unsupported-field-warningstắt loại cảnh báo này. Một mụcattachmentsvớias: filekhông bị ảnh hưởng — compose bind-mount nó, và không có cảnh báo nào được phát ra. - Nội dung
deploy:của chế độ swarm. Replicas, ràng buộc placement và chiến lược cập nhật dướideploy:là các tính năng của chế độ swarm, và compose provider chỉ nhắm tới compose trên một host duy nhất, nên nó không xuất ra thứ nào trong số đó. Nó có xuất radeploy.resources— các reservation và limit màresourcescủa một container ánh xạ tới, vốn được docker compose tôn trọng ở chế độ không phải swarm (xem Tài nguyên container). depends_oncó điều kiện theo trạng thái health từ một cạnhuses. Một phụ thuộc được suy ra từ một cạnhusesđược xuất ra không kèm điều kiện, với ngữ nghĩaservice_started; nó không chờ healthcheck của đích báo trạng thái healthy. Điều này liên quan đến ý nghĩa của một cạnhuses, chứ không phải một dạng mà provider không thể tạo ra: dạng đầy đủ được xuất ra cho việc chờ một init container, và một đợt triển khai thực sự có chờ trạng thái health của đích khi đích khai báo healthcheck.
Ví dụ soạn thảo
Một triển khai compose gồm hai service với một cạnh depends_on được suy ra từ uses:
# release.yaml fragmentspec: boundaries: production: annotations: aggrega.ai/namespace: prod components: api: {} db: {}# api RecipeapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: api:1.0 ports: http: 8080 health: live: http: /healthz services: public: type: NodePort ports: http: 8080# Aggregate fragment — api uses db, on a socket api's Component declaresapiVersion: aggrega.ai/v1beta1kind: Aggregatespec: components: api: type: example/compute/api:1.0.0 uses: backend: db: target: db db: type: example/datastore/db:1.0.0Compose provider tạo ra một tệp docker-compose.yaml tại đường dẫn đã được đánh giá của boundary (mặc định là dist/boundaries/production/compose/docker-compose.yaml, vì directory: của một boundary mặc định là dist/boundaries/<name> và subDirectory: mặc định là {{ .capability }}), chứa:
services.api(service api chính, networkprod, ports8080:8080, healthcheck quacurl,depends_on: [db])services.db(service db chính, networkprod)networks.prod(docker network của boundary)
Tài liệu tham khảo liên quan
- Thực thể Workload — loại Workload do nền tảng sở hữu mà compose provider chuyển đổi.
- Kiến trúc Provider — cách các provider khớp vào quy trình biên dịch.
- Các annotation phổ biến — các annotation
aggrega.ai/*mà compose provider sử dụng. - Chỉ mục tham chiếu Provider — những gì mỗi provider của thư viện chuẩn tạo ra, và trang nào trả lời câu hỏi nào.
- Kết hợp đầu vào Recipe — Ma trận năng lực Provider chuẩn.