Skip to main content

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 under the deploy section in your Compose file:

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:

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 to deploy one container to each specified machine:

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.

ModeReplicasPlacement
replicated (default)You specify with scale or deploy.replicasUncloud evenly spreads replicas across all machines or x-machines
globalAlways one per machineOne replica on each machine or each x-machines machine

See also​