Skip to main content

Deploy to specific machines

Deploy services to specific machines in your cluster using the 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 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.

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:

  • 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 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 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 command:

# 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 for more details.

See also​