Skip to content

Commit

Permalink
Merge pull request #2053 from OctopusDeploy/sf/upgrade-noise
Browse files Browse the repository at this point in the history 
Reduce noise in search from legacy upgrades
  • Loading branch information
@steve-fenton-octopus
steve-fenton-octopus authored Oct 24, 2023
2 parents 260cde8 + 344be31 commit af6d0e6
Show file tree
Hide file tree
Showing 21 changed files with 555 additions and 513 deletions.
33 changes: 25 additions & 8 deletions dictionary-octopus.txt
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,34 @@
apikey
astro
runbook
runbooks
deallocate
deallocated
DONTVALIDATEPATH
FIPS
HKEY
HKLM
hotfix
hotfixes
HSTS
ITSM
FIPS
maxage
msiexec
MTTR
nologs
NTLM
Octo
octobak
octopusid
OIDC
HSTS
MTTR
swaggerui
apikey
onlylogs
reprioritize
reprovisioned
reprovisioning
xmark
runbook
runbooks
Schannel
sthumb
swaggerui
systemprofile
upgradelog
WIXUI
xmark
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"img": "node --no-experimental-fetch ./src/themes/accelerator/utilities/img.mjs",
"dev": "node --no-experimental-fetch ./src/themes/accelerator/utilities/img.mjs && astro dev",
"test": "astro build && npx playwright install --with-deps && npx playwright test",
"spellcheck": "git fetch origin main:refs/remotes/origin/main && git diff origin/main --name-only | cspell --file-list stdin",
"spellcheck": "git fetch origin main:refs/remotes/origin/main && git diff origin/main --name-only --diff-filter=ACMRTUXB | cspell --file-list stdin",
"build": "astro build",
"preview": "astro preview",
"astro": "astro",
Expand Down
14 changes: 7 additions & 7 deletions src/pages/docs/administration/managing-infrastructure/service-watchdog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ navOrder: 2300

In some environment the Windows Services for Octopus Server and Tentacle may not reliably start when the server is rebooted. This typically occurs during a restart after Windows Updates have been installed.

## Why does it happen? {#ServiceWatchdog-Whydoesithappen?}
## Why does it happen? {#ServiceWatchdog-WhyDoesItHappen?}

The exact cause of this issue has not yet been determined, however investigation indicates that it may be related to a delay caused by slow initialization of the .NET CLR during these restarts.

## What can you do about it? {#ServiceWatchdog-Whatcanyoudoaboutit?}
## What can you do about it? {#ServiceWatchdog-WhatCanYouDoAboutIt?}

The **watchdog** command can be used on the command line to configure a Windows Scheduled Task that ensures the services are running. The command is used as follows.

### Configure the watchdog {#ServiceWatchdog-ConfiguringtheWatchdog}
### Configure the watchdog {#ServiceWatchdog-ConfiguringTheWatchdog}

```powershell
Tentacle.exe watchdog --create --instances * --interval 10
Expand All @@ -41,7 +41,7 @@ Tentacle.exe watchdog --create --instances Tentacle --interval 10
```
:::

### Cancel the watchdog {#ServiceWatchdog-CancelingtheWatchdog}
### Cancel the watchdog {#ServiceWatchdog-CancelingTheWatchdog}

```powershell
Tentacle.exe watchdog --delete
Expand All @@ -55,7 +55,7 @@ If you have scheduled the watchdog to monitor all instances on a server but you
:::

###
Recreating the Watchdog {#ServiceWatchdog-RecreatingtheWatchdog}
Recreating the Watchdog {#ServiceWatchdog-RecreatingTheWatchdog}

As mentioned above, running create again can be used to change the instances and interval for the watchdog, but all other settings will remain unchanged. If you do want to reset all of the other settings you can easily combine the delete and create, for example

Expand All @@ -73,7 +73,7 @@ The default log file location is therefore **C:\Windows\System32\config\systempr

This is only for information related to which instances the watchdog attempted to start, and any errors it received while trying to start the windows services. Any instance specific errors will still be located in the instance's log file.

### Tentacle vs Octopus Server {#ServiceWatchdog-TentaclevsOctopusServer}
### Tentacle vs Octopus Server {#ServiceWatchdog-TentacleVsOctopusServer}

The above commands work equally for Octopus Server and Tentacle (by using **Octopus.Server.exe** instead of **Tentacle.exe**). Noting that the Tentacle Watchdog will only check Tentacle instances and the Octopus Server Watchdog will only check server instances. They can both be configured simultaneously on the same machine.

Expand All @@ -85,7 +85,7 @@ Octopus.Server.exe watchdog --create --instances OctopusServer --interval 10
```
:::

