Docs
Free trial

In place upgrade (Install Over 2.6.5)

You can perform an in place upgrade from Octopus 2.6.5 to Octopus 2018.10 LTS, but you need to upgrade your Tentacles first.

Due to the new communication method, you won’t be able to communicate with your upgraded Tentacles until you upgrade your server. However, if you upgrade your server before all Tentacles are correctly updated, you will have to upgrade them manually, or roll your server back to Octopus 2.6.5 and try again.

Step by step

To perform an in-place upgrade, follow these steps carefully:

1. Back up your Octopus 2.6.5 database and Master Key

See the Backup and restore page for instructions on backing up your database.

2. Use Hydra to automatically upgrade your Tentacles

Hydra is a tool we’ve built that will help you update your Tentacles to the latest version. It is particularly useful migrating from 2.6.5 to 2018.10 LTS as the communication methods have changed.

This is the point of no return. When your Tentacles are upgraded to 3.x your 2.6.5 server will not be able to communicate with them.

We strongly recommend testing Hydra against a small subset of “canary” machines before upgrading the rest of your machines. The best way to do this is:

  1. Create a new “canary” machine role and assign it to a few machines.
  2. Set the Update Octopus Tentacle step to run on machines with the “canary” role.
  3. Once you are confident the Tentacle upgrade works as expected, you can use Hydra to upgrade all of the remaining machines.

How does Hydra work?

Hydra consists of two parts:

  1. A package that contains the latest Tentacle MSI installers.
  2. An Octopus 2.6.5 step template that does the upgrade to your environments.

To account for issues with communicating with a Tentacle that has been ‘cut off’ from its Octopus Server, the Hydra process connects to the Tentacle and creates a scheduled task on the Tentacle Machine. If it is able to schedule the task it considers that install a success. The task runs one minute later.

The scheduled task does the following:

  1. Find Tentacle services.
  2. Stop all Tentacles (if they’re running).
  3. Run MSI.
  4. Update configs for any polling Tentacles.
  5. Starts any Tentacles that were running when we started.

With just one Tentacle service this should be a very quick process, but we cannot estimate how long it may take with many Tentacle services running on the one machine.

Common problems using Hydra

The scheduled task is set to run as SYSTEM to ensure the MSI installation will succeed. If your Tentacles are running with restricted permissions, they may not be able to create this scheduled task. The only option is to upgrade your Tentacles manually.

Hydra performs a Reinstall of each Tentacle. As part of the reinstall, the Service Account is reset to Local System. If you need your Tentacles to run under a different account, you will have to make the change after the upgrade completes (after you’ve re-established a connection from 2018.10 LTS). You can do this manually, or using the following script:

Tentacle.exe service --instance "Tentacle" --reconfigure --username=DOMAIN\ACCOUNT --password=your-password --start --console

Let’s upgrade these Tentacles!

To use Hydra, follow these steps:

These steps should be executed from your Octopus 2.6.5 server to your 2.6 Tentacles.

  1. Download the latest Hydra NuGet package from https://octopus.com/downloads/latest/Hydra.
  2. Use the Upload Package feature of the library to upload the OctopusDeploy. Hydra package to the built-in NuGet repository on your Octopus 2.6.5 server.

  1. Import the Hydra step template from the Community Library.

  1. Create a new project with a single “Update Octopus Tentacle” step from the step template.

  2. Ensure you choose or create a Lifecycle that allows you to deploy to all Tentacles.

  3. Ensure you set the Update Octopus Tentacle step to run for all appropriate Tentacles.

  4. Set the Server Mapping field:

  • If you only use listening Tentacles you can leave the Server Mapping field blank.
  • If you are using any polling Tentacles, add the new Octopus 2018.10 LTS server address (including the polling TCP port) in the Server Mapping field. See below for examples.

Server mapping for Polling Tentacles

