mirror of
https://github.com/psviderski/uncloud.git
synced 2026-08-26 19:13:34 +00:00
docs: split 'Deploy to specific machines' and 'Deploy a global service' into separate guides
This commit is contained in:
Pasha Sviderski
+15
-87
@@ -11,12 +11,12 @@ This guide covers both scenarios:
|
||||
|
||||
Uncloud uses [Compose Specification](https://compose-spec.io/) for defining the deployment configuration of your app's
|
||||
services. It implements the most common Compose features with some Uncloud-specific extensions. See
|
||||
[Compose support matrix](../8-compose-file-reference/1-support-matrix.md) for details.
|
||||
[Compose support matrix](../../8-compose-file-reference/1-support-matrix.md) for details.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `uc` CLI [installed](../2-getting-started/1-install-cli.md) on your local machine
|
||||
- An Uncloud cluster with at least one machine (see [Quick start](../2-getting-started/2-deploy-demo-app.md))
|
||||
- `uc` CLI [installed](../../2-getting-started/1-install-cli.md) on your local machine
|
||||
- An Uncloud cluster with at least one machine (see [Quick start](../../2-getting-started/2-deploy-demo-app.md))
|
||||
- Basic knowledge of [Compose Specification](https://compose-spec.io/)
|
||||
|
||||
## Deploy from source code
|
||||
@@ -62,7 +62,7 @@ This command looks for a Compose file in your current working directory and:
|
||||
5. **Deploys service containers** using the built images and latest configuration changes with zero-downtime rolling
|
||||
updates
|
||||
|
||||
See the [uc deploy](../9-cli-reference/uc_deploy.md) reference for all available options.
|
||||
See the [uc deploy](../../9-cli-reference/uc_deploy.md) reference for all available options.
|
||||
|
||||
Watch `uc deploy` building and deploying a demo app (18 seconds):
|
||||
|
||||
@@ -140,7 +140,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 format](../8-compose-file-reference/2-image-tag-format.md) reference for all available template
|
||||
See the [Image tag format](../../8-compose-file-reference/2-image-tag-format.md) reference for all available template
|
||||
variables and functions.
|
||||
|
||||
### Separate build and deploy steps
|
||||
@@ -251,7 +251,7 @@ machines. For example, images you built locally outside of the Compose workflow
|
||||
is unreachable from your cluster machines. This is useful for deploying to air-gapped or restricted environments.
|
||||
|
||||
You can push these local images directly to your cluster machines using the
|
||||
[`uc image push`](../9-cli-reference/uc_image_push.md) command:
|
||||
[`uc image push`](../../9-cli-reference/uc_image_push.md) command:
|
||||
|
||||
```shell
|
||||
# Push to *all* cluster machines
|
||||
@@ -276,7 +276,7 @@ services:
|
||||
pull_policy: never
|
||||
```
|
||||
|
||||
Run [`uc images`](../9-cli-reference/uc_images.md) to verify that the image is available on the target machines.
|
||||
Run [`uc images`](../../9-cli-reference/uc_images.md) to verify that the image is available on the target machines.
|
||||
|
||||
Then deploy as usual:
|
||||
|
||||
@@ -321,86 +321,6 @@ Choose unique names to avoid conflicts with services deployed from other Compose
|
||||
|
||||
:::
|
||||
|
||||
## Deploy to specific machines
|
||||
|
||||
By default, Uncloud randomly chooses available machines to run your services on, 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.
|
||||
|
||||
This is useful when you want to:
|
||||
|
||||
- Deploy services to machines in a specific region or data center
|
||||
- Run services only on machines with specific hardware (for example, GPUs or ARM processors)
|
||||
- Keep certain services isolated to dedicated machines
|
||||
- Deploy to a subset of machines for testing before rolling out cluster-wide
|
||||
|
||||
Here's a basic example:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
x-ports:
|
||||
- app.example.com:8000/https
|
||||
# Spread 3 replicas across machine-1 and machine-2 only
|
||||
scale: 3
|
||||
x-machines:
|
||||
- machine-1
|
||||
- machine-2
|
||||
|
||||
db:
|
||||
image: postgres:18
|
||||
environment:
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD}
|
||||
volumes:
|
||||
- db-data:/var/lib/postgresql
|
||||
# Create the db-data volume and run the DB container on machine-db
|
||||
x-machines: machine-db
|
||||
|
||||
volumes:
|
||||
db-data:
|
||||
```
|
||||
|
||||
When you deploy this Compose file with `uc deploy`:
|
||||
|
||||
- The `web` service will create and spread its 3 replicas only across `machine-1` and `machine-2`
|
||||
- The `db` service will create its `db-data` volume and run only on `machine-db`
|
||||
|
||||
:::tip
|
||||
|
||||
Use [`uc machine ls`](../9-cli-reference/uc_machine_ls.md) to see available machines in your cluster.
|
||||
|
||||
:::
|
||||
|
||||
### Push images to specific machines only
|
||||
|
||||
When building from source, `uc deploy` and `uc build --push` automatically push images to **all** cluster machines by
|
||||
default. This ensures images are available wherever services might be deployed.
|
||||
|
||||
If you're using `x-machines` to restrict deployments to specific machines, `uc deploy` and `uc build --push` push images
|
||||
only to those machines. This saves time and bandwidth by uploading images only where they're needed.
|
||||
|
||||
## Run one replica on each machine
|
||||
|
||||
To deploy exactly one service replica on each machine in your cluster, set
|
||||
[`mode: global`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode) under the `deploy` section. It's
|
||||
useful for cluster-wide services like monitoring agents, log collectors, or reverse proxies.
|
||||
|
||||
You can also combine `mode: global` with `x-machines` to run one container on each machine in a specific set.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
monitoring:
|
||||
image: quay.io/prometheus/node-exporter:latest
|
||||
deploy:
|
||||
# Run one container on each machine in the cluster
|
||||
mode: global
|
||||
# Optionally run one container on each of these specific machines only
|
||||
#x-machines:
|
||||
# - machine-1
|
||||
# - machine-2
|
||||
```
|
||||
|
||||
## Use a different Compose file location
|
||||
|
||||
If your Compose file has a different name or location, use the `-f/--file` flag to specify its path:
|
||||
@@ -432,3 +352,11 @@ and inspecting the status of containers for a specific service:
|
||||
```shell
|
||||
uc inspect web
|
||||
```
|
||||
|
||||
# See also
|
||||
|
||||
- [Deploy to specific machines](2-deploy-specific-machines.md): Deploy services to specific machines in your cluster
|
||||
- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
|
||||
- [Compose Specification](https://compose-spec.io/): Official specification for the Compose file format
|
||||
- [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md): Supported Compose features and Uncloud
|
||||
extensions
|
||||
@@ -0,0 +1,84 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
This is useful when you want to:
|
||||
|
||||
- Deploy services to machines in a **specific region** or **data center**
|
||||
- Run services only on machines with **specific hardware** (for example, GPUs or ARM processors)
|
||||
- Specify where to deploy **stateful services** and create their data volumes
|
||||
- Keep certain services isolated to **dedicated machines**
|
||||
- Deploy to a subset of machines for **testing** before rolling out cluster-wide
|
||||
|
||||
## Target machines in a Compose file
|
||||
|
||||
Set `x-machines` to a list of machine names or a single machine name to restrict which machines a service can run on.
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
x-ports:
|
||||
- app.example.com:8000/https
|
||||
# Spread 3 replicas across machine-1 and machine-2 only
|
||||
x-machines:
|
||||
- machine-1
|
||||
- machine-2
|
||||
scale: 3
|
||||
|
||||
db:
|
||||
image: postgres:18
|
||||
environment:
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD}
|
||||
volumes:
|
||||
- db-data:/var/lib/postgresql
|
||||
# Create the db-data volume and run the DB container on machine-db
|
||||
x-machines: machine-db
|
||||
|
||||
volumes:
|
||||
db-data:
|
||||
```
|
||||
|
||||
When you deploy this Compose file with [`uc deploy`](../../9-cli-reference/uc_deploy.md):
|
||||
|
||||
- The `web` service will create and spread its 3 replicas only across `machine-1` and `machine-2`
|
||||
- The `db` service will create its `db-data` volume and run only on `machine-db`
|
||||
|
||||
:::tip
|
||||
|
||||
Use [`uc machine ls`](../../9-cli-reference/uc_machine_ls.md) to see available machines in your cluster.
|
||||
|
||||
:::
|
||||
|
||||
## Push images to specific machines only
|
||||
|
||||
When [building from source](1-deploy-app.md#deploy-from-source-code), `uc deploy` and `uc build --push` automatically
|
||||
push built images to **all** cluster machines by default. This ensures images are available wherever services might be
|
||||
deployed.
|
||||
|
||||
If you're using `x-machines` to restrict deployments to specific machines, `uc deploy` and `uc build --push` push images
|
||||
**only to those** machines. This saves time and bandwidth by uploading images only where they're needed.
|
||||
|
||||
You can also manually push your local Docker images to specific machines using the [
|
||||
`uc image push`](../../9-cli-reference/uc_image_push.md) command:
|
||||
|
||||
```shell
|
||||
# Push the local Docker image 'myapp:latest' to machine-1 and machine-2
|
||||
uc image push myapp:latest -m machine-1,machine-2
|
||||
```
|
||||
|
||||
See [Push local images to cluster machines](1-deploy-app.md#push-local-images-to-cluster-machines) for more details.
|
||||
|
||||
## See also
|
||||
|
||||
- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
|
||||
- [Deploy an app](1-deploy-app.md): Deploy from source code or prebuilt images
|
||||
- [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md): Supported Compose features and Uncloud
|
||||
extensions
|
||||
@@ -0,0 +1,68 @@
|
||||
# Deploy a global service
|
||||
|
||||
Deploy exactly one replica of a service on each machine in your cluster.
|
||||
|
||||
This is useful for cluster-wide infrastructure services like monitoring or security agents, log collectors, or reverse
|
||||
proxies.
|
||||
|
||||
## Deploy to all machines
|
||||
|
||||
To deploy exactly one replica on each machine in your cluster for a specific service, set
|
||||
[`mode: global`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode) under the `deploy` section in
|
||||
your Compose file:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
monitoring:
|
||||
image: quay.io/prometheus/node-exporter:latest
|
||||
deploy:
|
||||
# Run one container on each machine in the cluster
|
||||
mode: global
|
||||
```
|
||||
|
||||
Then deploy:
|
||||
|
||||
```shell
|
||||
uc deploy
|
||||
```
|
||||
|
||||
Before creating replicas on cluster machines, it will show you a deployment plan and ask for confirmation.
|
||||
|
||||
If you add more machines to the cluster later, you need to run `uc deploy` again to create replicas on the new machines.
|
||||
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)
|
||||
to deploy one container to each specified machine:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
caddy:
|
||||
image: caddy:2
|
||||
deploy:
|
||||
# Run one container on each of the three specified machines
|
||||
mode: global
|
||||
x-machines:
|
||||
- ingress-1
|
||||
- ingress-2
|
||||
- ingress-3
|
||||
```
|
||||
|
||||
This is useful when you want a service on a specific group of machines (for example, ingress or GPU machines) but still
|
||||
want the one-per-machine guarantee that global mode provides.
|
||||
|
||||
## Global vs replicated mode
|
||||
|
||||
The default mode is `replicated`, where you specify the number of replicas.
|
||||
|
||||
| Mode | Replicas | Placement |
|
||||
|------------------------|-----------------------------------------------|---------------------------------------------------------------------|
|
||||
| `replicated` (default) | You specify with `scale` or `deploy.replicas` | Uncloud evenly spreads replicas across all machines or `x-machines` |
|
||||
| `global` | Always one per machine | One replica on each machine or each `x-machines` machine |
|
||||
|
||||
## See also
|
||||
|
||||
- [Deploy to specific machines](2-deploy-specific-machines.md): Deploy services to specific machines in your cluster
|
||||
- [Compose Specification: deploy.mode](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode):
|
||||
Compose specification for deployment modes
|
||||
@@ -0,0 +1,4 @@
|
||||
label: Deployments
|
||||
collapsed: false # keep the category open by default
|
||||
link:
|
||||
type: generated-index
|
||||
Reference in New Issue
Block a user