Skip to content

Technical Reference: Rhapsody Upgrade Playbook Logic

Parent Page: [How-To: Rhapsody Upgrade Workflows] Description: This document details the step-by-step technical execution performed by the Ansible playbook (play-rhapsody-upgrade.yml) when an upgrade is triggered via GitHub Actions.

🔍 High-Level Overview

The upgrade process is an automated workflow that manages the end-to-end lifecycle of a Rhapsody version change. It performs version validation, environment preparation, artifact retrieval, safety snapshots, the actual installation, and post-deployment verification.

🔄 Workflow Diagram

graph TD
    A[Start] --> B{Check Version}
    B -- Up to Date --> C[Stop / Fail]
    B -- Upgrade Needed --> D[Prepare Environment]
    D --> E[Query Azure Metadata]
    E --> F[Download Installer from S3]
    F --> G[Stop Rhapsody Service]
    G --> H{Snapshot Requested?}
    H -- Yes --> I[Snapshot Data Disk]
    H -- No --> J[Run Installer]
    I --> J
    J --> K[Start Rhapsody Service]
    K --> L[Health Check Endpoint]
    L -- 200 OK --> M[Update Azure VM Tags]
    M --> N[Cleanup & Finish]

🛠️ Detailed Execution Steps

1. Pre-Flight Checks & Version Validation

Before any changes are made, the playbook ensures the upgrade is valid.

  • Current Version Check: Reads /data/orionhealth/rhapsody/version.txt.

  • Comparison: Compares the installed version against the requested rhapsody_version.

  • Guard Rail: If the installed version is newer than or equal to the requested version, the playbook fails immediately to prevent accidental downgrades or redundant operations.

2. Environment Preparation

The system prepares the host for the upgrade binaries.

  • Directory Management: Cleans and recreates the /data/orionhealth/upgrade/ directory to ensure no stale files exist.

  • Dependency Management: Upgrades pip and installs AWS SDKs (boto3, botocore) required to fetch the installer from S3.

  • Configuration Backup: If upgrading to version 7+, a backup of log4j.properties is created.

  • Response File: Generates a response.data file (using a Jinja2 template) which automates the answers required by the Rhapsody installer script.

3. Azure Context & Metadata

The playbook queries the Azure Instance Metadata Service (IMDS) at http://169.254.169.254 to retrieve:

  • The Azure VM Name.

  • The Resource Group.

  • The Subscription ID.

  • The attached Data Disk name.

This information is critical for the snapshotting and tagging phases later in the process.

4. Artifact Retrieval

  • Source: AWS S3 Bucket (rhapsody-engine-installer-distribution).

  • Action: Downloads the specific version installer (rhapsody-linux-x64.sh) to the upgrade directory.

  • Authentication: Uses AWS Access Keys injected securely via GitHub Secrets.

5. Service Stoppage & Safety Snapshots

  • Stop Service: The rhapsody service is stopped.

  • Snapshot Logic (Conditional):

    • If the input SNAPSHOT_DATA_VOLUMES was set to true:

    • The playbook triggers an Azure Managed Disk Snapshot of the Rhapsody data volume.

    • Tagging: The snapshot is tagged with rhapsody_version_before_upgrade for easy identification.

6. Execution & Upgrade

  • Installer: Runs the rhapsody.sh installer in headless mode using the generated response.data file.

  • Post-Config: If upgrading to v7+, it applies specific logback.xml configurations for audit events.

7. Startup & Health Check

  • Start Service: The rhapsody service is started.

  • Verification: The playbook polls the local login page (https://localhost:8444/rhapsody/login/ViewLogin.action).

  • Criteria: It waits (up to 20 minutes) for a HTTP 200 OK response. If the engine fails to start or respond, the playbook fails.

8. Azure Inventory Update

Once the application is healthy, the playbook updates the Azure Control Plane to reflect the change.

  • Tagging: It updates the Tags on the Azure VM resource.

  • Tag Name: RhapsodyVersion is updated to the new version number.

  • Note: This allows Azure Portal and CLI queries to report the correct installed version without logging into the VM.

9. Cleanup

The /data/orionhealth/upgrade/ directory is deleted to save disk space and remove the installer binary.