Option 2 - Upgrading Omnissa Access Control Plane Deployments

This topic describes the recommended procedure for upgrading an existing Control Plane-based Omnissa Access deployment. It covers upgrading operating system packages, the Control Plane asset bundle, Access services, and the bootstrap machine.

Important: These upgrade instructions are not applicable for upgrading versions 24.12 or earlier. This method is planned for deprecation. It is suggested to use these instructions Upgrading Omnissa Access Using the Access Wizard for upgrading Omnissa Access.

Prerequisites

• Run all commands from the bootstrap machine, unless otherwise specified.
• The existing deployment must be healthy. Run wso healthcheck and wso access check-service-readiness to confirm system health before you begin.
• The offline asset bundle for the target release is downloaded and available in the bootstrap machine.
• The OS security RPM is downloaded and available in the bootstrap machine, if this upgrade includes OS package upgrades.

Upgrade Workflow

An upgrade consists of the following phases:

1. Upgrade Phase 1 - Download and configure the local repository for operating system upgrades (only when operating system package upgrades are required).
2. Upgrade Phase 2 - Download and configure the new Control Plane asset bundle.
3. Upgrade Phase 3 - Upgrade the Control Plane, optionally including OS package upgrades.
4. Upgrade Phase 4 - Upgrade Access services and validate services status.
5. Upgrade Phase 5 - If Upgrade Phase 1 was applicable, upgrade the bootstrap machine operating system.

Regardless of which phase you start from, complete the Prep section below first.

Preparation - Export Shell Variables

Set the following variables in your shell before you begin. Later phases depend on them, including phases you might start from directly if you skip Upgrade Phase 1.

export BOOTSTRAP_IP=<bootstrap_ip>
export WORKDIR=<cluster_dir>
export PATCH_DIR=<patch_dir>

Upgrade Phase 1 - Configure the Local Repository for OS Upgrades

Note: If this upgrade does not include operating system package upgrades, skip to Upgrade Phase 2 - Configure the New Asset Bundle.

Procedure:

1. Download or copy security RPMs to bootstrap node, using one of the following options:

   • Option 1 - curl from Artifactory

     curl -L -o /root/security-rpms-with-portable-script.tar.gz \
       "<artifactory-path-to-security-pkg-bundle>"
     

   • Option 2 - scp from local machine to bootstrap node

     From local machine:

     scp security-rpms-with-portable-script.tar.gz configuser@${BOOTSTRAP_IP}:/home/configuser
     

     On the bootstrap node:

     mv /home/configuser/security-rpms-with-portable-script.tar.gz /root/
     

     Note: The above URL is an example. Use the Artifactory path for your target OS security release.

2. Update bootstrap localrepo

   1. Extract the security update bundle on the bootstrap node.

      tar -xvf /root/security-rpms-with-portable-script.tar.gz -C /root/
      

      Note: The both must provide both:

      • security-rpms.tar.gz
      • cp-alma-portable-fixes-v1.sh

   2. Apply the AlmaLinux portable fixes on the bootstrap node before refreshing the local repository. These fixes prepare the bootstrap environment for the portable OS security update workflow.

      sh /root/cp-alma-portable-fixes-v1.sh
      

   3. Refresh the bootstrap local repository with the extracted security RPM archive.

      sh /usr/local/sbin/update-dnf-repo.sh /root/security-rpms.tar.gz
      

3. Set environment variables

   export WORKDIR="/root/cp-cluster"
   export BOOTSTRAP_IP="<bootstrap-ip>"   # reachable from cluster nodes
   export TARGETS="general_compute_linux:general_compute_access_linux"
   export ASSET_DIR="${WORKDIR}/assets-2607"   # adjust version folder name
   

4. Enable localrepo on bootstrap node and stage CA for ansible copy

   cd "${WORKDIR}"
   
   sed -i 's/enabled=0/enabled=1/' /etc/yum.repos.d/localrepo.repo
   mkdir -p "${WORKDIR}/access/localrepo_ca_path"
   cp -f /etc/nginx/localrepo-certs/root-ca.crt "${WORKDIR}/access/localrepo_ca_path/root-ca.crt"
   
   if [ -f /root/cp-alma-portable-fixes-v1.sh ]; then
     cp -f /root/cp-alma-portable-fixes-v1.sh "${WORKDIR}/access/cp-alma-portable-fixes-v1.sh"
   fi
   
   if [ -f /root/remove-old-ova-rpms.sh ]; then
     cp -f /root/remove-old-ova-rpms.sh "${WORKDIR}/access/remove-old-ova-rpms.sh"
   fi
   
   if [ -s /root/removed-packages.txt ]; then
     cp -f /root/removed-packages.txt "${WORKDIR}/access/removed-packages.txt"
   fi
   

