Introduction

Using Ansible Playbooks for the bulk upgrade of Oracle Management Agents offers several benefits, including resource optimization by minimizing the time and effort needed to upgrade agents on multiple hosts. The process provides a unified, single setup for all hosts, making the upgrade more efficient and consistent. In addition, the agent binaries required for upgrade are automatically downloaded based on the Ansible playbook script, simplifying and automating the upgrade process even more.


Some terminology used in this tutorial:
  • Management agent (agent): Collects data from the host where it is installed and sends it to Oracle Cloud Infrastructure's Observability and Management services.
  • Management Agent Cloud Service (MACS): Manages management agents and their lifecycle, enabling Oracle Cloud services to interact and collect data.

Objectives

In cases where you may want to upgrade a subset of your management agents (for example, only the agents in a test environment and not the ones in production) the management agent automatic upgrade option may not be suitable. This tutorial provides the details on setting up and executing Ansible playbooks for upgrading management agents manually across multiple hosts from a single controller host.

Prerequisites

  1. Ansible installation: Ensure Ansible (version 2.9 or above) is installed on the controller host.
    For details, see the Ansible Installation Guide.
  2. Python installation: Ensure Python3 (version 3.6 or above) is installed on all target and controller hosts.
    Refer to the Python Installation Guide.
  3. SSH capability: Ensure SSH access to all target hosts; user should be able to become root.
  4. OCI CLI installation: Install OCI CLI and create the OCI configuration on the controller host.
    For details, see:
  5. Ansible collection: Ensure the Ansible collection is configured with OCI CLI on the controller host.
    For details, see Getting Started with Ansible Collection.
  6. Linux-based operating systems running on x86-64 architecture; bulk upgrades are not supported on any other platforms.

Task 1: Plan your upgrade

  1. First, check the management agents upgrade eligibility: Log in to Oracle Cloud, navigate to Observability & Management, click Management Agents and then Agents. Select your compartment and check the agents that are eligible for upgrade.

    Description of upgradable_agents.png follows
    Description of the illustration upgradable_agents.png
    Make a note of all the host names where agents require an upgrade.

  2. Management agents are upgraded based on how they were originally installed, either using a ZIP-based method or an RPM-based method.

    To check what method was used for each agent installation, on each host you noted above where agents are eligible for upgrade, examine the /opt/oracle/mgmt_agent/agent_inst/config/security/resource/agent.package file: 

    cat /opt/oracle/mgmt_agent/agent_inst/config/security/resource/agent.package
    The agent installation method is determined by the package type: RPM indicates an RPM-based binary installation, while ZIP signifies a ZIP-based binary installation.

    Here is what the content of this file looks like for an RPM-based binary installation:
    packageArchitectureType=X86_64
    packageType=RPM

    Here is what the content of this file looks like for a ZIP-based binary installation:
    packageArchitectureType=X86_64
    packageType=ZIP

Task 2: Configure the playbooks

  1. Clone the Git Repository: 
    git clone https://github.com/oracle-quickstart/oci-management-agent.git
  2. Navigate to the Playbooks directory: 
    cd deployment/ansible-playbooks
  3. Create separate Ansible inventory files ("hosts" files) for ZIP-based agents and RPM-based agents. Edit the "hosts" file with the following:
    • target_hosts: Specify the hosts where the agents will be upgraded. List only hosts with agents of the same installation type, either ZIP-based or RPM-based.
    • target_hosts:vars: Target host-specific variables.
    • all:vars: Global variables for all hosts, including the controller host.

    Here is what the file may look like:

    Description of ansible_upg.png follows
    Description of the illustration ansible_upg.png
  4. Save your "hosts" file keeping in mind the following:
    • When upgrading RPM-based agents, the hosts file only includes hosts that have agents installed using RPM-based binaries.
    • When upgrading ZIP-based agents, the hosts file only includes hosts that have agents installed using ZIP-based binaries.
    • Avoid mixing hosts with different installation types in the hosts file
  5. Set the environment variable compartment_ocid on your controller host. This value represents the compartment for the management agent: 
    export compartment_ocid=your compartment OCID
    where the OCID is of the format similar to: ocid1.compartment.oc1.aaaaaa............xxxxxxx

Task 3: Perform the upgrade

  • For RPM-based agents upgrade, run the following on the controller host: 
    ansible-playbook -i hosts mgmt_agent_upgrade.yaml -kK
  • For ZIP-based agents upgrade, run the following on the controller host: 
    ansible-playbook -i hosts mgmt_agent_zip_upgrade.yaml -kK
    Note: The -kK option, which stands for --ask-pass and -ask-become-pass, prompts for both the SSH user password and the password to become root (defaults to SSH password).

Task 4: Verify the upgrade

  1. First, check the output of the upgrade operation. It should look similar to the following:
    Description of verify_upg.png follows
    Description of the illustration verify_upg.png
  2. Log in to Oracle Cloud and:

Acknowledgements

  • Authors - Sandeep Kumar (O&M Principal Product Manager), Nirav Gandhi (O&M Software Development Director), Madhavan Arnisethangaraj (O&M Principal Member Technical Staff)
  • Contributors - Daniela Hansell (O&M Director)

More Learning Resources