Chapter 3. Deploying extension nodes

The foundation stack is deployed with two automation controller nodes and one automation hub node by default. You can add execution nodes to scale out Ansible Automation Platform from AWS Marketplace. Extension node offers can be mixed and matched together to scale up and out the Ansible Automation Platform deployment.

You must create a backup of the Ansible Automation Platform deployment before deploying new extension nodes.

The procedure contains the following steps:

  1. Decide the offer type for the extension nodes.
  2. Pull the ansible-on-clouds-ops container image.
  3. Ensure the minimum permissions are met to manage extension nodes.
  4. Generate data files by running the ansible-on-clouds-ops container.
  5. Populate the data file.
  6. Run the ansible-on-clouds-ops container to deploy extension nodes.

Prerequisites

  • Linux or macOS system (where the ansible-on-clouds-ops container image will run).
  • Docker

3.1. Deciding the offer type

The following table lists the offer types and the corresponding AWS instance types. Depending on the workload needs, you can choose a more suitable offer type for the extension nodes.

Offer TypeAWS Instance Type

100

m5.large

200

m5.xlarge

400

m5.2xlarge

3.2. Getting an Extension Node Subscription

Public Offer

Ansible Automation Platform from AWS Marketplace can be obtained directly from the AWS Marketplace. Follow these steps to purchase an extension node subscription.

Procedure

  1. In the AWS Console, navigate to AWS Marketplace Subscriptions.
  2. In the navigation bar, click Discover Products.
  3. Click one of the listings for Red Hat Ansible Automation Platform 2 Extension - Up to 100|200|400 Managed Nodes. Whichever is suitable for your workload needs.
  4. Click Continue to Subscribe.
  5. Read terms, if you agree to them, click Accept Terms.
  6. You should shortly be subscribed to an extnesion node offer.

Private Offer

If you have worked with Red Hat Sales to enable a private offer of Ansible Automation Platform from AWS Marketplace, follow these steps to accept your offer.

Procedure

  1. Visit your Private Offer with the URL link provided by your Red Hat Sales representative.
  2. Click Accept Terms to subscribe to the AMI Private Offer named Ansible Automation Platform from AWS Marketplace.
Note

If you are accepting terms for Ansible Automation Platform extension nodes, then assign the number of virtual machines arranged with your Red Hat Sales representative. The number of VMs directly correlates to the number of licensed managed active nodes that you have purchased.

After subscribing, the offer is also listed in your AWS Marketplace Subscriptions.

3.3. Pulling the ansible-on-clouds-ops container image

Pull the Docker image for the Ansible on Clouds operational container with the same tag as the version you are deploying to.

Note

Before pulling the docker image, ensure you are logged in to registry.redhat.io using docker. Use the following command to login to registry.redhat.io. 

$ docker login registry.redhat.io

For more information about registry login, see Registry Authentication

For example, if your foundation deployment version is 2.4.20230630-00, you must pull the operational image with tag 2.4.20230630 to deploy extension nodes to the foundation stack.

Use the following commands: 

$ export IMAGE=registry.redhat.io/ansible-on-clouds/ansible-on-clouds-ops-rhel9:2.4.20230630
$ docker pull $IMAGE --platform=linux/amd64

3.4. IAM minimum permissions

You must have the following policies to manage both adding and removing the extension nodes. 

required-roles:
  ec2:
    actions:
      - ec2:DeleteTags
      - ec2:DescribeAvailabilityZones
      - ec2:DescribeAccountAttributes
      - ec2:DeleteLaunchTemplate
      - ec2:DescribeLaunchTemplates
      - ec2:DescribeTags
      - ec2:CreateTags
      - ec2:DescribeLaunchTemplateVersions
      - ec2:RunInstances
      - ec2:CreateLaunchTemplateVersion
      - ec2:CreateLaunchTemplate
      - ec2:DescribeVpcs
      - ec2:DescribeInstanceTypes
      - ec2:DescribeSubnets
      - ec2:DescribeInstances
      - ec2:DescribeRegions
    resources:
      - "*"
  iam:
    actions:
      - iam:PassRole
      - iam:GetRole
      - iam:GetInstanceProfile
      - iam:GetRolePolicy
    resources:
      - "*"
  autoscaling:
    actions:
      - autoscaling:DescribeLaunchConfigurations
      - autoscaling:DescribeAutoScalingGroups
      - autoscaling:UpdateAutoScalingGroup
      - autoscaling:DescribeInstanceRefreshes
      - autoscaling:DeleteTags
      - autoscaling:DescribeTags
      - autoscaling:DescribeLifecycleHooks
      - autoscaling:StartInstanceRefresh
      - autoscaling:DisableMetricsCollection
      - autoscaling:CreateOrUpdateTags
      - autoscaling:DeleteAutoScalingGroup
      - autoscaling:CreateAutoScalingGroup
    resources:
      - "*"
  cloudformation:
    actions:
      - cloudformation:DescribeStackEvents
      - cloudformation:ListStackResources
      - cloudformation:ListStacks
      - cloudformation:DescribeStacks
      - cloudformation:GetTemplate
    resources:
      - "*"
  elasticloadbalancing:
    actions:
      - elasticloadbalancing:DescribeLoadBalancers
      - elasticloadbalancing:DescribeTargetGroups
    resources:
      - "*"
  s3:
    actions:
      - s3:GetBucketLocation
      - s3:DeleteObject
      - s3:PutObject
    resources:
      - "*"
  ssm:
    actions:
      - ssm:StartSession
      - ssm:SendCommand
      - ssm:TerminateSession
    resources:
      - "*"