5. Push HTTPS localrepo config to cluster nodes

   Run from ${WORKDIR} on bootstrap node (requires wso control-plane ansible / inventory groups general_compute_linux and general_compute_access_linux):

   1. Create the local repository certificate directory on each target node.

      wso control-plane ansible -- -b -m file \
        -a "path=/etc/nginx/localrepo-certs state=directory owner=root group=root mode=0755" \
        "${TARGETS}"
      

   2. Copy the bootstrap local repository root CA to each target node. This allows the target nodes to trust the bootstrap-hosted HTTPS local repository.

      wso control-plane ansible -- -b -m copy \
        -a "src=/workdir/access/localrepo_ca_path/root-ca.crt dest=/etc/nginx/localrepo-certs/root-ca.crt owner=root group=root mode=0644 force=yes" \
        "${TARGETS}"
      

   3. Configure each target node to use the bootstrap HTTPS local repository. The repository is enabled with certificate validation using the copied root CA.

      wso control-plane ansible -- -b -m ini_file \
        -a "path=/etc/yum.repos.d/localrepo.repo section=localrepo option=baseurl value=https://${BOOTSTRAP_IP}/" \
        "${TARGETS}"
      wso control-plane ansible -- -b -m ini_file \
        -a "path=/etc/yum.repos.d/localrepo.repo section=localrepo option=sslverify value=1" \
        "${TARGETS}"
      wso control-plane ansible -- -b -m ini_file \
        -a "path=/etc/yum.repos.d/localrepo.repo section=localrepo option=sslcacert value=/etc/nginx/localrepo-certs/root-ca.crt" \
        "${TARGETS}"
      wso control-plane ansible -- -b -m ini_file \
        -a "path=/etc/yum.repos.d/localrepo.repo section=localrepo option=enabled value=1" \
        "${TARGETS}"
      

   4. Rebuild the DNF cache from the local repository only. Repeat this step whenever new RPMs are added to /opt/localrepo on the bootstrap node.

      wso control-plane ansible -- -b -m shell \
        -a "dnf clean all && rm -rf /var/cache/dnf/* && dnf --refresh makecache --disablerepo='*' --enablerepo=localrepo && dnf --refresh --disablerepo='*' --enablerepo=localrepo list available" \
        "${TARGETS}"
      

   5. Copy scripts to /tmp (portable required; remove-old-ova optional).

      if [ -f "${WORKDIR}/access/cp-alma-portable-fixes-v1.sh" ]; then
        wso control-plane ansible -- -b -m copy \
          -a "src=/workdir/access/cp-alma-portable-fixes-v1.sh dest=/tmp/cp-alma-portable-fixes-v1.sh owner=root group=root mode=0755" \
          "${TARGETS}"
      
        if [ -f "${WORKDIR}/access/remove-old-ova-rpms.sh" ]; then
          wso control-plane ansible -- -b -m copy \
            -a "src=/workdir/access/remove-old-ova-rpms.sh dest=/tmp/remove-old-ova-rpms.sh owner=root group=root mode=0755" \
            "${TARGETS}"
        fi
      
        if [ -f "${WORKDIR}/access/removed-packages.txt" ]; then
          wso control-plane ansible -- -b -m copy \
            -a "src=/workdir/access/removed-packages.txt dest=/tmp/removed-packages.txt owner=root group=root mode=0755" \
            "${TARGETS}"
        fi
      fi
      

   6. Run portable fixes only (it looks for remove-old-ova-rpms.sh on its own).

        wso control-plane ansible -- -b -m shell \
          -a "bash /tmp/cp-alma-portable-fixes-v1.sh" \
          "${TARGETS}"
      

   Note: Verify cluster nodes can see expected security packages before proceeding.

Upgrade Phase 2 - Configure the New Asset Bundle

Procedure:

1. Create a directory for the new asset bundle and download it:

   mkdir -p ${ASSET_DIR}
   cd ${ASSET_DIR}
   # Copy the target release asset bundle to this location ${ASSET_DIR}
   

   Important: Download the asset bundle that corresponds to your target release. Do not reuse a bundle from an older release.

2. Extract the bundle and add the CLI to your path:

   # Ensure that you are in ${ASSET_DIR} before you unzip the asset bundle
   unzip asset-bundle.zip
   cp cli-distribution/linux/wso /usr/bin/
   cp: overwrite '/usr/bin/wso'? y # It will prompt for overwrite
   wso eula
   Do you agree to these terms ? [y/n]: y
   

