Automating Upgrades - robedi/PowerShell GitHub Wiki

This guide explains how to use a PowerShell script to automate the upgrade process of an Octopus Deploy server. The script downloads the latest version of Octopus, places the server in maintenance mode, backs up relevant data, performs the upgrade, and then exits maintenance mode. Below is a detailed step-by-step instruction on how to configure and run the script.

Based on original script: Upgrading single node Octopus Deploy instances

---

Script: AutomatingUpgrades.ps1

Before running the script, ensure you have:

• A valid Octopus Deploy API key.
• Administrative rights on the Octopus Deploy server.
• Backup permissions to save files and databases.
• PowerShell 5.1 or later installed.

1. Clone the Repository or Download the Script

   • Ensure the script is available on the Octopus server by cloning the repository or downloading it from the appropriate location.

2. Edit the Script for Your Environment

   • Open the PowerShell script and update the following placeholder values with your actual configuration:

Variable Name	Description	Example
$url	The URL of your Octopus Deploy Web Portal	https://octopus.yourdomain.com
$apiKey	Your Octopus API key	API-KEY
$octopusDeployDatabaseName	The name of the Octopus Deploy database	OctopusDeploy
$sqlBackupFolderLocation	Network share or path where the database backup will be stored	\\ServerStorage\Backup\Database
$fileBackupLocation	Network share or path where file backups will be stored	\\ServerStorage\Backup\Files
$downloadDirectory	Directory where the installer MSI will be downloaded (can be a local or network path)	${env:Temp} or \\NetworkShare

3. Set Permissions

   • Ensure the user running the script has the necessary permissions to:
     • Write to the backup folders.
     • Manage the Octopus Deploy service (start/stop).
     • Perform database backups.

4. Run the Script

   • Open a PowerShell window with administrative privileges and execute the script:

   .\AutomatingUpgrades.ps1
   PowerShell.exe -ExecutionPolicy Bypass -File .\AutomatingUpgrades.ps1

---

1. Version Check

   • The script checks the current version of Octopus against the latest available version from Octopus Deploy.
   • If no new version is found, the script exits.

   $currentVersion = (Invoke-RestMethod "$Url/api").Version
   $upgradeVersion = $versions[-1].Version

2. Backup Folders

   • If the current version is a major upgrade (e.g., from 2021.x to 2022.x), the script backs up key folders:
     • Artifacts
     • EventExports
     • Packages
     • TaskLogs
     • Telemetry

   robocopy $serverFolders.<Directory> $fileBackupLocation\<Directory> /mir

3. Database Backup

   • The script performs a backup of the Octopus Deploy database using SqlServer PowerShell module.

   $command.CommandText = "BACKUP DATABASE [$octopusDeployDatabaseName] TO DISK = '$backupFileFullPath' WITH FORMAT;"

4. Download and Install the Update

   • The latest version of Octopus Deploy is downloaded from the Octopus Deploy site if it's not already available locally.
   • The installer runs silently in the background to upgrade the server.

   Start-Process -FilePath "msiexec.exe" -ArgumentList "/i $msiToInstall /quiet" -Wait -PassThru

5. Upgrade the Database

   • After the installation, the script upgrades the Octopus Deploy database schema to the new version.

   & $serverExe database --instance="OctopusServer" --upgrade

6. Restart the Service

   • The script updates the database, restarts the Octopus service and stop the drain process.

   & $serverExe database --instance="OctopusServer" --upgrade
   & $serverExe service --instance="OctopusServer" --start
   & $serverExe node --instance="OctopusServer" --drain=false

   • The command will place the server out of maintenance, within five attempts. Comment this line, if you want to check the integrity of the Octopus Deploy server.

   Set-OctopusOutOfMaintenanceMode -url $url -apiKey $apiKey

7. Clean Up

   • The downloaded MSI installer is removed after the installation completes.

   Remove-Item "$downloadDirectory\$msiFilename"

---

The script contains built-in error handling for several key areas:

• Network Failures: If unable to connect to the server, the script retries connecting multiple times before exiting.
• File Copy Failures: If robocopy fails to copy files, the script throws an error and exits.
• Database Backup Failures: If the database backup fails, the script exits and rolls back any changes by restarting the service.

---

• If the script encounters any issue during the upgrade process (e.g., network failure, backup failure), it will attempt to revert to the pre-upgrade state by restarting the Octopus service. Additionally, the script will exit maintenance mode and provide an error message.

• Yes. The script can be used for multiple Octopus instances. You need to modify the instance-specific parameters (e.g., database name, API key) accordingly.

• The script is designed to check for all available updates. However, it can be modified to only apply patch updates by adding additional logic to check the minor version number.

---

• Test in a Staging Environment: Before running the script in production, test it in a non-critical environment to ensure compatibility with your Octopus Deploy setup.
• Regular Backups: Ensure regular backups are performed outside of the upgrade process to avoid potential data loss.
• Monitor the Upgrade: During the upgrade process, it's advisable to monitor the server logs for any issues.

---

By following these instructions, you'll be able to automate the upgrade of your Octopus Deploy server, ensuring backups are made, and services are restored without manual intervention.