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
|
||||
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.
|
||||
|
||||
### 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,
|
||||
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
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
# Deploy to specific machines
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
[`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:
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ Uncloud doesn't automatically scale global services to new 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:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
|
||||
@@ -29,7 +29,7 @@ changes do not persist after the hook finishes, except for changes written to sh
|
||||
|
||||
## 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
|
||||
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
|
||||
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.
|
||||
|
||||
### Database migrations
|
||||
@@ -203,7 +203,7 @@ Most database migration tools handle this naturally since they track which migra
|
||||
|
||||
## 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
|
||||
- [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
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Compose support matrix
|
||||
|
||||
Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some extensions and limitations.
|
||||
The following table shows the support status for main Compose features.
|
||||
Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some
|
||||
[extensions](2-extensions.md) and limitations. The following table shows the support status for main Compose features.
|
||||
|
||||
:::info
|
||||
|
||||
@@ -39,7 +39,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea
|
||||
| `memswap_limit` | ❌ Not supported | |
|
||||
| `networks` | ❌ Not supported | All containers share cluster network |
|
||||
| `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 |
|
||||
| `pull_policy` | ✅ Supported | `always`, `missing`, `never` |
|
||||
| `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** | | |
|
||||
| `labels` | ❌ Not supported | |
|
||||
| `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 |
|
||||
| `resources` | ⚠️ Limited | CPU, memory limits and device reservations |
|
||||
| `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
|
||||
- ❌ **Not supported**: Feature is not (yet) available
|
||||
|
||||
## Uncloud extensions
|
||||
|
||||
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.
|
||||
See [Compose extensions](2-extensions.md) for details on additional Compose features provided by Uncloud.
|
||||
|
||||
@@ -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