3.5. Generating data files by running the ansible-on-clouds-ops container

The following commands generate the required data file. These commands create a directory, and an empty data template that, when populated, is used during the deployment of the extension nodes.

Procedure

  1. Create a folder to hold the configuration files. 

    $ mkdir command_generator_data

  2. Populate the command_generator_data folder with the configuration file template.

    Note

    On Linux, any file or directory created by the command generator is owned by root:root by default. To change the ownership of the files and directories, you can run the sudo chmod command after the files are created. For more information, read Command generator - Linux files owned by root. 

    $ docker run --rm -v $(pwd)/command_generator_data:/data $IMAGE \
command_generator_vars aws_add_extension_nodes \
--output-data-file /data/extra_vars.yml

  3. When you have run these commands, a command_generator_data/extra_vars.yml template file is created. This template file resembles the following: 

    # Create
aws_add_extension_nodes:
  ansible_config_path:
  cloud_credentials_path:
  deployment_name:
  extra_vars:
    aws_autoscaling_group_name:
    aws_extension_node_subscription:
    aws_launch_template_name:
    aws_offer_type:
    aws_region:
    aws_ssm_bucket_name:
    seller_name:

3.6. Populating the data file

You must populate the data file before triggering the operation. The variables listed in the data file are defined below.

  • ansible_config_path (Optional) is a value that overrides the default Ansible configuration used to run the playbook.
  • cloud_credentials_path is the path to your AWS credentials file. For example, ~/.aws/credentials
  • deployment_name is the name of the foundation deployment. This is the same name you used when you deployed the foundation.
  • aws_autoscaling_group_name is the name of the AWS AutoScaling Group to create for the extension nodes.
  • aws_extension_node_subscription is a boolean value either true or false specifying whether or not you have an extension node subscription
  • aws_launch_template_name is the name of the AWS EC2 launch template to create.
  • aws_offer_type is the offer type of the extension nodes. This must be 100, 200, or 400.
  • aws_region is the region where the foundation deployment is located.

  • aws_ssm_bucket_name is the name of the S3 bucket where temporary configuration files for the AWS SSM are stored. You can use an existing bucket or create a new one.

    Note

    The aws_ssm_bucket_name parameter is ONLY used to store temporary config files. It does NOT need to be saved for use in other playbooks. Any valid existing bucket can be used. For more information on creating S3 buckets, read AWS Creating A Bucket in the AWS documentation.

  • seller_name (Optional) is used to designate the AWS Marketplace Seller. The default value is redhatinc. If you are based in EMEA and purchased this offering through the redhatlimited AWS Marketplace seller, ensure that this value is set to redhatlimited.

After populating the data file, it resembles the following:

The values are provided as examples.

Note

The optional values ansible_config_path and seller_name in this data file example have been removed. If you do not wish to use these optional values and want to use the default values for these variables, you 'must' also remove them for your data file like it was done in the example below. If you wish to use these optional variables, they 'must' be included in the data file and be assigned a value. 

aws_add_extension_nodes:
  cloud_credentials_path: ~/.aws/credentials
  deployment_name: AnsibleAutomationPlatform
  extra_vars:
    aws_autoscaling_group_name: AnsibleAutomationPlatform-ext-asg1-100
    aws_extension_node_subscription: true
    aws_launch_template_name: AnsibleAutomationPlatform-ext-lt1-100
    aws_offer_type: "100"
    aws_region: us-east-1
    aws_ssm_bucket_name: aap-ssm-bucket

3.7. Deploying the extension nodes

Procedure

  1. To deploy the extension nodes, run the command generator to generate the CLI command. 

    $ docker run --rm -v $(pwd)/command_generator_data:/data $IMAGE command_generator --data-file /data/extra_vars.yml

    Provides the following command: 

    -----------------------------------------------
docker run --rm --env PLATFORM=AWS -v ~/.aws/credentials:/home/runner/.aws/credentials:ro \
--env ANSIBLE_CONFIG=../aws-ansible.cfg --env DEPLOYMENT_NAME=AnsibleAutomationPlatform \
--env GENERATE_INVENTORY=true  $IMAGE redhat.ansible_on_clouds.aws_add_extension_nodes \
-e 'aws_foundation_stack_name=AnsibleAutomationPlatform aws_region=us-east-1 \
aws_launch_template_name=AnsibleAutomationPlatform-ext-lt1-100 \
aws_autoscaling_group_name=AnsibleAutomationPlatform-ext-asg1-100 \
aws_extension_node_subscription=True aws_offer_type=100 \
aws_ssm_bucket_name=aap-ssm-bucket'
===============================================

  2. Run the supplied command to add the extension nodes. 

    $ docker run --rm --env PLATFORM=AWS -v ~/.aws/credentials:/home/runner/.aws/credentials:ro \
--env ANSIBLE_CONFIG=../aws-ansible.cfg --env DEPLOYMENT_NAME=AnsibleAutomationPlatform \
--env GENERATE_INVENTORY=true  $IMAGE redhat.ansible_on_clouds.aws_add_extension_nodes \
-e 'aws_foundation_stack_name=AnsibleAutomationPlatform aws_region=us-east-1 \
aws_launch_template_name=AnsibleAutomationPlatform-ext-lt1-100 \
aws_autoscaling_group_name=AnsibleAutomationPlatform-ext-asg1-100 \
aws_extension_node_subscription=True aws_offer_type=100 \
aws_ssm_bucket_name=aap-ssm-bucket'