diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index 7169119735..fd42e90443 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -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 \ No newline at end of file +runbook +runbooks +Schannel +sthumb +swaggerui +systemprofile +upgradelog +WIXUI +xmark diff --git a/package.json b/package.json index 970e3e7f95..de5bd4277a 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/src/pages/docs/administration/managing-infrastructure/service-watchdog.md b/src/pages/docs/administration/managing-infrastructure/service-watchdog.md index 7503186234..0c96306e33 100644 --- a/src/pages/docs/administration/managing-infrastructure/service-watchdog.md +++ b/src/pages/docs/administration/managing-infrastructure/service-watchdog.md @@ -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 @@ -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 @@ -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 @@ -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. @@ -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. diff --git a/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern.mdx b/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern.mdx index dcd86b2127..a5e15213c2 100644 --- a/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern.mdx +++ b/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern.mdx @@ -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. - - - -## 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. - - - - - - - - - - - -## 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. - - - - - - - - - - - -### 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. -::: - - - - - - - - - - - -## 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. - - - - - - - - - - - - - - - - - - - - - - - -## 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. - - - - - - - -## 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&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 +--- \ No newline at end of file diff --git a/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern.mdx b/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern.mdx index 613e4a386e..607335cdc6 100644 --- a/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern.mdx +++ b/src/pages/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern.mdx @@ -1,177 +1,6 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2023-10-04 -title: Upgrading from Octopus 4.x / 2018.x to latest version -description: Information on how to upgrade from Octopus Deploy 4.x or 2018.x to the latest version -navOrder: 5 ---- -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 UpgradeDisableTargetsClonedInstance from 'src/shared-content/upgrade/upgrade-disable-targets-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'; - -It is generally safe to do an in-place upgrade from Octopus Deploy 4.x/2018.x to the latest version. Please keep in mind, 4.x/2018.x did not include the Spaces feature. Spaces made the following changes: - -- 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. - -The upgrade should work without error, but there are integration concerns to consider. This guide will step through the steps to mitigate those concerns. - -## 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. - - - -## 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 2018. 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. - - - - - - - - - - - -## Risk mitigation recommended approach - create a test instance - -An in-place upgrade should be the safest approach. Upgrade scripts assume you are upgrading from older versions of Octopus Deploy. While the upgrade will work, there might be a new feature or breaking changes you will want to test first. The recommended approach is to create a test instance containing a subset of projects representing your main instance. Upgrade that test instance, verify it, and then upgrade the 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 upgraded main instance. -1. Disable maintenance mode. - - - - - - - - - - - - - - - - - - - - - -## Risk mitigation alternative approach - create a cloned instance - -An alternative approach to an in-place upgrade is to create a cloned instance and upgrade that. 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 for testing future upgrades. - -### 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. - - - - - - - - - - - - - - - - - - - - - - - - - -## 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. - - - - - - \ No newline at end of file +layout: src/layouts/Redirect.astro +title: Redirect +redirect: /docs/administration/upgrading/legacy/upgrading-from-octopus-4.x-2018.x-to-modern +navMenu: false +pubDate: 2023-10-24 +--- \ No newline at end of file diff --git a/src/pages/docs/administration/upgrading/guide/upgrading-major-releases.mdx b/src/pages/docs/administration/upgrading/guide/upgrading-major-releases.mdx index f259a8670b..b418412c70 100644 --- a/src/pages/docs/administration/upgrading/guide/upgrading-major-releases.mdx +++ b/src/pages/docs/administration/upgrading/guide/upgrading-major-releases.mdx @@ -9,7 +9,7 @@ navOrder: 3 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 UpgradeInPlaceUpgrade from 'src/shared-content/upgrade/upgrade-in-place-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'; @@ -64,7 +64,7 @@ The steps for this are: - + diff --git a/src/pages/docs/administration/upgrading/guide/upgrading-minor-and-patch-releases.mdx b/src/pages/docs/administration/upgrading/guide/upgrading-minor-and-patch-releases.mdx index 4d09fc87dd..0f78565a64 100644 --- a/src/pages/docs/administration/upgrading/guide/upgrading-minor-and-patch-releases.mdx +++ b/src/pages/docs/administration/upgrading/guide/upgrading-minor-and-patch-releases.mdx @@ -9,7 +9,7 @@ navOrder: 2 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 UpgradeInPlaceUpgrade from 'src/shared-content/upgrade/upgrade-in-place-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'; @@ -45,7 +45,7 @@ The steps for this are: - + diff --git a/src/pages/docs/administration/upgrading/index.mdx b/src/pages/docs/administration/upgrading/index.mdx index f9df15e6c8..531bf70f77 100644 --- a/src/pages/docs/administration/upgrading/index.mdx +++ b/src/pages/docs/administration/upgrading/index.mdx @@ -36,7 +36,7 @@ Once the **Octopus Manager** starts the upgrade process, downtime _will_ occur. **Upgrades and the Service Watchdog** -If you are using the [Service Watchdog](/docs/administration/managing-infrastructure/service-watchdog), you will need to cancel it before you start your upgrade and recreate it after the upgrade is finished. Documentation on canceling the watchdog can be found [here](/docs/administration/managing-infrastructure/service-watchdog/#ServiceWatchdog-CancelingtheWatchdog). +If you are using the [Service Watchdog](/docs/administration/managing-infrastructure/service-watchdog), you will need to cancel it before you start your upgrade and recreate it after the upgrade is finished. Documentation on canceling the watchdog can be found [here](/docs/administration/managing-infrastructure/service-watchdog/#ServiceWatchdog-CancelingTheWatchdog). ### Upgrading a highly available Octopus Deploy instance @@ -59,7 +59,7 @@ The Windows Service is split across multiple folders to make upgrading easy and - **SQL Server Database**: Since `Octopus Deploy 3.x`, the back-end database has been SQL Server. Each update can contain 0 to N database scripts embedded in a .dll in the install location. The **Octopus Manager** invokes those database scripts automatically. - **Home Folder**: The home folder stores configuration, logs, and other items unique to your instance. The home folder is separate from the install location to make it easier to upgrade, downgrade, uninstall/reinstall without affecting your instance. The default location of the home folder is `C:\Octopus`. Except in rare cases, this folder is left unchanged by the upgrade process. - **Instance Information**: The Octopus Deploy Manager allows you to configure 1 to N instances per Windows Server. The **Octopus Manager** stores a list of all the instances in the `C:\ProgramData\Octopus\OctopusServer\Instances` folder. Except in rare cases, this folder is left unchanged by the upgrade process. -- **Server Folders**: Logs, artifacts, packages, and event exports are too big for Octopus Deploy to store in a SQL Server database. The server folders are subfolders in `C:\Octopus\`. Except in rare cases, these folders are left unchanged by an upgrade. +- **Server Folders**: Logs, artifacts, packages, and event exports are too big for Octopus Deploy to store in a SQL Server database. The server folders are sub-folders in `C:\Octopus\`. Except in rare cases, these folders are left unchanged by an upgrade. - **Tentacles**: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until _after_ the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work [with any modern version of Octopus Deploy](/docs/support/compatibility). We recommend you upgrade them to get the latest bug fixes and security patches when convenient. - **Calamari**: The Tentacles facilitate communication between Octopus Deploy and the deployment targets. Calamari is the software that does the actual deployments. Calamari and Octopus Deploy are coupled together. Calamari is upgraded automatically during the first deployment to a target. @@ -67,7 +67,7 @@ The Windows Service is split across multiple folders to make upgrading easy and -## How we version Octopus Deploy \{#Upgrading-HowweversionOctopusDeploy} +## How we version Octopus Deploy We use our version numbering scheme to help you understand the type of changes we have introduced between two versions of Octopus Deploy: @@ -91,14 +91,14 @@ If you're interested in more details about versioning Octopus, check out the blo ## Scenarios -Please pick from one of these upgrade scenarios. Any version 3.x or higher is considered modern; any version before that is considered legacy. +Please pick from one of these upgrade scenarios: - [Upgrading minor and patch releases](/docs/administration/upgrading/guide/upgrading-minor-and-patch-releases) - [Upgrading major releases](/docs/administration/upgrading/guide/upgrading-major-releases) -- [Upgrading from Octopus 4.x or 2018.x to latest version](/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern) -- [Upgrading from Octopus 3.x to latest version](/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern) - [Upgrading host OS or .NET version](/docs/administration/upgrading/guide/upgrade-host-os-or-net) - Legacy Upgrades + - [Upgrading from Octopus 4.x or 2018.x to latest version](/docs/administration/upgrading/guide/upgrading-from-octopus-4.x-2018.x-to-modern) + - [Upgrading from Octopus 3.x to latest version](/docs/administration/upgrading/guide/upgrading-from-octopus-3.x-to-modern) - [Upgrade from 2.6.5 to 2018.10.x](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts) - [Upgrade from 2.x to 2.6.5](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.x-2.6.5) - [Upgrade from 1.6 to 2.6.5](/docs/administration/upgrading/legacy/upgrading-from-octopus-1.6-2.6.5) diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-1.6-2.6.5.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-1.6-2.6.5.md index fe8a535bfe..736c59f96f 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-1.6-2.6.5.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-1.6-2.6.5.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Upgrading from Octopus 1.6 to 2.6.5 description: Information on how to upgrade from Octopus 1.6 tp 2.6.5. navOrder: 2 +navSearch: false --- :::div{.success} @@ -13,7 +14,7 @@ Please read our guide for [upgrading older versions of Octopus](/docs/administra A **lot** changed between **Octopus 1.6** and **Octopus 2.0**; so much that we had to to handle upgrades differently to the way we handle upgrades from, say, **Octopus 1.5** to **Octopus 1.6**. This page will walk you through the process of upgrading an **Octopus 1.6** instance to **Octopus 2.0**. Rather than being an in-place upgrade, **Octopus 2.0** is designed to be a **side-by-side** upgrade. -## Preparing {#UpgradingfromOctopus1.6-Preparing} +## Preparing :::div{.problem} @@ -34,7 +35,7 @@ Then go to the **Storage** tab in the **Configuration** area, and make sure that ![](/docs/administration/upgrading/legacy/images/3277999.png) ::: -## Install Octopus 2.0 {#UpgradingfromOctopus1.6-InstallOctopus2.0} +## Install Octopus 2.0 Next, install **Octopus 2.0**, either on the same server as your current **Octopus 1.6** server, or on a new server (ideal). **Octopus 2.0** uses different paths, ports and service names to **Octopus 1.0** so there should not be any conflicts between them. @@ -42,7 +43,7 @@ Next, install **Octopus 2.0**, either on the same server as your current **Octop View our [guide to installing an Octopus 2.0](/docs/installation), which includes a video walk-through. ::: -## Importing {#UpgradingfromOctopus1.6-Importing} +## Importing On the **Octopus 2.0** server, open the Octopus Manager from your start menu/start screen. @@ -86,11 +87,11 @@ At this point, you should be able to view the imported projects, environments an ![](/docs/administration/upgrading/legacy/images/3277992.png) ::: -## Permissions {#UpgradingfromOctopus1.6-Permissions} +## Permissions The **Octopus 2.x** migrator will not import permission settings from **Octopus 1.6**, due to changes made between the permission models. After you upgrade to **Octopus 2.x**, you will need to configure [Teams](/docs/security/users-and-teams) to assign permissions. -## Upgrading Tentacles {#UpgradingfromOctopus1.6-UpgradingTentacles} +## Upgrading Tentacles **Octopus 2.x** changed the communication stack between Octopus and Tentacle, meaning that your **Octopus 2.x** server can no longer communicate with **Tentacle 1.6**. So in addition to upgrading Octopus, you'll also need to upgrade any Tentacles. @@ -112,7 +113,7 @@ function Upgrade-Tentacle ($rel, $loc, $hm, $sthumb, $sxsPort) $downloader.DownloadFile("http://download.octopus.com/octopus/Octopus.Tentacle.$rel.msi", [System.IO.Path]::GetFullPath(".\Tentacle.msi")) Write-Output "Installing MSI" - $msiExitCode = (Start-Process -FilePath "msiexec.exe" -ArgumentList "/i Tentacle.msi /quiet" -Wait -Passthru).ExitCode + $msiExitCode = (Start-Process -FilePath "msiexec.exe" -ArgumentList "/i Tentacle.msi /quiet" -Wait -PassThru).ExitCode Write-Output "Tentacle MSI installer returned exit code $msiExitCode" if ($msiExitCode -ne 0) { throw "Installation aborted" diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6.md index f5a30cfa44..57e0c97056 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6.md @@ -4,6 +4,7 @@ pubDate: 2023-01-01 modDate: 2023-01-01 title: Backup v2.6 database description: Information on how to backup an Octopus 2.6 database. +navSearch: false --- All of the data and settings managed by Octopus - the projects, environments, deployments and so on - are stored in an embedded database hosted by the Octopus Server. Out of the box, Octopus automatically creates backups of this database and any other files necessary to restore the Octopus instance every four hours. The backup files are copied to a local directory: you can easily change this to use a file share or other path that is backed up externally. diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/in-place-upgrade-install-over-2.6.5.mdx b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/in-place-upgrade-install-over-2.6.5.mdx index 36cd5b9bf3..52a7ea84fe 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/in-place-upgrade-install-over-2.6.5.mdx +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/in-place-upgrade-install-over-2.6.5.mdx @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: In place upgrade (Install Over 2.6.5) description: Information on how to do an in-place upgrade to Octopus 2018.10 LTS from Octopus 2.6.5. navOrder: 0 +navSearch: false --- import UsingHydra from 'src/shared-content/using-hydra.include.md'; @@ -12,19 +13,19 @@ You can perform an in place upgrade from **Octopus 2.6.5** to **Octopus 2018.10 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 \{#Inplaceupgrade(installover2.6)-Stepbystep} +## 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 \{#Inplaceupgrade(installover2.6)-1.BackupyourOctopus2.6databaseandmasterkey} +### 1. Back up your Octopus 2.6.5 database and Master Key See the [Backup and restore](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6/)[ page for instructions on backing up your database.](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6) -### 2. Use Hydra to automatically upgrade your Tentacles \{#Inplaceupgrade(installover2.6)-2.UseHydratoautomaticallyupgradeyourTentacles} +### 2. Use Hydra to automatically upgrade your Tentacles -### 3. Verify the upgrade worked \{#Inplaceupgrade(installover2.6)-3.Verifytheupgradehasworked} +### 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**. @@ -44,7 +45,7 @@ We recommend connecting to some of your Tentacle machines and examining the Octo 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 \{#Inplaceupgrade(installover2.6)-4.InstallOctopus3.xonyourOctopusServer} +### 4. Install Octopus 2018.10 LTS on your Octopus Server :::div{.success} **Upgrade to the latest version** @@ -71,7 +72,7 @@ Click Next, and then Install to install the **Octopus 2018.10 LTS** server over ![](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/images/3278006.png "width=500") ::: -### 5. Restore the Octopus 2.6.5 database using the Migration Tool \{#Inplaceupgrade(installover2.6)-5.RestoretheOctopus2.6databaseusingthemigrationtool} +### 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. @@ -95,7 +96,7 @@ In a standard **Octopus 2.6.5** install the files can be found under `C:\Octopus 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 \{#Inplaceupgrade(installover2.6)-6.Verifyconnectivitybetweenthe3.xserverand3.xTentacles} +### 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. @@ -109,4 +110,4 @@ If one or more health checks do not succeed after a few attempts, see the Troubl 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](/docs/administration/managing-infrastructure/server-configuration-and-file-storage\#ServerconfigurationandFilestorage-CleanUp) to clean up files left over from your **Octopus 2.6.5** to **Octopus 2018.10 LTS** upgrade. +You can follow the instructions on this [page](/docs/administration/managing-infrastructure/server-configuration-and-file-storage\#ServerConfigurationAndFileStorage-CleanUp) to clean up files left over from your **Octopus 2.6.5** to **Octopus 2018.10 LTS** upgrade. diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/index.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/index.md index 8fdc415aac..6c67f713b2 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/index.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/index.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Upgrading from Octopus 2.6.5 to 2018.10 LTS description: Information on how to upgrade from Octopus 2.6.5 to 2018.10 LTS navOrder: 3 +navSearch: false --- :::div{.success} @@ -25,13 +26,13 @@ We recommend choosing from two different approaches for upgrading from **Octopus - Create a new Octopus Server and migrate to it. We recommend this approach. - Install over the top of your existing Octopus Server. -### Approach 1: Install the new version of Octopus on a new server, and migrate to it (recommended) {#UpgradingfromOctopus2.6-Approach1-Install3.xonanewserver,andmigratetoit(recommended)} +### Approach 1: Install the new version of Octopus on a new server, and migrate to it (recommended) If you are able to provision a new Octopus Server, this is the safest option. That way, if something goes wrong in the upgrade, it will be easy to discard the new server and start the process again. And when it works, you can decommission the old Octopus Server. Read the full guide: [Upgrade with a new Server instance](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance) -### Approach 2: In-place (Over the Top) upgrade of an existing server {#UpgradingfromOctopus2.6-Approach2-In-place(overthetop)upgradeofanexistingserver} +### Approach 2: In-place (Over the Top) upgrade of an existing server It is possible to install newer versions of Octopus over the top of a **Octopus 2.6** instance. You'll upgrade the Tentacles, then upgrade the Octopus Server. @@ -49,7 +50,7 @@ If you only have a small number of Tentacles, it's easiest to just download the Read the full guide: [Manual upgrades for smaller instances](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/manual-upgrade) -### Lots of Tentacles {#UpgradingfromOctopus2.6-Largerinstallations} +### Lots of Tentacles > "I have lots of Tentacles; there's no way I'm manually updating them all!" diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/manual-upgrade.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/manual-upgrade.md index a429b03366..db8db9e200 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/manual-upgrade.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/manual-upgrade.md @@ -5,28 +5,29 @@ modDate: 2023-10-04 title: Manual upgrade description: Information on how to manually upgrade to Octopus 2018.10 LTS from Octopus 2.6.5. navOrder: 1 +navSearch: false --- You can upgrade from **Octopus 2.6.5** to **Octopus 2018.10 LTS** by downloading the latest [MSI's for both Octopus and Tentacle](https://octopus.com/download), and installing them manually. If you're working with a large number of Tentacles, see the section on [upgrading larger installations](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts). -## Summary {#Manualupgrade-Summary} +## Summary 1. Backup your **Octopus 2.6.5** database and Master Key. 2. Install **Octopus 2018.10 LTS** on your Octopus Server. 3. Migrate your data from **Octopus 2.6.5** to **Octopus 2018.10 LTS**. 4. Install **the latest version of Tentacle** on your deployment targets. 5. Verify the connectivity between the **Octopus 2018.10 LTS** Server and your Tentacles. -6. **[Optional]** Clean up your Octopus Home folder, follow the instructions on this [page](/docs/administration/managing-infrastructure/server-configuration-and-file-storage\#ServerconfigurationandFilestorage-CleanUp). +6. **[Optional]** Clean up your Octopus Home folder, follow the instructions on this [page](/docs/administration/managing-infrastructure/server-configuration-and-file-storage\#ServerConfigurationAndFileStorage-CleanUp). -## Step by step {#Manualupgrade-Stepbystep} +## Step by step To perform an in-place upgrade, follow these steps: -### 1. Back up your Octopus 2.6.5 database and Master Key {#Manualupgrade-1.BackupyourOctopus2.6databaseandmasterkey} +### 1. Back up your Octopus 2.6.5 database and Master Key See the [Backup and restore](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6/)[ page for instructions on backing up your database.](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6) -### 2. Install Octopus 2018.10 LTS on your Octopus Server {#Manualupgrade-2.InstallOctopus3.xonyourOctopusServer} +### 2. Install Octopus 2018.10 LTS on your Octopus Server :::div{.success} **Upgrade to the latest version** @@ -53,7 +54,7 @@ Click Next, and then Install to install the **Octopus 2018.10 LTS** server over ![](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/images/3278006.png) ::: -### 3. Restore the Octopus 2.6.5 database using the Migration Tool {#Manualupgrade-3.RestoretheOctopus2.6databaseusingthemigrationtool} +### 3. 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. @@ -77,13 +78,13 @@ In a standard **Octopus 2.6.5** install the files can be found under `C:\Octopus 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. ::: -### 4. Install the latest Tentacle MSI {#Manualupgrade-4.InstalltheTentacle3.xMSI} +### 4. Install the latest Tentacle MSI At this point, the machines should appear in your Environments page inside **Octopus 2018.10 LTS**, but a health check will fail - the communication protocol used by modern Octopus Servers isn't compatible with **Tentacle 2.6**. On each machine that ran **Tentacle 2.6**, connect to the machine, and install the latest Tentacle MSI. -### 5. Verify connectivity between the 2018.10 LTS server and your Tentacles {#Manualupgrade-5.Verifyconnectivitybetweenthe3.xserverand3.xTentacles} +### 5. 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. diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/migrating-data-from-octopus-2.6.5-2018.10lts.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/migrating-data-from-octopus-2.6.5-2018.10lts.md index adbdb79872..3b5d380803 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/migrating-data-from-octopus-2.6.5-2018.10lts.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/migrating-data-from-octopus-2.6.5-2018.10lts.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Migrating data from Octopus 2.6.5 to 2018.10 LTS description: Information on how to migrate your data from Octopus 2.6.5 to 2018.10 LTS. navOrder: 3 +navSearch: false --- When upgrading from **Octopus 2.6** to **Octopus 2018.10 LTS** you can migrate your data. There are some points worth noting about the data migration process: @@ -21,7 +22,7 @@ When upgrading from **Octopus 2.6** to **Octopus 2018.10 LTS** you can migrate y Please see our [tips for minimizing the migration duration](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time). ::: -## Importing your 2.6 backup into 2018.10 LTS {#MigratingdatafromOctopus2.6to3.x-Importingyour2.6Backupinto3.x} +## Importing your 2.6 backup into 2018.10 LTS To import your 2.6 Raven data into a 2018.10 LTS installation (generally this is run after a side-by-side upgrade) you need to select import from the Octopus Manager. @@ -53,12 +54,12 @@ If you need to use any of the options below to manage the data being imported yo ![](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/images/3964996.png) ::: -### Migrating the built-in Octopus NuGet package repository {#MigratingdatafromOctopus2.6to3.x-PackageRepositoryMigratingthebuilt-inOctopusNuGetpackagerepository} +### Migrating the built-in Octopus NuGet package repository If you use the built-in [Octopus NuGet repository](/docs/packaging-applications/package-repositories) you will need to move the files from your 2.6 server to your 2018.10 LTS server. The package files are not included as part of the backup. In a standard **Octopus 2.6** 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. -### Migrating historical data {#MigratingdatafromOctopus2.6to3.x-MaxAgeMigratinghistoricaldata} +### Migrating historical data By default we migrate everything from your backup including all historical data. Learn about [minimizing migration time](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time). diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time.md index 094e96d8f8..27d02ff04a 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/minimize-migration-time.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Minimize the data-migration time description: Tips to minimize the time taken to migrate your data from Octopus 2.6 to 2018.10 LTS navOrder: 5 +navSearch: false --- Migrating data from an **Octopus 2.6** backup file into an **Octopus 2018.10 LTS** instance can take a significant time to run (hours or even days in some cases). diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/troubleshooting.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/troubleshooting.md index 4f9c6110c2..56d13ae08f 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/troubleshooting.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/troubleshooting.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Troubleshooting description: Solutions to common problems when upgrading to Octopus 2018.10 LTS from Octopus 2.6. navOrder: 4 +navSearch: false --- If your upgrade from **Octopus 2.6** to **Octopus 2018.10 LTS** doesn't go smoothly, this page will help you find a solution. If this page doesn't help, contact support. @@ -29,7 +30,7 @@ You can also refer to the Windows Event Log as well as Scheduled Tasks for more This section describes some common upgrade issues and ways to resolve them. -### Tentacle does not upgrade properly {#Troubleshooting-Tentacledoesnotupgradeproperly} +### Tentacle does not upgrade properly #### Symptoms #1 {#Troubleshooting-Symptoms#1} @@ -95,7 +96,7 @@ If the upgrade itself failed, this can be due to a previous installation of a 2. In this case, you will have to **log onto your Tentacle machine as the user who first installed the 2.0 version of the Tentacle**. You can then either run `Hydra.exe` directly, or manually uninstall the previous Tentacle and install the latest version of Tentacle. -### I've lost all my NuGet packages {#Troubleshooting-I'velostallmyNuGetpackages} +### I've lost all my NuGet packages #### Symptoms {#Troubleshooting-Symptoms} @@ -105,4 +106,4 @@ After migration, none of the NuGet packages that were present in the internal fe NuGet packages are not included in the Raven database backup, so will not be automatically moved to your new server and to the correct location. -To move your NuGet packages, follow the [instructions in the Upgrade documentation](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance/#Upgradewithanew3.0serverinstance-3.Migrateyourdatafrom2.6to3.x). After moving the files and restarting the service, your packages should be reindexed and available. +To move your NuGet packages, follow the [instructions in the Upgrade documentation](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance/#migrate-data-265-2018-10-lts). After moving the files and restarting the service, your packages should be reindexed and available. diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance.mdx b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance.mdx index fc1983edc0..97d9ec8022 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance.mdx +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/upgrade-with-a-new-server-instance.mdx @@ -5,6 +5,7 @@ modDate: 2023-10-04 title: Upgrade with a new server instance description: Information on how to upgrade from Octopus 2.6.5 to a new Octopus instance. navOrder: 2 +navSearch: false --- import UsingHydra from 'src/shared-content/using-hydra.include.md'; @@ -12,15 +13,15 @@ This is the recommended way of performing an upgrade for larger installations. I Be sure to read the [Upgrading from Octopus 2.6.5 to 2018.10 LTS](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts) documentation page. You must have a working **Octopus 2.6.5** installation for the data migration. -## Step by step \{#Upgradewithanew3.0serverinstance-Stepbystep} +## Step by step To upgrade to a modern version of Octopus Server, follow these steps: -### 1. Back up your Octopus 2.6.5 database and Master Key \{#Upgradewithanew3.0serverinstance-1.BackupyourOctopus2.6databaseandmasterkey} +### 1. Back up your Octopus 2.6.5 database and Master Key See the [Backup and restore](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/backup-2.6) page for instructions on backing up your database. -### 2. Install Octopus 2018.10 LTS on a new virtual or physical server \{#Upgradewithanew3.0serverinstance-2.InstallOctopus3.xonanewvirtualorphysicalserver} +### 2. Install Octopus 2018.10 LTS on a new virtual or physical server :::div{.success} **Upgrade to the latest version** @@ -29,7 +30,7 @@ When upgrading to **Octopus 2018.10 LTS** please use the latest version availabl See the [Installing Octopus 2018.10 LTS](/docs/installation) page for instructions on installing a new **Octopus 2018.10 LTS** instance. -### 3. Migrate your data from 2.6.5 to 2018.10 LTS \{#Upgradewithanew3.0serverinstance-3.Migrateyourdatafrom2.6to3.x} +### 3. Migrate your data from 2.6.5 to 2018.10 LTS \{#migrate-data-265-2018-10-lts} See the [Migrating data from Octopus 2.6.5 to 2018.10 LTS](/docs/administration/upgrading/legacy/upgrading-from-octopus-2.6.5-2018.10lts/migrating-data-from-octopus-2.6.5-2018.10lts) page for instructions on importing your **Octopus 2.6.5** database backup into **Octopus 2018.10 LTS**. @@ -47,11 +48,11 @@ In a standard **Octopus 2.6.5** install the files can be found under `C:\Octopus 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. ::: -### 4. Use Hydra to automatically upgrade your Tentacles \{#Upgradewithanew3.0serverinstance-4.UseHydratoautomaticallyupgradeyourTentacles} +### 4. Use Hydra to automatically upgrade your Tentacles -### 5. Verify connectivity between the 2018.10 LTS server and your Tentacles \{#Upgradewithanew3.0serverinstance-5.Verifyconnectivitybetweenthe3.xserverand3.xTentacles} +### 5. Verify connectivity between the 2018.10 LTS server and your Tentacles 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**. @@ -75,6 +76,6 @@ Performing the Check Health on your **Octopus 2018.10 LTS** server should now su 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. ::: -### 6. Decommission your Octopus 2.6.5 Server \{#Upgradewithanew3.0serverinstance-6.DecommissionyourOctopus2.6server} +### 6. Decommission your Octopus 2.6.5 Server Once you are confident your Tentacles have all been updated and work correctly, you can decommission your **Octopus 2.6.5** Server. diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.x-2.6.5.md b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.x-2.6.5.md index 72e48158b1..c9e8813e1f 100644 --- a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.x-2.6.5.md +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-2.x-2.6.5.md @@ -5,6 +5,7 @@ modDate: 2023-01-01 title: Upgrading from Octopus 2.x to 2.6.5 description: Information on how to upgrade from Octopus 2.x to 2.6.5. navOrder: 3 +navSearch: false --- :::div{.success} @@ -18,7 +19,7 @@ Upgrading **Octopus 2.0** involves two major steps. Additional information on troubleshooting upgrades is below. -## Upgrading the Octopus Server {#UpgradingfromOctopus2.0-UpgradingtheOctopusserver} +## Upgrading the Octopus Server To upgrade the Octopus Server, you will need to follow these steps: @@ -38,7 +39,7 @@ When the installer finishes, Octopus Manager will appear. Make sure the Octopus ![](/docs/administration/upgrading/legacy/images/3277991.png) ::: -## Upgrading Tentacles {#UpgradingfromOctopus2.0-UpgradingTentacles} +## Upgrading Tentacles After upgrading the Octopus Server, browse to the **Environments** tab in the Octopus Web Portal. You may need to press the "Check health" button to refresh the status of your Tentacles. If any of the Tentacle agents need to be updated, a message will appear: @@ -48,7 +49,7 @@ After upgrading the Octopus Server, browse to the **Environments** tab in the Oc Click on the **Upgrade machines** button to have Octopus send the new Tentacle package to all of the machines. -## Troubleshooting {#UpgradingfromOctopus2.0-Troubleshooting} +## Troubleshooting When **Octopus 2.0** was first released, the MSI was set as a "per user" install. This means that if Joe installed Octopus, Mary would not see the start menu entries. @@ -62,7 +63,7 @@ Instead, we added a check in **Octopus 2.1.3** that checks if a per-user install ![](/docs/administration/upgrading/legacy/images/3278002.png) ::: -### Uninstall Octopus 2.0 {#UpgradingfromOctopus2.0-UninstallingOctopus2.0} +### Uninstall Octopus 2.0 :::div{.success} **Your data is safe** @@ -79,7 +80,7 @@ You can uninstall the old version of the Octopus Deploy MSI installer and instal After you have uninstalled the old version of Octopus, you can install the new version. -### If you are still getting this error {#UpgradingfromOctopus2.0-Ifyouarestillgettingthiserror} +### If you are still getting this error After uninstalling the old version of Octopus and restarting, if you still receive this error, please navigate to the following registry keys: @@ -103,9 +104,9 @@ $RegServer = 'HKLM:\Software\Octopus\OctopusServer' $RegTentacle = 'HKLM:\Software\Octopus\Tentacle' $RegServer64 = 'HKLM:\SOFTWARE\Wow6432Node\Octopus\OctopusServer' $RegTentacle64 = 'HKLM:\SOFTWARE\Wow6432Node\Octopus\Tentacle' -$Regs = @($RegServer,$RegTentacle, $RegServer64, $RegTentacle64) +$Entries = @($RegServer,$RegTentacle, $RegServer64, $RegTentacle64) -foreach ($reg in $Regs) { +foreach ($reg in $Entries) { if (Test-Path $reg) { Remove-ItemProperty -Path $reg -Name InstallLocation } } ``` diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-3.x-to-modern.mdx b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-3.x-to-modern.mdx new file mode 100644 index 0000000000..2b188e9c33 --- /dev/null +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-3.x-to-modern.mdx @@ -0,0 +1,266 @@ +--- +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: 4 +navSearch: false +--- +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-in-place-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. + + + +## 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. + + + + + + + + + + + +## 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. + + + + + + + + + + + +### 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. +::: + + + + + + + + + + + +## 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. + + + + + + + + + + + + + + + + + + + + + + + +## 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. + + + + + + + +## 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 + +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 + +See the [Release Notes](https://octopus.com/downloads/compare?from=3.3.27&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 + +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 + +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" +``` diff --git a/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-4.x-2018.x-to-modern.mdx b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-4.x-2018.x-to-modern.mdx new file mode 100644 index 0000000000..2187d2c4d6 --- /dev/null +++ b/src/pages/docs/administration/upgrading/legacy/upgrading-from-octopus-4.x-2018.x-to-modern.mdx @@ -0,0 +1,178 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-01-01 +modDate: 2023-10-04 +title: Upgrading from Octopus 4.x / 2018.x to latest version +description: Information on how to upgrade from Octopus Deploy 4.x or 2018.x to the latest version +navOrder: 5 +navSearch: false +--- +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-in-place-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 UpgradeDisableTargetsClonedInstance from 'src/shared-content/upgrade/upgrade-disable-targets-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'; + +It is generally safe to do an in-place upgrade from Octopus Deploy 4.x/2018.x to the latest version. Please keep in mind, 4.x/2018.x did not include the Spaces feature. Spaces made the following changes: + +- 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. + +The upgrade should work without error, but there are integration concerns to consider. This guide will step through the steps to mitigate those concerns. + +## 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. + + + +## 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 2018. 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. + + + + + + + + + + + +## Risk mitigation recommended approach - create a test instance + +An in-place upgrade should be the safest approach. Upgrade scripts assume you are upgrading from older versions of Octopus Deploy. While the upgrade will work, there might be a new feature or breaking changes you will want to test first. The recommended approach is to create a test instance containing a subset of projects representing your main instance. Upgrade that test instance, verify it, and then upgrade the 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 upgraded main instance. +1. Disable maintenance mode. + + + + + + + + + + + + + + + + + + + + + +## Risk mitigation alternative approach - create a cloned instance + +An alternative approach to an in-place upgrade is to create a cloned instance and upgrade that. 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 for testing future upgrades. + +### 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. + + + + + + + + + + + + + + + + + + + + + + + + + +## 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. + + + + + + \ No newline at end of file diff --git a/src/shared-content/upgrade/upgrade-inplace-upgrade.include.md b/src/shared-content/upgrade/upgrade-in-place-upgrade.include.md similarity index 96% rename from src/shared-content/upgrade/upgrade-inplace-upgrade.include.md rename to src/shared-content/upgrade/upgrade-in-place-upgrade.include.md index 8a8470cd9c..be0dfaab70 100644 --- a/src/shared-content/upgrade/upgrade-inplace-upgrade.include.md +++ b/src/shared-content/upgrade/upgrade-in-place-upgrade.include.md @@ -8,7 +8,7 @@ The Windows Service is split across multiple folders to make upgrading easy and - **SQL Server Database**: Since `Octopus Deploy 3.x`, the back-end database has been SQL Server. Each update can contain 0 to N database scripts embedded in a .dll in the install location. The `Octopus Manager` invokes those database scripts automatically. - **Home Folder**: The home folder stores configuration, logs, and other items unique to your instance. The home folder is separate from the install location to make it easier to upgrade, downgrade, uninstall/reinstall without affecting your instance. The default location of the home folder is `C:\Octopus`. Except in rare cases, this folder is left unchanged by the upgrade process. - **Instance Information**: The Octopus Deploy Manager allows you to configure 1 to N instances per Windows Server. The `Octopus Manager` stores a list of all the instances in the `C:\ProgramData\Octopus\OctopusServer\Instances` folder. Except in rare cases, this folder is left unchanged by the upgrade process. -- **Server Folders**: Logs, artifacts, packages, and event exports are too big for Octopus Deploy to store in a SQL Server database. The server folders are subfolders in `C:\Octopus\`. Except in rare cases, these folders are left unchanged by an upgrade. +- **Server Folders**: Logs, artifacts, packages, and event exports are too big for Octopus Deploy to store in a SQL Server database. The server folders are sub-folders in `C:\Octopus\`. Except in rare cases, these folders are left unchanged by an upgrade. - **Tentacles**: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until _after_ the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work [with any modern version of Octopus Deploy](/docs/support/compatibility). We recommend you upgrade them to get the latest bug fixes and security patches when convenient. - **Calamari**: The Tentacles facilitate communication between Octopus Deploy and the deployment targets. Calamari is the software that does the actual deployments. Calamari and Octopus Deploy are coupled together. Calamari is upgraded automatically during the first deployment to a target.components.