Typical upgrade steps

For each Azkaban Web and Executor Server instance:

1. Stop the Windows services and/or Linux processes for each Web and Exec server.

2. Perform backups of the following:

   • Your Azkaban metadata repository

   • azkaban.local.properties for each Web and Exec server

   • Any other configuration files if you have customized them

3. Run the installer targeting the existing Azkaban install locations:

   • Step 1 - upgrade the Azkaban metadata
   • Step 2 - upgrade the Azkaban Web Server
   • Step 3 - upgrade each Azkaban Executor

4. Merge any customizations back in from your earlier backups.

5. Start the Azkaban Web and Executor services and/or Linux processes.

6. Upgrade or merge changes to the Scheduler Integration Scripts as required.
7. Create scheduler authentication profiles as required. See Scheduler Profile Maintenance for details.

Backup of your Azkaban Properties and Configuration files

When you choose to upgrade either the Scheduler or the Executor, the installer will make a copy of any properties and configuration files that could have custom settings. These copies are stored on a folder called 'Backup-<timestamp>' in the ‘WEB_SERVER’ and ‘EXEC_SERVER’ folders. The backup includes these files:

• azkaban.local.properties
• azkaban-users.xml
• log4j.properties
• Response.xml
• users.xml

You can also manually backup these files for each Web Server and Executor Server being upgraded.

The backup of the azkaban.local.properties file will be useful to open while you run the installer so you can apply the correct settings to the installer fields.

Upgrade on Windows

1. On the RED installation folder, run RedSchedulerInstaller.exe to start the upgrade process, follow the interactive installer wizard. Please note the RedSchedulerInstaller.exe must be run using the same user that the Azkaban services are run under. 

   Hold down Shift and right click on RedSchedulerInstaller.exe and select “run as different user” then enter the Azkaban service user credentials if you are currently logged in as another user.

   For scripted upgrades, the Linux upgrade method described later can also be used on Windows.

   
   

2. To upgrade the Azkaban metadata and Web Server on this machine, select Scheduler Upgrade and check the components you want to upgrade. 
   
3. Select the location of the scheduler you want to upgrade.
   
   1. If you are upgrading from a version lower than RED 10.2, you will be required to specify the profile encryption secret and Windows service credentials.
4. The Upgrade wizard will collect all the required connection information from azkaban.local.properties and will show it on the summary window.
   
5.  To proceed through the rest of the installation wizard click Install.
6. Post install you need to manually merge any customizations to the azkaban.local.properties and users file as required before starting up your services again.

Command-line Upgrades for Linux or Windows

Like RED, Azkaban is comprised of two distinct parts, the application and the metadata. Some releases may only require one or the other to be upgraded so please refer to the important upgrade messages in the release notes to determine the upgrade requirements.

Azkaban Upgrade Steps

1. Upgrade the Azkaban Metadata

2. Upgrade the Azkaban Web Server

3. Upgrade one or more Azkaban Executor Servers

4. Merge any Customizations
5. Startup the Services or Processes

Before you begin

It is recommended you perform backups of the following so that any customizations can be merged back in after the upgrade:

• Your Azkaban metadata repository

• azkaban.local.properties for each Web and Exec server

• Any other configuration files if you have customized them

1. Upgrade the Azkaban Metadata

Ensure the Web Server service or process is stopped.

Perform the Azkaban metadata install by executing the below commands in your command shell in Linux or Windows.

• Stop the Web Server service or process
• Set the environment variables for your Azkaban metadata user and pwd:
  AZ_DB_USER=myuser
AZ_DB_PWD=mypwd
• Then, run the  azkaban-installer.jar  with the ‘upgrade-schema’ command:
  

  java.exe -jar  "azkaban-installer.jar"   upgrade-schema --database=AZ_REPO --host=PG_HOST --port= 5432   --schema=white --username-var=AZ_DB_USER --password-var=AZ_DB_PWD

2. Upgrade the Azkaban Web Server

Ensure the Web Server service or process is stopped.

• For Linux: Copy the scheduler .jar file from  <RED_install_dir>\Azkaban\azkaban-installer.jar  to the host machine and run the following command (with Java 11 JRE):

  java -jar azkaban-installer.jar --log-file=./install.log install-server --response-file=web_server_response_file.xml

• For Windows: Open a command prompt and run the following command, replacing the directory location placeholders:

  <RED_install_dir>\jre\bin\java -jar <RED_install_dir>\Azkaban\azkaban-installer.jar --log-file=c:\temp\install.log install-server --response-file=<WEB_install_dir>\web_server_response_file.xml

3. Upgrade one or more Azkaban Executor Servers

Ensure the Executor Server service or process is stopped.

• For Linux: Copy the scheduler .jar file from  <RED_install_dir>\Azkaban\azkaban-installer.jar  to the host machine and run the following command (with Java 11 JRE):

  java -jar azkaban-installer.jar --log-file=./install.log install-server --response-file=executor_server_response_file.xml

• For Windows: Open a command prompt and run the following command, replacing the directory location placeholders:

  <RED_install_dir>\jre\bin\java -jar <RED_install_dir>\Azkaban\azkaban-installer.jar --log-file=c:\temp\install.log install-server --response-file=<EXEC_install_dir>\executor_server_response_file.xml

4. Merge any Customizations 

Post-install you need to manually merge any customizations to the azkaban.local.properties and users file as required before starting up your services again.

5. Startup the Services or Processes

• For Windows: Open Services in Windows and restart each Web and Executor service

• For Linux: Run the startup script in the Azkaban install location within the bin directory.

Upgrade the Scheduler Integration Scripts

Some releases add improvements to the shipped Azkaban integration scripts, any such changes will be signaled in the release notes.

Due to specific environmental customizations users may have made to these scripts they are not upgraded automatically, instead you need to extract them from the installation folder and review and merge the changes to your existing scripts as required.

The shipped scheduler integration scripts are described below:

• wsl_scheduler_publish - publishes job metadata to Azkaban

• wsl_scheduler_lookup - retrieves the tags of all active Azkaban Executors

• wsl_scheduler_dashboard - opens the Azkaban Web Server dashboard

• wsl_scheduler_profile_maintenance - script for maintaining the scheduler profile

To upgrade any of these scripts follow this process:

1. In RED, open the Azkaban integration script in the script editor such as wsl_scheduler_publish under your Host Script objects.
2. In notepad open the matching script located in the RED installation directory under <RED install directory>\Administrator\Scripts\
3. Copy the contents of the updated script into the RED script editor to overwrite the existing script and save.

Upgrade Troubleshooting

Upgraded RED and now Azkaban doesn't start?

If you installed RED to a different location than when the Azkaban services were created, then you'll need to update the ImagePath key in the registry for each Azkaban service.

For example:

• Registry location: Computer\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WsAzkabanExec_red1001_db

• Key: ImagePath

• Value: "C:\Program Files\WhereScape\RED\10001-230606-005456\WslSchedulerService.exe" --type="Exec" --scheduler-dir="C:\temp\azkaban\red1001_db" --start-service=true --service-name="WsAzkabanExec_red1001_db"