Machine in Bathtub

This post is a part of our Octopus 3.4 blog series. Follow it on our blog or our twitter feed.

Octopus Deploy 3.4 has shipped! Read the blog post and download it today!


Octopus 3.4 introduces the concept of machine policies. Machine policies allow the automatic deletion of unavailable machines after a configurable time period has elapsed.

What is a machine?

In Octopus land (deep under the sea) we use the term deployment target to describe the types of things that can be deployed to. They might be Tentacles, SSH endpoints, Offline Drops or Cloud Regions. In the past we had Azure related deployment targets. The functionality in machine policies does not make sense for some deployment targets so we have decided on the word machine to identify the subset of deployment targets where the functionality does make sense. At the moment machine policies are most applicable to Tentacle and SSH deployment targets.

Why automatically delete machines?

The typical life cycle for infrastructure as it relates to Octopus is:

  • Provision the infrastructure
  • Install Tentacle or SSH
  • Register the Tentacle or SSH endpoint with the Octopus Server
  • Deploy!
  • Terminate the infrastructure
  • Remove the endpoint from the Octopus Server

Small-scale and long-lived infrastructure is easily managed in Octopus without machine policies. If there are only two Tentacles registered with Octopus or the lifetime of a Tentacle is a few years it is not much of a burden to remove the Tentacle from Octopus when a piece of infrastructure is terminated.

As scale increases and lifetime decreases it becomes increasingly difficult to manage machines in Octopus. Consider auto-scaling infrastructure where hundreds of machines are provisioned and terminated throughout the day. This scenario quickly becomes a nightmare attempting to keep Octopus in sync with changes to the underlying infrastructure. By using machine policies, Octopus can be configured to automatically remove machines when the infrastructure is terminated.

Configuring Octopus to automatically delete machines

To configure a machine policy to automatically delete machines:

Find Machine Policies on the Environments screen:

Machine Policies

Create a new machine policy by selecting Add Machine Policy or select the Default Machine Policy:

Create a Machine Policy

Change the setting "Clean up unavailable machines" to "Automatically delete unavailable machines". Change the "Hours unavailable" to the minimum number of hours a machine can be unavailable before it is deleted:

Automatically delete machines

Now machines that are assigned this machine policy will be permanently deleted when they are unavailable for the specified number of hours.

Assigning machine policies to machines

Machine policies can be assigned to machines via the Octopus portal by selecting a machine from the Environments page and using the Policy drop-down to select a machine policy:

Assign a Machine Policy

The command line can be used to assign a machine policy when registering a machine by using the --policy parameter:

Tentacle.exe register-with --instance "Tentacle" --policy "Transient machines" --server "http://YOUR_OCTOPUS" --apiKey="API-YOUR_API_KEY" --role "web-server" --environment "Staging" --comms-style TentaclePassive 

There is also a property called MachinePolicyId that is settable on MachineResource so a machine policy can be assigned via the Octopus API or through Octopus.Client:

$machine = New-Object Octopus.Client.Model.MachineResource
$machine.Endpoint = $tentacleEndpoint
$machine.Name = $machineName
$machine.MachinePolicyId = $machinePolicyId
$machine.EnvironmentIds.Add($environmentId) 
$machine.Roles.Add($role) 

If a machine is created and a machine policy has not been specified, the machine will be assigned the default machine policy.

How it works

Machine clean up uses the result of health checks as the criteria to determine if a machine should be deleted. When a machine's health is taken and Octopus is unable to contact the machine, its health status will become Unavailable. Octopus checks Unavailable machines every 5 minutes to determine machines that should be deleted. If a machine's machine policy has been configured to automatically delete Unavailable machines and the machine has been Unavailable for longer than the time specified in the machine policy, it will be permanently deleted from Octopus. Octopus will only delete enabled machines, so disable a machine if it is going offline and it should not be deleted.

Further information

Learn more about automatically deleting machines from our guide on cleaning up environments. Explore machine policies with our in-depth documentation or get in touch if you have comments, suggestions or just want to say "hi".


Octopus Deploy is used by thousands of developers across the globe, from small companies to large enterprises. Find out if it meets your deployment automation needs by taking advantage of our free 30-day trial. You can spin up an instance with just a few clicks!

New Releases