Upgrading BlueCat Server Update Services to a new version - Adaptive Applications - BlueCat Gateway - 25.2

BlueCat Server Update Services Administration Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
25.2
Tip: Instructions for applying an update are also included in release notes for the release in question.

BlueCat periodically releases patches and updates for the BlueCat Server Update Services (BSUS) application itself. If you're using an existing BSUS system, you must download and apply the updated custom BlueCat Gateway image that contains the BlueCat Server Update Services workflow. The custom BlueCat Gateway image can be downloaded from Quay.

During the upgrade process, you'll download the patch, back up your Planned Updates list, then restore those scheduled updates after BSUS is upgraded. The download package includes a script to use to properly back up and download your scheduled updates.

CAUTION:
If you do not back up and restore your list of scheduled updates, they will be lost when upgrading BSUS.

Before you begin the BSUS upgrade

Make sure that there are no DNS/DHCP Server updates currently in progress. Any DNS/DHCP Server updates should be either completed before updating BSUS, or scheduled to take place well after the expected time for the BSUS update to complete.

Important: When upgrading from BSUS v21.x or v22.x, you must first upgrade to BSUS v23.x. You can upgrade to BSUS 25.2 only from BSUS v23.x.

Applying a BlueCat Server Update Services application update

To acquire and upgrade your BlueCat Server Update Services system:

  1. From the host machine, navigate to the dist directory containing the docker-compose.yml file for the current running version.

  2. Download the bsus_installer-25.2-GA.zip installer file from BlueCat Customer Care.

  3. Unzip the installer file.

    Among other files, the zip file contains several files you will need to use during the upgrade:

    • backup_jobs.sh: Used to back up the list of scheduled updates from your Scheduled Updates page (changed to Planned Updates as of v23.1).

      After updating BSUS, you will restore the list of updates with the /job_restoration REST API endpoint.

    • docker-compose.yml: Used to configure docker so that it can properly install the docker container that holds BSUS.

    • example.env: A template environment file. You will use this as a template for the .env file (no prefix) that contains credentials for the BlueCat software that BSUS integrates with.

    • update_volume.py: Assists with docker volume mapping between versions.

    Tip: The backup_jobs.sh and update_volume.py scripts will be used only if you are upgrading from a version prior to BSUS v23.1.

  4. If you are upgrading from a version prior to BSUS v23.1, back up your jobs and update mapping for your volumes as follows:

    1. Within the set of downloaded files, go to the dist subfolder and grant executable permission to the backup_jobs.sh script.

      To do so, run the following command from the dist subfolder: 
      chmod +x ./backup_jobs.sh

    2. Set up docker volume mapping in the update_volume.py script as follows:

      1. Make sure that the current version of BSUS is still running. Then, go to the dist subfolder and grant executable permission to the update_volume.py script. To do so, run the following command from the dist subfolder: 
        chmod +x ./update_volume.py
      2. Install the pyyaml package as follows: 
        pip install pyyaml
      3. Run the update script as follows: 
        python3 ./update_volume.py

    3. Back up your list of scheduled updates using the backup_jobs.sh script (also located within the extracted files).

      To do so, run the backup_jobs.sh script from the dist subfolder as follows: 
      ./backup_jobs.sh

  5. Turn off the Docker container using the following command:

    docker-compose down

    You can verify that the BlueCat Server Update Services container is turned off by running the docker ps command. If the BlueCat Server Update Services container names do not appear in the list, the Docker containers were successfully shut down.

  6. In the same folder as the extracted file docker-compose.yml, create an environment variable file named .env (with no prefix) that contains Address Manager, BlueCat Gateway, and RabbitMQ credentials.

    Tip: Use the provided sample environment file example.env as a template.
    Important: Do not change RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS from their current values ("guest").
    For example:
    BAM_IP=192.168.88.54