3. Configure the CLI to use the new bundle:

   cd ${WORKDIR}
   wso configure ${ASSET_DIR}
   

Upgrade Phase 3 - Upgrade the Control Plane

Procedure:

1. Deploy the Control Plane with the new asset bundle. Include -u if this upgrade also upgrades OS packages on the cluster nodes:

   #  To upgrade without OS packages upgrade
   nohup wso cp deploy &
   # To upgrade with OS packages upgrade
   nohup wso cp deploy  -u &
   

   This step will take some time to complete.

2. Verify the deployment:

   ./verify-os-update.sh
   wso version
   wso healthcheck
   

3. If you deployed with -u, unseal the cluster:

   Note: You can skip this step if you have deployed without -u

   wso cp unseal
   

   This step will take some time to complete.

Upgrade Phase 4 - Upgrade Access Services

Procedure:

1. Reconcile the Access configuration for the upgrade:

   cd ${WORKDIR}
   wso access update-config set
   

2. If a services directory exists in the working directory from a prior patch or upgrade, use the command below so the deployment uses the images from the new bundle instead:

   mv ${WORKDIR}/services ${WORKDIR}/services.bk
   

3. If using a proxy, settings can be tested, prior to being applied:

   wso access proxy test unauthenticated
   wso access proxy test authenticated
   

4. If using a proxy, settings can be persisted, after testing:

   wso access proxy configure unauthenticated
   wso access proxy configure authenticated
   wso access config set --config_key IPS_TO_IGNORE_IN_XFFHEADER --config_value <list of addresses>
   

   • Required parameters: --proxy_host and --proxy_port
   • Optional parameters: --non_proxy_host
   • When using authentication: proxy_user and --proxy_password

5. If using a proxy, current settings can be displayed:

   wso access proxy get
   

6. Deploy all Access services:

   nohup wso services deploy --type full &
   

7. Check the health of the services:

   wso access check-service-readiness
   

8. After all services report healthy, exit upgrade mode:

   wso access update-config reset
   

9. Clean up assets from the previous release:

   wso cp reset-assets
   

Upgrade Phase 5 - Upgrade the Bootstrap Machine Operating System

Perform this phase only after the cluster upgrade has completed successfully. You can perform your cluster operations once you complete Upgrade Phase 4.

For this phase, choose either to perform in-place upgrade or to replace the machine.

In-Place Upgrade

1. Upgrade packages and reboot the bootstrap machine:

   dnf update -y
   reboot
   

2. After the bootstrap machine comes back online, validate the cluster:

   cd /root/cp-cluster
   wso healthcheck
   wso access check-service-readiness
   

Replace the Machine

Use this option when you want to deploy a new bootstrap machine from the latest Omnissa OVA instead of patching the existing bootstrap machine in place. This approach is recommended for major OS upgrades.

Step 1 - Create a Migration Package from the Existing Bootstrap Machine

cd /opt/wss/<cluster_name>

tar czpvf /opt/wss/<cluster_name>-migration-$(date +%Y%m%d).tar.gz \
  profile.yml \
  logging \
  telegraf_plugin \
  ansible_extra_vars.yml \
  access \
  cp-cluster \
  additional_env_vars.env \
  deploy_services.log \
  deployment-config.yml

Step 2 - Copy the Migration Package to the New Bootstrap Machine

scp /opt/wss/<cluster_name>-migration-*.tar.gz configuser@<new-bootstrap-machine>:/home/configuser/

Step 3 - Restore the Configuration on the New Bootstrap Machine

mkdir -p /opt/wss/<cluster_name>
cd /opt/wss/<cluster_name>

tar xzpvf /home/configuser/cp-cluster-migration-*.tar.gz

The new bootstrap machine now contains the same deployment configuration as the previous bootstrap machine.

Step 4 - Configure the Asset Bundle

Copy the asset bundle used with the existing bootstrap machine to the new bootstrap machine and then execute the steps that follow.

mkdir -p assets
cd assets
# COPY asset bundle at this path.
unzip asset-bundle.zip
cp cli-distribution/linux/wso /usr/bin/
wso eula
wso configure /opt/wss/<cluster_name>/assets/
cd ..

Step 5 - Validate the New Bootstrap Machine

wso version
wso healthcheck
wso access check-service-readiness

Verify that the CLI version, Control Plane image version, CPS image version, cluster health, and Access service readiness are all correct. All Access services should report a status of READY.

Disaster Recovery

When the upgrade is completed, Omnissa strongly recommends backing-up critical files on the bootstrap node. Recovery is not possible, without completing the steps in: Back Up Bootstrap Node Data.