It is very important you get this value correct. An incorrect value will result in a polling Tentacle that can’t be contacted by neither a 2.6.5 or 2018.10 LTS server. Several different scenarios are supported:

  1. A single Polling Tentacle instance on a machine pointing to a single Octopus Server the most common case:
  • Just point to the new server’s polling address https://newserver:newport like https://octopus3.mycompany.com:10934
  1. Multiple Polling Tentacle instances on the same machine pointing to a single Octopus Server:
  • Just point to the new server’s polling address https://newserver:newport like https://octopus3.mycompany.com:10934 and Hydra will automatically update all Tentacles to point to the new server’s address
  1. Multiple Polling Tentacle instances on the same machine pointing to different Octopus Servers a very rare case:
  • Use this syntax to tell Hydra the mapping from your old Octopus Server to your new Octopus Server: https://oldserver:oldport=>https://newserver:newport,https://oldserver2:oldport2/=>https://newserver2:newport2 where each pair is separated by commas. This will match the first case and replace it => with the second case.

Click the help button for more detailed instructions.

:::

  1. Create a release and deploy. The deployment should succeed, and one minute later the Tentacles will be upgraded.

3. Verify the upgrade worked

When the Hydra task runs on a Tentacle machine, it should no longer be able to communicate with the Octopus 2.6.5 server. You can verify this by navigating to the Environments page and clicking Check Health.

After successfully updating your Tentacles, you should see this check fail from your 2.6.5 server.

We recommend connecting to some of your Tentacle machines and examining the Octopus Tentacle binaries to ensure they have been upgraded. You should also ensure the service is running (even though it will not be able to communicate with the server).

If you have multiple Tentacles running on the same server, an update to one will result in an update to all of them. This is because there is only one copy of the Tentacle binaries, even with multiple instances configured.

4. Install Octopus 2018.10 LTS on your Octopus Server

Upgrade to the latest version When upgrading to Octopus 2018.10 LTS please use the latest version available. We have been constantly improving the Octopus 2.6.5 to Octopus 2018.10 LTS data migration process whilst adding new features and fixing bugs.

See the Installing Octopus 2018.10 LTS page for instructions on installing a new Octopus 2018.10 LTS instance.

After installing the MSI, you will be presented with an upgrade page.

Click “Get started…” and set up your database connection. You may need to grant permission to the NT AUTHORITY\SYSTEM account at this stage.

Click Next, and then Install to install the Octopus 2018.10 LTS server over the Octopus 2.6.5 instance.

5. Restore the Octopus 2.6.5 database using the Migration Tool

After upgrading, the Octopus Manager will prompt to import your Octopus 2.6.5 database. Click the Import data… button and follow the prompts to import your Octopus 2.6.5 data.

See the Migrating data from Octopus 2.6.5 to 2018.10 LTS page for more detailed instructions on importing your Octopus 2.6.5 database backup into Octopus 2018.10 LTS.

Migration taking a long time? By default we migrate everything from your backup including historical data. You can use the maxage= argument when executing the migrator to limit the number of days to keep. For example: maxage=90 will keep 90 days of historical data ignoring anything older.

To see the command syntax click the Show script link in the wizard.

Using the built-in Octopus NuGet repository? If you use the built-in Octopus NuGet repository you will need to move the files from your Octopus 2.6.5 server to your Octopus 2018.10 LTS server. They are not part of the backup. In a standard Octopus 2.6.5 install the files can be found under C:\Octopus\OctopusServer\Repository\Packages You will need to transfer them to the new server to C:\Octopus\Packages. Once the files have been copied, go to Library ➜ Packages ➜ Package Indexing and click the RE-INDEX NOW button. This process runs in the background, so if you have a lot of packages it could take a while (5-20 mins) to show in the UI or be usable for deployments.

6. Verify connectivity between the 2018.10 LTS server and your Tentacles

Log in to your new Octopus 2018.10 LTS server and run health checks on all of your environments. If the upgrade completed successfully, they should succeed.

If one or more health checks do not succeed after a few attempts, see the Troubleshooting section to identify possible issues.

Optionally clean up your Octopus home folder

We leave some files used by Octopus 2.6.5 in place so you can roll back if necessary. After the upgrade is complete these files will never be used again and can be safely deleted.

You can follow the instructions on this page to clean up files left over from your Octopus 2.6.5 to Octopus 2018.10 LTS upgrade.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023

Edit on GitHub