Upgrading from Octopus 3.x

Last updated

The following guide provides an overview of how the various components of Octopus Deploy 3.x can be updated to the latest release.

Update Available Notification

When an update is available, a bullhorn icon will appear in the top status bar with details and a link to the downloads page.

What is included in the release?
You can find the differences between your current version and the newest version using our Compare versions page. Please note that this will also list the release notes for major and minor version changes which may include breaking changes or dependencies that you may need to also update. It is important to know what might be affected by your upgrade.

Scheduling maintenance

Upgrading Octopus Server is normally quite fast, however you should allow yourself time to perform a good backup and restore process.

You should also consider how long the actual upgrade may take:

  • Patch upgrades are usually very fast - only the executable binaries are upgraded.
  • Minor upgrades are usually quite fast, however these releases typically require database changes.
  • Major upgrades usually require detailed planning.

Upgrading Octopus Server

Upgrading the Octopus Deploy Server is easy, you will just need to follow these steps:

  1. Schedule a maintenance window: Octopus Server will be unavailable during the upgrade (unless you are upgrading Octopus HA)

  2. Switch your server to Maintenance Mode and wait until all current tasks and deployments have completed. This ensures that no further changes will be made that may potentially become lost if the upgrade fails and you need to rollback.

  3. Backup your database and master key so that it can be restored in case anything goes wrong.

  4. Download the latest Octopus Deploy MSI installer.

No internet connection required for install
Once you have downloaded the required version of the Octopus Server MSI no further internet connectivity is required. This allows for installation on servers and systems that have no internet connectivity.

  1. Run the installer and follow the prompts.

  2. Turn Maintenance Mode OFF.

  3. Calamari will then be automatically updated if required with the next health check or deployment that takes place.

No need to upgrade the Tentacle
Given that the deployment code is now embedded within Calamari, and this gets pushed out automatically as needed by the Octopus Deploy Server, you no longer need be concerned about ensuring the version number between Tentacle and Server remain in lockstep. Builds of the Server and the Tentacle are no longer in sync as of Octopus Deploy 3.14, and Octopus Server v3.x is compatible with all Tentacle 3.x versions. We hope splitting the Tentacle helps relieve some of the hassle and friction involved with upgrading Octopus and provides better communication about changes to Tentacle.

Upgrading Octopus HA

You should generally follow the same instructions as above but upgrade one node at a time. This will allow you to keep the cluster running and avoid interruption to your users. Read more about Managing High Availability Nodes.

It is important to upgrade all nodes in your cluster during the same maintenance window, especially if the database schema is changed. The database schema will be upgraded when you upgrade the first node. Any nodes running the old version can fail due to a database schema mismatch.

Upgrading Octopus HA nodes

Follow these steps to upgrade each node in your cluster:

  1. Go to the Configuration ➜ Nodes page

  2. Set Drain to ON for the node you want to upgrade

  3. Wait until all the running tasks complete

  4. Upgrade the Octopus Server instance on the node

  5. Set Drain to OFF so the node starts processing tasks again

Upgrading Calamari

Calamari will either self-update automatically during a deployment if they are out of date with the latest available on the server, or they can be manually updated to avoid interrupting the deployment.

Auto Update

During a deployment process one of the first commands that's executed on the Tentacle is a check to confirm that the latest version of Calamari exists on the target machine. This is currently done by checking for the existence for an empty file in the folder location of${env:TentacleHome}\Calamari\{{CalamariVersion}}\Success.txt where the CalamariVersion variable is defined by the latest available on the Server.

When deploying to an environment with out of date Calamaris, they will be automatically upgraded. An info message on the deployment page will notify the user that this will happen.

Manual Update

The environments page will make machines without latest Calamari yellow, and show a green Update button (per environment) - this will just run a script that ensures Calamari is there.

Upgrading Octopus Tentacles

The role of Tentacles has changed in Octopus 3.x. Tentacles in 3.x are only responsible for the secure communication protocol, and then calling Calamari to actually perform deployments. This means Tentacle only needs to change when we change some part of the secure communication protocol (hopefully very infrequently).

Why have there been so many different versions of Tentacle 3.x?
In early versions of 3.x we have been rebuilding Tentacle in lock-step with Octopus Server due to shared dependencies in their project structure even though there have not been any changes to Tentacle itself. We hope to unlock these in the near future.

Octopus 3.1 supports automatically updating Tentacles via the Environments page. You can upgrade all Tentacles which will systematically work through all Machines in all Environments in batches until all Tentacles are upgraded.

Alternatively you can upgrade Tentacles one Environment at a time.

Optional and Required Tentacle upgrades
In most cases we will maintain backwards compatibility between versions of Octopus Server and Tentacle. In these cases the Environments page will recommend updating your Tentacles while still allowing deployments to continue as normal. In the rare occasion we need to break compatibility you will be required to upgrade any incompatible Tentacles before you can Deploy to those machines again from the upgraded Octopus Server.