BSUS_IP=192.168.88.64
RABBITMQ_DEFAULT_USER=guest
RABBITMQ_DEFAULT_PASS=guest
USE_TLS=true
PATCH_TIMEOUT_MINUTES=15
BSUS_ADMIN_GROUP=admin_group
ELASTIC_PASSWORD=ChangeMe
    Where

    • BAM_IP variable is the IP address of Address Manager.

    • BSUS_IP is the IP address of the BlueCat Gateway instance that will be running BlueCat Server Update Services.

    • RABBITMQ_DEFAULT_USER is the default username of the RabbitMQ service. Do not change this from "guest".

    • RABBITMQ_DEFAULT_PASS is the default password of the RabbitMQ service. Do not change this from "guest".

    • USE_TLS specifies whether or not to use TLS encryption for communications between BSUS containers.

    • PATCH_TIMEOUT_MINUTES specifies the maximum number of minutes a patch can take when applied or scheduled. If this limit is exceeded, the apply/schedule process will be considered a failure. For example, with the default value is 15 minutes, if the upgrade.log file is no longer updated after 15 minutes, it will show a time-out event.

    • BSUS_ADMIN_GROUP specifies which Address Manager group to use as the BSUS Administrator user group. This group will have access rights to use all features and functionality in BlueCat Server Update Services, and rights to add, modify, or delete all BSUS Server Batches.

      Note: This setting is new as of BSUS v23.1. If you're upgrading from a version before v23.1, you must decide which Address Manager user group to use as the BSUS Administrator group. For more details on BSUS Access Right Settings, see Managing BSUS Access Rights.
      Tip: You can set up non-admin groups for BSUS in the BSUS Access Right Settings page.

    • ELASTIC_PASSWORD is the password for the BSUS search database.

      Note: Until you specify ELASTIC_PASSWORD, the search database will be unprotected. If no password is set on the database, BSUS will set the database password the first time it sees the ELASTIC_PASSWORD setting in the .env file.

      If the database is already password-protected, BSUS will attempt to use the password specified in ELASTIC_PASSWORD. Therefore, after adding ELASTIC_PASSWORD to the .env file, do not change it again.

      Note: In previous releases, this setting was DB_PASSWORD. When updating to the new version of BSUS, change DB_PASSWORD to ELASTIC_PASSWORD.
    Note: If you are installing BlueCat Server Update Services for environments where you must specify the network range to which the BlueCat Server Update Services service containers are assigned. For more details, see Configuring a dedicated network range for BSUS.

  7. Run the updated BlueCat Server Update Services docker container using the following command:

    docker-compose up -d

    The BlueCat Server Update Services Adaptive Application starts up. You can proceed to access the BlueCat Server Update Services Adaptive Application from the browser window once the service has started.

    To verify that the service has started, run the following command:
    docker-compose logs -f | grep "Declaring"
    The following log message indicates that the service has started:
    logstash_1       | [2021-05-17T16:06:42,205][INFO ][logstash.inputs.rabbitmq ]
[main][ab3ce81ccc3d228c9c8d56d7f16bb605c6d35ff5bca7dd75ed83e6ab37dfa86e] 
Declaring exchange 'bsus' with type topic
    Important: You must wait for the BlueCat Server Update Services Adaptive Application to start before attempting to access the UI. If you do not wait for the Declaring exchange 'bsus' with type topic message to appear and attempt to access the UI before the service has started, you will receive the following error:
    Get Batches Error: NotFoundError(404, 'index_not_found_exception', 'no such index [batch], batch, index_or_alias)

    If you receive this error, you must stop the current BlueCat Batch Update Services container, delete the container, and install a new container.

  8. If you are upgrading from a version prior to BSUS v23.1, restore the list of scheduled jobs that you backed up as follows:

    After starting the docker container, call the POST /job_restoration REST API endpoint:

    http://<Gateway_hostname_or_IP>/bsus/api/v1/job_restoration

    Tip: You can also run this endpoint directly from the BSUS Swagger documentation (the in-product interactive documentation for BSUS's REST API). To access the Swagger documentation, go to:

    http://<Gateway_hostname_or_IP>/bsus/api/v1/doc

  9. (Optional, but recommended) After the upgrade finishes successfully, you can change the RabbitMQ username and password that BSUS uses. For more details, see Modifying the RabbitMQ password.