Skip to main content
This feature is in public preview.
A deployment manages a fleet of instances running on a capacity. You specify an instance template and a target instance count. The deployment creates and removes instances to match the target. Without a deployment, you create and manage instances manually. If an instance is destroyed because its allocation ended, nothing replaces it. A deployment maintains your target count by creating a new instance in awaiting_allocation state, which starts running when allocation becomes available.

​
Create a deployment

sf deployments create \
  --capacity dev \
  --instance-template prod-ubuntu \
  --target-instance-count 4
This creates a deployment that maintains 4 instances on the dev capacity, each configured according to the referenced instance template.

​
Instance templates

A deployment references an instance template that defines the image, cloud-init script, and other configuration for each instance. Create an instance template first, then reference it in the deployment. Updating the instance template only affects new instances created by the deployment.

​
Instance name templates

Instances created by a deployment get auto-generated names. You can provide a naming pattern with --instance-name-template to give instances predictable names. 
sf deployments create \
  --capacity dev \
  --instance-template prod-ubuntu \
  --target-instance-count 4 \
  --instance-name-template "worker-{{nanoid(10)}}"

​
List deployments

sf deployments list

NAME              CAPACITY      INSTANCES  STATUS  MESSAGE
prod-workers      prod-cluster  8          info    running
ml-training-pool  ml-training   32         info    running

​
Get deployment details

sf deployments get prod-workers

│ DEPLOYMENT ID      depl_Xm9pR2wLk7Nf3Qy8Td5V
│ NAME               prod-workers
│ CAPACITY           prod-cluster (cap_yIwQRIaE8bJo4Gs0000)
│ INSTANCE TEMPLATE  prod-ubuntu (ntmpl_Gw5rT8mKn2Pj4Lx9Qf7Y)
│ TARGET INSTANCES   8
│ NAME TEMPLATE      {{adjective}}-{{noun}}-{{nanoid(6)}}
│ STATUS             info
│ MESSAGE            running
│ CREATED            Mar 25, 2:00pm PDT
└ UPDATED            Mar 30, 1:00pm PDT

​
Update a deployment

Change the target instance count, instance template, or name. 
sf deployments set prod-workers --target-instance-count 16
Switch to a different instance template. 
sf deployments set prod-workers --instance-template prod-ubuntu-v2

​
Delete a deployment

sf deployments delete prod-workers
Deleting a deployment deletes all instances that are running under that deployment.

​
API reference

See the Deployments API for programmatic access.