Upgrading to Octopus 3.1 or greater

Summary: Tentacle was upgraded from .NET 4.0 to .NET 4.5 to enable TLS 1.2.

You can upgrade to Octopus Server 3.1 without upgrading any Tentacles and get all of the new 3.1 deployment features because Calamari will continue to work on both Tentacle 3.0 and 3.1.

This is the first version of Octopus 3.x where there has been a Tentacle upgrade and it has caused some confusion. This section aims to answer some of the most commonly asked questions about upgrading to Octopus 3.1 and the impact on Tentacles.

Am I required to upgrade to Tentacle 3.1? No, you aren't required to upgrade to Tentacle 3.1. Tentacle 3.0 will still work and benefit from the latest version of Calamari and all of the deployment features we shipped in Octopus 3.1.

What changed with Tentacle 3.1? The Octopus-Tentacle communication protocol in 3.1 can use TLS 1.2 which requires .NET 4.5 to be installed on the server.

When should I upgrade to Tentacle 3.1? We recommend upgrading to Tentacle 3.1 as soon as you are able. Upgrading Tentacles in Octopus 3.1 is automated and can be done through the Environments page. The main benefit you'll get is the Octopus-Tentacle communication protocol can use TLS 1.2.

What would stop me from upgrading to Tentacle 3.1? Your server needs to support .NET 4.5. Tentacle 3.1 requires .NET 4.5 to be installed on the server, which is what enables TLS 1.2 support, and .NET 4.5 is supported on Windows Server 2008 SP2 or newer. This means Windows Server 2003 and Windows Server 2008 SP1 are not supported for Octopus Server or Tentacle 3.1.

How can I make Octopus/Tentacle use TLS 1.2 instead of TLS 1.0? Octopus Server and Tentacle to 3.1 will use TLS 1.2 by default. Tentacle 3.0 will still work with Octopus Server 3.1, but the communication protocol will fall back to the lowest-common denominator of TLS 1.0.

Can I have a mixture of Tentacle 3.0 and 3.1? I'm not ready to upgrade some of my application servers. Yes, you can have a mixture of Tentacle 3.0 and 3.1 working happily with Octopus Server 3.1. We have committed to maintaining compatibility with the communication protocol.

If I keep running Tentacle 3.0 does that mean I won't get any of the new Octopus 3.1 deployment features? The deployment features are handled by Calamari and Octopus Server makes sure all Tentacles have the latest Calamari. This means servers hosting Tentacle 3.0 or 3.1 will get all of the new deployment features we shipped with Octopus 3.1 by means of the latest Calamari.

Will you continue to support Windows Server 2003 or Windows Server 2008 SP1? No, from Octopus 3.1 onward we are dropping official support for Octopus Server and Tentacle hosted on Windows Server 2003 or Windows Server 2008 SP1.

Tentacle communications protocol
Read more about the Octopus - Tentacle communication protocol and Troubleshooting Schannel and TLS.

Upgrading to Octopus 3.4 or greater

See the Release Notes for breaking changes and more information.

Using TeamCity NuGet feeds? You will need to upgrade your TeamCity server to v9.0 or newer and enable the NuGet v2 API. Octopus 3.4+ no longer supports the custom NuGet v1 feeds from TeamCity 7.x-8.x. We recommend upgrading to the latest TeamCity version available due to continual improvements in their NuGet feed - or switch to using the Octopus built-in repository.

Want to use SemVer 2 for packages or releases? You will need to upgrade OctoPack and/or octo.exe to 3.4 or newer.

Upgrading to Octopus 3.5 or greater

Some server configuration values are moved from the config file into the database in 3.5+.

If you are upgrading to a 3.5+ version please backup your server config file prior to upgrading. If you need to downgrade then replace the config with the original file after the downgrade and restart Octopus Deploy server.

How to downgrade to a previously installed instance of Octopus Server

If for any reason you need to downgrade to a previous version of Octopus Server, follow the steps below:

  1. Turn Maintenance Mode ON.

Wait until all current tasks and deployments have completed.

  1. Navigate to the Octopus Manager and stop the Octopus service.

  1. Restore the database, by using the database back up you completed prior to installing the new version you were upgrading to.

Any data that has been created from between when the backup was taken to when it was restored will be lost. You should always use the most recent backup, or rolling forward may be a better solution if the backup is old.

  1. Download the previous version of the Octopus installer, from our Previous releases page.

  1. Install the previous version you are rolling back to, over the top of the installation you are rolling back from.

There is no need to uninstall the newer version you were trying to upgrade to.

  1. Turn Maintenance Mode OFF.


In a few cases a bug in a 3rd party component causes the installer displays a "Installation directory must be on a local hard drive" error. If this occurs, running the install again from an elevated command prompt using the following command (replacing Octopus.3.3.4-x64.msi with the name of the installer you are using):

msiexec /i Octopus.3.3.4-x64.msi WIXUI_DONTVALIDATEPATH="1"