## Installation locations {#ServiceWatchdog-Installationlocations}
## Installation locations {#ServiceWatchdog-InstallationLocations}

Please note that the task created by the watchdog references the Octopus Server/Tentacle executable from the location it was in when the watchdog command was executed.

Expand Down
270 changes: 6 additions & 264 deletions ...es/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,265 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2023-10-04
title: Upgrading from Octopus 3.x to the latest version
description: Information on how to upgrade from Octopus Deploy 3.x to the latest version
navOrder: 6
---
import OctopusBackupMasterKey from 'src/shared-content/upgrade/upgrade-octopus-backup-master-key.include.md';
import UpgradeDownloadLatestVersion from 'src/shared-content/upgrade/upgrade-download-latest-version.include.md';
import UpgradeOctopusBackupDatabase from 'src/shared-content/upgrade/upgrade-octopus-backup-database.include.md';
import UpgradeInplaceUpgrade from 'src/shared-content/upgrade/upgrade-inplace-upgrade.include.md';
import UpgradeTestingUpgradedInstance from 'src/shared-content/upgrade/upgrade-testing-upgraded-instance.include.md';
import UpgradeHighAvailability from 'src/shared-content/upgrade/upgrade-high-availability.include.md';
import UpgradeRestoreBackup from 'src/shared-content/upgrade/upgrade-restore-backup.include.md';
import UpgradeFindPreviousVersion from 'src/shared-content/upgrade/upgrade-find-previous-version.include.md';
import UpgradeRollbackFolders from 'src/shared-content/upgrade/upgrade-rollback-folders.include.md';
import UpgradeDownloadSameVersion from 'src/shared-content/upgrade/upgrade-download-same-version.include.md';
import UpgradeInstallClonedVersion from 'src/shared-content/upgrade/upgrade-install-cloned-version.include.md';
import UpgradeCopyFilesForClonedInstance from 'src/shared-content/upgrade/upgrade-copy-files-for-cloned-instance.include.md';
import UpgradeMigratingInstances from 'src/shared-content/upgrade/upgrade-migrating-instances.include.md';
import UpgradeOctopusBackupFolders from 'src/shared-content/upgrade/upgrade-octopus-backup-folders.include.md';
import UpgradeMainInstanceAfterTestInstance from 'src/shared-content/upgrade/upgrade-main-instance-after-test-instance.include.md';
import UpgradeInstallTestVersion from 'src/shared-content/upgrade/upgrade-install-test-version.include.md';
import UpgradeExportImportTestProjects from 'src/shared-content/upgrade/upgrade-export-import-test-projects.include.md';

You should be safe doing an in-place upgrade of 3.x to the latest version of Octopus Deploy. With that said, the last version of 3.x, 3.17.14, was released on November 12th, 2017. Fundamentally, Octopus is almost an entirely different product. We did our best to maintain backward compatibility, but there is a risk a hyper-specific scenario was missed or a breaking change was introduced. Here is an example of changes made to Octopus Deploy since 3.17.14 was released.

