Completing an upgrade

After performing an Automation Suite cluster upgrade, some changes are needed to ensure a new node joins the cluster correctly through scale-out operations. To automate the changes, we recommend using the upgrade_wrapper.py script.

Preparation

Prerequisites

Make sure you meet the following requirements:

• Python 3.8 or newer must be installed on the machine on which you execute the script. For details, see Python documentation.
• Python packages are required for the script. You can install these packages using the following pip command. For details, see pip documentation.

  pip install wget requests boto3

• boto3 clients must be able to authenticate to AWS because deployment changes occur through them. You can provide credentials as environment variables or through a default profile using a shared credential file. The user must have the permission to perform the actions described in the Script behavior section.

• Ensure your RHEL version for the Auto Scaling Group (Server, Agent, etc.) is updated and matches the version you are upgrading to.

• Make sure to review the cluster_config.json file and change any boolean values marked as string ("true"/"false") to actual boolean values (true/false). For example:
  • to enable zone resilience, use "zone_resilience": true.
  • to allow the installer to create the databases, use "sql.create_db": true.
• If you upgrade from Automation Suite 2022.10 to Automation Suite 2023.4 or newer, and Orchestrator is enabled on both the old and new versions, you must set the orchestrator.block_classic_executions flag to true in the cluster_config.json file. Using the flag shows that you agree with blocking classic folders executions. Not using the flag causes the upgrade operation to fail. This parameter is not required in new installations.
• If you upgrade to Automation Suite 2023.10 or later, and Insights is enabled on both the old and new environments, you must set the insights.external_object_storage.bucket_name flag to the same bucket used for platform in the cluster_config.json file. Not using the flag causes the upgrade operation to fail. This parameter is not required in new installations.
• If you upgrade to Automation Suite 2023.10 or newer, make sure to fill in the following fields in the cluster_config.json if sql.create_db is set to true:

  sql.server_url = "<db_endpoint>"
  sql.port = "1433"
  sql.username = <SQL Username>
  sql.password = <SQL password>

Script considerations

When running the upgrade_wrapper.py script, take into consideration the fact that it performs the following operations:

• Downloads in the current folder the dependencies needed;
• Extracts information from the Automation Suite deployment stack;

• Creates a new stack containing:

  • A new Launch Template for each Auto Scaling Group present in the initial deployment with the changes needed for the new version installation flow;
  • An IAM policy attached to the IAM role used by the Automation Suite nodes that allows the DescribeStackResource operation on the current stack;
    Note: The policy is deployed only if a custom IAM role was not provided at deployment time. Otherwise you should grant the cloudformation:DescribeStackResource permission on the newly deployed stack to the IAM role used by the Automation Suite nodes.
• Updates the Auto Scaling Group to use the Launch Templates created in the new stack;
• Updates the SSM parameter containing the installer URL (optional, depending on the initial deployment template version);

• Overrides the old installer used in the initial deployment with the one used for upgrade on all nodes through an SSM Run Command. This is needed to preserve the functionality of the SSM documents already existent in the initial deployment;

  Note: The AMI update SSM document might no longer work after the Launch template update. The IAM role used by the SSM documents should be updated with the ec2:CreateLaunchTemplateVersion permission, and ec2:RunInstances permissions on the newly created Launch Templates.
• Cleans up the downloaded files.

Execution

To successfully complete an upgrade, take the following steps:

1. Download the upgrade_wrapper.py script from here.
2. Run the script in an interactive or non-interactive mode:
   • Option 1: If you run the script in an interactive mode, use the following command: python3 upgrade_wrapper.py

   • Option 2: If you run the script in a non-interactive mode, it automatically populates the following environment variables:

     • The AS_VERSION variable is populated with the Automation Suite version you used for the upgrade;
     • The parameter names in uppercase format required for a specific version. You can check the parameters in the upgrade_matrix.json object defining the dependencies needed for this process. For example, for passing the deployment region needed by the 2022.10.1 version, you must set the AS_DEPLOYMENT_REGION environment variable.