mirror of
https://github.com/psviderski/uncloud.git
synced 2026-08-26 11:03:34 +00:00
docs: move Compose extensions to a separate reference page
This commit is contained in:
Pasha Sviderski
@@ -141,7 +141,7 @@ This generates tags like:
|
|||||||
`uc deploy` renders the image templates when it loads the Compose file and then uses the resulting names for the build
|
`uc deploy` renders the image templates when it loads the Compose file and then uses the resulting names for the build
|
||||||
and deploy stages.
|
and deploy stages.
|
||||||
|
|
||||||
See the [Image tag template](../../8-compose-file-reference/2-image-tag-template.md) reference for all available
|
See the [Image tag template](../../8-compose-file-reference/3-image-tag-template.md) reference for all available
|
||||||
template variables and functions.
|
template variables and functions.
|
||||||
|
|
||||||
### Separate build and deploy steps
|
### Separate build and deploy steps
|
||||||
@@ -338,7 +338,7 @@ services:
|
|||||||
With this configuration, `uc deploy` and other commands using the Compose file will always target the `prod` context,
|
With this configuration, `uc deploy` and other commands using the Compose file will always target the `prod` context,
|
||||||
regardless of your currently active context. You can still override it with the `--context` flag if needed.
|
regardless of your currently active context. You can still override it with the `--context` flag if needed.
|
||||||
|
|
||||||
See [`x-context`](../../8-compose-file-reference/1-support-matrix.md#x-context) for more details.
|
See [`x-context`](../../8-compose-file-reference/2-extensions.md#x-context) for more details.
|
||||||
|
|
||||||
## Use a different Compose file location
|
## Use a different Compose file location
|
||||||
|
|
||||||
|
|||||||
@@ -1,13 +1,13 @@
|
|||||||
# Deploy to specific machines
|
# Deploy to specific machines
|
||||||
|
|
||||||
Deploy services to specific machines in your cluster using the
|
Deploy services to specific machines in your cluster using the
|
||||||
[`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines) extension in your Compose file.
|
[`x-machines`](../../8-compose-file-reference/2-extensions.md#x-machines) extension in your Compose file.
|
||||||
|
|
||||||
## When to target specific machines
|
## When to target specific machines
|
||||||
|
|
||||||
By default, Uncloud randomly chooses available machines to run your services on, evenly spreading multiple replicas of a
|
By default, Uncloud randomly chooses available machines to run your services on, evenly spreading multiple replicas of a
|
||||||
service across all machines for high availability. You can restrict which machines can run your service using the
|
service across all machines for high availability. You can restrict which machines can run your service using the
|
||||||
[`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines) extension in your Compose file.
|
[`x-machines`](../../8-compose-file-reference/2-extensions.md#x-machines) extension in your Compose file.
|
||||||
|
|
||||||
This is useful when you want to:
|
This is useful when you want to:
|
||||||
|
|
||||||
|
|||||||
@@ -33,7 +33,7 @@ Uncloud doesn't automatically scale global services to new machines.
|
|||||||
|
|
||||||
## Deploy to a subset of machines
|
## Deploy to a subset of machines
|
||||||
|
|
||||||
You can combine the `global` mode with [`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines)
|
You can combine the `global` mode with [`x-machines`](../../8-compose-file-reference/2-extensions.md#x-machines)
|
||||||
to deploy one container to each specified machine:
|
to deploy one container to each specified machine:
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
```yaml title="compose.yaml"
|
||||||
|
|||||||
@@ -29,7 +29,7 @@ changes do not persist after the hook finishes, except for changes written to sh
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Add the [`x-pre_deploy`](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy) extension to a service in your
|
Add the [`x-pre_deploy`](../../8-compose-file-reference/2-extensions.md#x-pre_deploy) extension to a service in your
|
||||||
Compose file. The only required attribute is `command`, which can be a string or a list of strings, just like the
|
Compose file. The only required attribute is `command`, which can be a string or a list of strings, just like the
|
||||||
service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command).
|
service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command).
|
||||||
|
|
||||||
@@ -54,7 +54,7 @@ hook and regular service containers.
|
|||||||
Since your command runs in the same image as the service, any tools or dependencies it needs must be installed in that
|
Since your command runs in the same image as the service, any tools or dependencies it needs must be installed in that
|
||||||
image.
|
image.
|
||||||
|
|
||||||
See [`x-pre_deploy`](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy) for all available attributes and
|
See [`x-pre_deploy`](../../8-compose-file-reference/2-extensions.md#x-pre_deploy) for all available attributes and
|
||||||
their defaults.
|
their defaults.
|
||||||
|
|
||||||
### Database migrations
|
### Database migrations
|
||||||
@@ -203,7 +203,7 @@ Most database migration tools handle this naturally since they track which migra
|
|||||||
|
|
||||||
## See also
|
## See also
|
||||||
|
|
||||||
- [`x-pre_deploy` reference](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy): All available attributes
|
- [`x-pre_deploy` reference](../../8-compose-file-reference/2-extensions.md#x-pre_deploy): All available attributes
|
||||||
and their defaults
|
and their defaults
|
||||||
- [Rolling deployments](4-rolling-deployments.md): How Uncloud updates containers with zero downtime
|
- [Rolling deployments](4-rolling-deployments.md): How Uncloud updates containers with zero downtime
|
||||||
- [Deploy an app](1-deploy-app.md): Build and deploy from source code or pre-built images
|
- [Deploy an app](1-deploy-app.md): Build and deploy from source code or pre-built images
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
# Compose support matrix
|
# Compose support matrix
|
||||||
|
|
||||||
Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some extensions and limitations.
|
Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some
|
||||||
The following table shows the support status for main Compose features.
|
[extensions](2-extensions.md) and limitations. The following table shows the support status for main Compose features.
|
||||||
|
|
||||||
:::info
|
:::info
|
||||||
|
|
||||||
@@ -39,7 +39,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea
|
|||||||
| `memswap_limit` | ❌ Not supported | |
|
| `memswap_limit` | ❌ Not supported | |
|
||||||
| `networks` | ❌ Not supported | All containers share cluster network |
|
| `networks` | ❌ Not supported | All containers share cluster network |
|
||||||
| `pid` | ✅ Supported | Set the PID namespace mode, `pid: host` only |
|
| `pid` | ✅ Supported | Set the PID namespace mode, `pid: host` only |
|
||||||
| `ports` | ⚠️ Limited | `mode: host` only, use [`x-ports`](#x-ports) for HTTP/HTTPS |
|
| `ports` | ⚠️ Limited | `mode: host` only, use [`x-ports`](2-extensions.md#x-ports) for HTTP/HTTPS |
|
||||||
| `privileged` | ✅ Supported | Run containers in privileged mode |
|
| `privileged` | ✅ Supported | Run containers in privileged mode |
|
||||||
| `pull_policy` | ✅ Supported | `always`, `missing`, `never` |
|
| `pull_policy` | ✅ Supported | `always`, `missing`, `never` |
|
||||||
| `secrets` | ❌ Not supported | Use configs or environment variables |
|
| `secrets` | ❌ Not supported | Use configs or environment variables |
|
||||||
@@ -54,7 +54,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea
|
|||||||
| **Deploy** | | |
|
| **Deploy** | | |
|
||||||
| `labels` | ❌ Not supported | |
|
| `labels` | ❌ Not supported | |
|
||||||
| `mode` | ✅ Supported | Either `global` or `replicated` |
|
| `mode` | ✅ Supported | Either `global` or `replicated` |
|
||||||
| `placement` | ❌ Not supported | Use [`x-machines`](#x-machines) extension |
|
| `placement` | ❌ Not supported | Use [`x-machines`](2-extensions.md#x-machines) extension |
|
||||||
| `replicas` | ✅ Supported | Number of container replicas |
|
| `replicas` | ✅ Supported | Number of container replicas |
|
||||||
| `resources` | ⚠️ Limited | CPU, memory limits and device reservations |
|
| `resources` | ⚠️ Limited | CPU, memory limits and device reservations |
|
||||||
| `restart_policy` | ❌ Not supported | Defaults to `unless-stopped` |
|
| `restart_policy` | ❌ Not supported | Defaults to `unless-stopped` |
|
||||||
@@ -91,115 +91,4 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea
|
|||||||
- ⚠️ **Limited**: Partial support or with restrictions
|
- ⚠️ **Limited**: Partial support or with restrictions
|
||||||
- ❌ **Not supported**: Feature is not (yet) available
|
- ❌ **Not supported**: Feature is not (yet) available
|
||||||
|
|
||||||
## Uncloud extensions
|
See [Compose extensions](2-extensions.md) for details on additional Compose features provided by Uncloud.
|
||||||
|
|
||||||
Uncloud provides several custom extensions to enhance the Compose experience:
|
|
||||||
|
|
||||||
### `x-context`
|
|
||||||
|
|
||||||
Set the cluster context for all commands that use the Compose file, such as `deploy`, `build`, and `logs`. This is
|
|
||||||
useful when you manage multiple clusters and want to make sure a Compose file is always deployed to the right one. No
|
|
||||||
need to remember to manually switch clusters with `uc ctx` or `--context`.
|
|
||||||
|
|
||||||
`x-context` is a top-level key, not a service-level attribute.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
x-context: prod
|
|
||||||
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
image: nginx
|
|
||||||
```
|
|
||||||
|
|
||||||
The `--context` and `--connect` flags take precedence over `x-context`. If you don't specify any of these, the current
|
|
||||||
context from your Uncloud config (`--uncloud-config`) is used.
|
|
||||||
|
|
||||||
:::warning
|
|
||||||
|
|
||||||
If you share the Compose file with other users, make sure to use the same context name for the target cluster in your
|
|
||||||
Uncloud configs.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
### `x-ports`
|
|
||||||
|
|
||||||
Expose HTTP/HTTPS service ports via the Caddy reverse proxy, or bind TCP/UDP ports directly to the host:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
image: nginx
|
|
||||||
x-ports:
|
|
||||||
- 80/https
|
|
||||||
- example.com:80/https
|
|
||||||
- 8080:80/tcp@host
|
|
||||||
```
|
|
||||||
|
|
||||||
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
|
||||||
|
|
||||||
### `x-caddy`
|
|
||||||
|
|
||||||
Custom Caddy reverse proxy configuration for a service:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
image: nginx
|
|
||||||
x-caddy: |
|
|
||||||
example.com {
|
|
||||||
reverse_proxy {{upstreams 80}}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
|
||||||
|
|
||||||
### `x-machines`
|
|
||||||
|
|
||||||
Restrict which machines can run your service. If you deploy multiple replicas, Uncloud automatically spreads them across
|
|
||||||
the specified machines.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
image: nginx
|
|
||||||
x-machines:
|
|
||||||
- machine-1
|
|
||||||
- machine-2
|
|
||||||
# Short syntax for a single machine
|
|
||||||
# x-machines: machine-1
|
|
||||||
```
|
|
||||||
|
|
||||||
### `x-pre_deploy`
|
|
||||||
|
|
||||||
Configure a pre-deploy hook to run a one-off command in a separate container and wait for it to finish successfully
|
|
||||||
before rolling out service containers. It's useful for preparation tasks that need to run before every service
|
|
||||||
deployment, such as database migrations, static asset uploads, or cache invalidation.
|
|
||||||
|
|
||||||
The hook container uses the service's image and inherits its environment variables, volumes, placement, and compute
|
|
||||||
resources. If the command fails or times out (5 minutes by default), the deployment stops.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
web:
|
|
||||||
build: .
|
|
||||||
x-pre_deploy:
|
|
||||||
command: python manage.py migrate
|
|
||||||
environment:
|
|
||||||
LOG_LEVEL: DEBUG
|
|
||||||
timeout: 10m
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Attributes
|
|
||||||
|
|
||||||
| Attribute | Type | Default | Description |
|
|
||||||
|---------------|-------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
||||||
| `command` | string / list | (required) | The command to run in the hook container (same format as the service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command)) |
|
|
||||||
| `environment` | map / list of KEY=VALUE | - | Additional env vars that override or extend the service's [`environment`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#environment) |
|
|
||||||
| `privileged` | bool | service's value | Override the service's [`privileged`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#privileged) mode |
|
|
||||||
| `timeout` | duration | `5m` | Max time to wait for the command to finish before killing it (e.g., `1m30s`, `30m`, `1h`) |
|
|
||||||
| `user` | string | service's value | Override the service's [`user`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#user) to run as (`user`, `UID`, `user:group`, or `UID:GID`) |
|
|
||||||
|
|
||||||
The hook container also gets `UNCLOUD_HOOK_PRE_DEPLOY=true` environment variable set automatically.
|
|
||||||
|
|
||||||
See [Pre-deploy hooks](../4-guides/1-deployments/5-pre-deploy-hooks.md) for more details, usage examples, and failure
|
|
||||||
handling.
|
|
||||||
|
|||||||
@@ -0,0 +1,119 @@
|
|||||||
|
---
|
||||||
|
title: Compose extensions
|
||||||
|
---
|
||||||
|
|
||||||
|
# Uncloud-specific Compose extensions
|
||||||
|
|
||||||
|
Uncloud provides several custom extensions to the standard [Compose specification](https://compose-spec.io/) that let
|
||||||
|
you configure Uncloud-specific features directly in your Compose file.
|
||||||
|
|
||||||
|
See the [support matrix](1-support-matrix.md) for the full list of supported standard Compose features.
|
||||||
|
|
||||||
|
## `x-context`
|
||||||
|
|
||||||
|
Set the cluster context for all commands that use the Compose file, such as `deploy`, `build`, and `logs`. This is
|
||||||
|
useful when you manage multiple clusters and want to make sure a Compose file is always deployed to the right one. No
|
||||||
|
need to remember to manually switch clusters with `uc ctx` or `--context`.
|
||||||
|
|
||||||
|
`x-context` is a top-level key, not a service-level attribute.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
x-context: prod
|
||||||
|
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
The `--context` and `--connect` flags take precedence over `x-context`. If you don't specify any of these, the current
|
||||||
|
context from your Uncloud config (`--uncloud-config`) is used.
|
||||||
|
|
||||||
|
:::warning
|
||||||
|
|
||||||
|
If you share the Compose file with other users, make sure to use the same context name for the target cluster in your
|
||||||
|
Uncloud configs.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
## `x-ports`
|
||||||
|
|
||||||
|
Expose HTTP/HTTPS service ports via the Caddy reverse proxy, or bind TCP/UDP ports directly to the host:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: nginx
|
||||||
|
x-ports:
|
||||||
|
- 80/https
|
||||||
|
- example.com:80/https
|
||||||
|
- 8080:80/tcp@host
|
||||||
|
```
|
||||||
|
|
||||||
|
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
||||||
|
|
||||||
|
## `x-caddy`
|
||||||
|
|
||||||
|
Custom Caddy reverse proxy configuration for a service:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: nginx
|
||||||
|
x-caddy: |
|
||||||
|
example.com {
|
||||||
|
reverse_proxy {{upstreams 80}}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
|
||||||
|
|
||||||
|
## `x-machines`
|
||||||
|
|
||||||
|
Restrict which machines can run your service. If you deploy multiple replicas, Uncloud automatically spreads them across
|
||||||
|
the specified machines.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: nginx
|
||||||
|
x-machines:
|
||||||
|
- machine-1
|
||||||
|
- machine-2
|
||||||
|
# Short syntax for a single machine
|
||||||
|
# x-machines: machine-1
|
||||||
|
```
|
||||||
|
|
||||||
|
## `x-pre_deploy`
|
||||||
|
|
||||||
|
Configure a pre-deploy hook to run a one-off command in a separate container and wait for it to finish successfully
|
||||||
|
before rolling out service containers. It's useful for preparation tasks that need to run before every service
|
||||||
|
deployment, such as database migrations, static asset uploads, or cache invalidation.
|
||||||
|
|
||||||
|
The hook container uses the service's image and inherits its environment variables, volumes, placement, and compute
|
||||||
|
resources. If the command fails or times out (5 minutes by default), the deployment stops.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
x-pre_deploy:
|
||||||
|
command: python manage.py migrate
|
||||||
|
environment:
|
||||||
|
LOG_LEVEL: DEBUG
|
||||||
|
timeout: 10m
|
||||||
|
```
|
||||||
|
|
||||||
|
### Attributes
|
||||||
|
|
||||||
|
| Attribute | Type | Default | Description |
|
||||||
|
|---------------|-------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `command` | string / list | (required) | The command to run in the hook container (same format as the service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command)) |
|
||||||
|
| `environment` | map / list of KEY=VALUE | - | Additional env vars that override or extend the service's [`environment`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#environment) |
|
||||||
|
| `privileged` | bool | service's value | Override the service's [`privileged`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#privileged) mode |
|
||||||
|
| `timeout` | duration | `5m` | Max time to wait for the command to finish before killing it (e.g., `1m30s`, `30m`, `1h`) |
|
||||||
|
| `user` | string | service's value | Override the service's [`user`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#user) to run as (`user`, `UID`, `user:group`, or `UID:GID`) |
|
||||||
|
|
||||||
|
The hook container also gets `UNCLOUD_HOOK_PRE_DEPLOY=true` environment variable set automatically.
|
||||||
|
|
||||||
|
See [Pre-deploy hooks](../4-guides/1-deployments/5-pre-deploy-hooks.md) for more details, usage examples, and failure
|
||||||
|
handling.
|
||||||
Reference in New Issue
Block a user