- The majority of endpoints in the API can accept a `Space-Id`, for example `/api/Spaces-1/projects?skip=0&take=100` whereas before it was `/api/projects?skip=0&take=100`. If a `Space-Id` isn't supplied, the default space is used.
- Teams can be assigned to multiple roles and spaces. Before, a team could be assigned to only one role.
- Unique internal package feed per space. Each space has a subfolder in the `Packages` directory to keep them segregated on the file system. Before, a package would be located at `C:\Octopus\packages\MyPackage.2020.1.1.zip`. Now it is `C:\Octopus\packages\Spaces-1\MyPackage.2020.1.1.zip`
- Almost every table in the database had a `Space-Id` column added to it.
- Workers were introduced.
- Azure Management APIs were deprecated.
- Support for Kubernetes was introduced.
- Terraform support was introduced.
- Raised the [minimum requirements for hosting and using Octopus Server](https://octopus.com/blog/raising-minimum-requirements-for-octopus-server) (both Windows and SQL Server).
- Execution containers running on docker on workers were introduced.

## Prep work

Before starting the upgrade, it is critical to back up the master key and license key. If anything goes wrong, you might need these keys to do a restore. It is better to have the backup and not need it than need the backup and not have it. The master key doesn't change, while your license key changes, at most, once a year. Back them up once to a secure location and move onto the next steps.

1. Backup the Master Key.
1. Backup the License Key.

<OctopusBackupMasterKey />

## Standard upgrade process

The standard upgrade process is an in-place upgrade. In-place upgrades update the binaries in the install directory and update the database. The guide below includes additional steps to backup key components to make it easier to rollback in the unlikely event of a failure.

:::div{.problem}

While an in-place upgrade will work, it involves risk as you are upgrading from a version released back in 2017 (or earlier). Please see the risk mitigation sections below for steps on how to mitigate that risk.
:::

### Overview

The steps for this are:

1. Download the latest version of Octopus Deploy.
1. Enable maintenance mode.
1. Backup the database.
1. Do an in-place upgrade.
1. Test the upgraded instance.
1. Disable maintenance mode.

<UpgradeDownloadLatestVersion />

<UpgradeOctopusBackupDatabase />

<UpgradeInplaceUpgrade />

<UpgradeTestingUpgradedInstance />

<UpgradeHighAvailability />

## Risk mitigation recommended approach - create a cloned instance

The recommended approach to risk mitigation is to create a cloned instance, upgrade that instance, and test out the new functionality with any integrations. From there, you can migrate over to the cloned instance or do an in-place upgrade of your existing instance and use the cloned instance to test future upgrades. This provides the means to test an upgrade without affecting your CI/CD pipeline.

### Overview

Creating a clone of an existing instance involves:

1. Enable maintenance mode on the main instance.
1. Backup the database of the main instance.
1. Disable maintenance mode on the main instance.
1. Restore the backup of the main instance's database as a new database on the desired SQL Server.
1. Download the same version of Octopus Deploy as your main instance.
1. Installing that version on a new server and configure it to point to the **cloned/restored** database.
1. Copying all the files from the backed up folders from the source instance.
1. Optional: Disable all deployment targets.
1. Upgrade cloned instance.
1. Test cloned instance. Verify all API scripts, CI integrations, and deployments work.
1. If migrating, then migrate over. Otherwise, leave the test instance alone, backup the folders and database, and upgrade the main instance.

<UpgradeOctopusBackupDatabase />

<UpgradeRestoreBackup />

<UpgradeDownloadSameVersion />

<UpgradeInstallClonedVersion />

<UpgradeCopyFilesForClonedInstance />

### Disabling All Targets/Workers/Triggers/Subscriptions - Optional

Cloning an instance includes cloning all certificates. Assuming you are not using polling Tentacles, all the deployments will "just work." That is by design if the VM hosting Octopus Deploy is lost and you have to restore Octopus Deploy from a backup.

Just working does have a downside, as you might have triggers, auto release creation, and other items configured. These items could potentially perform deployments. You can run this SQL Script on your cloned instance to disable everything.

```sql
Use [OctopusDeploy]
go
DELETE FROM OctopusServerNode
IF EXISTS (SELECT null FROM sys.tables WHERE name = 'OctopusServerNodeStatus')
DELETE FROM OctopusServerNodeStatus
UPDATE Subscription SET IsDisabled = 1
UPDATE Machine SET IsDisabled = 1
IF EXISTS (SELECT null FROM sys.tables WHERE name = 'Worker')
UPDATE Worker SET IsDisabled = 1
DELETE FROM ExtensionConfiguration WHERE Id in ('authentication-octopusid', 'jira-integration')
```
:::div{.hint}
Remember to replace `OctopusDeploy` with the name of your database.
:::

<UpgradeInplaceUpgrade />

<UpgradeTestingUpgradedInstance />

<UpgradeMigratingInstances />

<UpgradeOctopusBackupFolders />

<UpgradeMainInstanceAfterTestInstance />

## Risk mitigation alternative approach - create a test instance

Creating and migrating to a cloned instance can be quite a bit of work. You have to worry about drift and getting new compute resources allocated. An alternative approach to the cloned instance is creating a test instance with only a handful of projects. Test the upgrade with that test instance and then do the upgrade of your main instance.

### Overview

The steps for this are:

1. Download the same version of Octopus Deploy as your main instance.
1. Install Octopus Deploy on a new VM.
1. Export a subset of projects from the main instance.
1. Import that subset of projects to the test instance.
1. Download the latest version of Octopus Deploy.
1. Backup the test instance database.
1. Upgrade that test instance to the latest version of Octopus Deploy.
1. Test and verify the test instance.
1. Enable maintenance mode on the main instance.
1. Backup the database on the main instance.
1. Backup all the folders on the main instance.
1. Do an in-place upgrade of your main instance.
1. Test the upgraded main instance.
1. Disable maintenance mode.

<UpgradeDownloadSameVersion />

<UpgradeInstallTestVersion />

<UpgradeExportImportTestProjects />

<UpgradeDownloadLatestVersion />

<UpgradeOctopusBackupDatabase />

<UpgradeInplaceUpgrade />

<UpgradeTestingUpgradedInstance />

<UpgradeOctopusBackupDatabase />

<UpgradeOctopusBackupFolders />

<UpgradeMainInstanceAfterTestInstance />

<UpgradeHighAvailability />

## Rollback failed upgrade

While unlikely, an upgrade may fail. It could fail on a database upgrade script, SQL Server version is no longer supported, license check validation, or plain old bad luck. Depending on what failed, you have a decision to make. If the cloned instance upgrade failed, it might make sense to start all over again. Or, it might make sense to roll back to a previous version. In either case, if you decide to roll back, the process will be:

1. Restore the database backup.
1. Restore the folders.
1. Download and install the previously installed version of Octopus Deploy.
1. Do some sanity checks.
1. If maintenance mode is enabled, disable it.

<UpgradeRestoreBackup />

<UpgradeRollbackFolders />

<UpgradeFindPreviousVersion />

## Additional items to note

Earlier versions of 3.x, including 3.1, 3.4, and 3.5, also carry some additional caveats to make a note of. Before upgrading to a modern version of Octopus Deploy, please keep these in mind.

### Upgrading to Octopus 3.1 or greater \{#UpgradingfromOctopus3.x-UpgradingTo31UpgradingtoOctopus3.1orgreater}

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

:::div{.success}
**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 modern version of Octopus Server 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 Calamari's latest version 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](https://msdn.microsoft.com/en-us/library/8z6watww%28v=vs.110%29.aspx). 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 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 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.

:::div{.hint}
**Tentacle communications protocol**
Read more about the [Octopus - Tentacle communication](/docs/security/octopus-tentacle-communication/) protocol and [Troubleshooting Schannel and TLS](/docs/security/octopus-tentacle-communication/troubleshooting-schannel-and-tls).
:::

### Upgrading to Octopus 3.4 or greater \{#UpgradingfromOctopus3.x-UpgradingtoOctopus3.4orgreater}

See the [Release Notes](https://octopus.com/downloads/compare?from=3.3.27&amp;to=3.4.0) 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](https://teamcity-support.jetbrains.com/hc/en-us/community/posts/206817105-How-to-enable-NuGet-feed-v2). **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](/docs/packaging-applications/package-repositories).

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

### Upgrading to Octopus 3.5 or greater \{#UpgradingfromOctopus3.x-UpgradingtoOctopus3.5orgreater}

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 the Octopus Server.

## Troubleshooting \{#UpgradingfromOctopus3.x-Troubleshooting}

In a few cases, a bug in a 3rd party component causes the installer to display 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"
```
layout: src/layouts/Redirect.astro
title: Redirect
redirect: /docs/administration/upgrading/legacy/upgrading-from-octopus-3.x-to-modern
navMenu: false
pubDate: 2023-10-24
---
Loading

0 comments on commit af6d0e6

Please sign in to comment.