Ansible Automation Platform from AWS Marketplace is installed into infrastructure resources running within your AWS account.

Ansible Automation Platform from AWS Marketplace is designed to be private, with no public access allowed by default.

This requires customers to expose the deployed internal Application Load Balancers (ALBs) themselves pursuant to their own network requirements and security practices. Some potential ways to expose the ALBs include VPC Peering, Transit Gateway, VPN, External Load Balancers, amongst others.

All cloud infrastructure components are deployed in a Virtual Private Cloud (VPC).

Customers can choose between deploying into an existing VPC, or have the product deploy a new VPC for them. All VM instances and Cloud infrastructure have private IP addresses (allocation determined by the VPC and subnetworks specified at deployment time) by default.

All internal traffic is encrypted using self-signed certificates generated at deployment time. External traffic can also be encrypted by deploying your own certificate on the Application Load Balancers deployed by the product.

The Ansible Automation Platform software runs as containers on the deployed VM instances.

Autoscaling Groups (ASG) manage VM instances and monitor the health of each service running on the VM instances. ASGs will automatically cycle the VM instances down and replace them with new VM instances if the health check fails to respond ensuring that the Ansible Automation Platform services stay up and available to process requests.

The VM instances run a customized RedHat Enterprise Linux (RHEL) Amazon Machine Image (AMI) as their base image. This AMI is preloaded with all the required container images and packages to run the Ansible Automation Platform (automation hub, automation controller, and Execution Node components).

A shared EFS (Elastic File Store) volume is mounted into each VM instance provisioned by the product and is used for shared access to common files and resources.

A Relational Database Service (RDS) is provisioned by the product at deployment time and contains databases for both the automation controller and automation hub.

The Foundation product includes two Execution Nodes running on the same VM instances as the automation controller components (this is called a Hybrid Node configuration in Ansible Automation Platform). Additional Execution Node offerings can be purchased to increase the scale (total number of managed nodes) the Ansible Automation Platform deployment is licensed to automate. When deploying the Execution Node offerings into an existing Ansible Automation Platform Foundation deployment, additional Execution Node VM instances can be deployed and automatically connected to the automation controller of the Foundation deployment, where they immediately begin processing automation tasks.

The Ansible Automation Platform components are run as containers using the Podman container runtime on the VM instances. The Podman runtime configuration is managed as a system service using systemd to ensure uptime and availability, and restarting any failed containers automatically.

SELinux is enabled on the VM instances and is supported down to the container level.

Additional operational automations are provided by the offering, available as a separate docker container for download from registry.redhat.io. These additional operational automations include backup, restore, and upgrade.

Any Common Vulnerabilities and Exposures (CVEs) found in the RHEL OS base image, the Ansible Automation Platform containers, or any included packages are addressed during upgrade of the Ansible Automation Platform offering by swapping out the base RHEL AMI with a newer version including all required software, packages, and containers.

This is done automatically for you through the use of the included upgrade automation.

Customers can take advantage of these operational automations to simplify the operational readiness of Ansible Automation Platform within their own corporate standards freeing themselves up to focus on developing Ansible Automation to manage their own infrastructure and applications rather than spending time developing automations to manage Ansible Automation Platform.

Before you can install and register Ansible Automation Platform, you must be familiar with AWS including how services operate, how data is stored, and any privacy implications that may exist by using these services. You must also set up an account with Amazon Web Services.

You must also have an SSH key pair, or Amazon Elastic Compute Cloud (EC2) pair to setup Ansible Automation Platform from AWS Marketplace. For more information, read Creating an EC2 pair.

You must have a working knowledge of the following aspects of Amazon Web Services:

For more information about Amazon Web Services and terminology, see the AWS product documentation.

Now that you have subscribed to an offer, you can begin configuration before launching the CloudFormation Stack.

There are two ways to deploy the application.

After deploying Ansible Automation Platform, use the following procedures to retrieve information about your deployment.

You must have an AWS credentials file for all day-2 operations, such as adding and removing Extension Nodes.

The file must follow the format of the AWS credentials file for "Long-term credentials", which includes the aws_access_key_id and aws_secret_access_key variables. For further information, read AWS Command Line Interface User Guide in the AWS documentation.

An example of the credentials file format is:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

After the credentials file is created, you can use it in the command generator by passing the file path to the -c option, for example:

[default]
aws_remove_extension_nodes:
  cloud_credentials_path: ./my_credentials
  deployment_name:
  extra_vars:
    aws_autoscaling_group_name:
    aws_launch_template_name:
    aws_offer_type:
    aws_region:
    aws_ssm_bucket_name:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Command:

docker run --rm \
        -v /home/user/project:/data:ro \
        $IMAGE \
        command_generator \
        --data-file /data/extra_vars.yml

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.

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

$ docker login registry.redhat.io

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

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:
      - "*"

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.

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

After populating the data file, it resembles the following:

The values are provided as examples.

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

Pull the Docker image for the Ansible on Clouds operational container which aligns with the version of your foundation deployment.

$ docker login registry.redhat.io

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

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

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:
      - "*"

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 upgrade.

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

The values below are provided as examples.

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

When Ansible Automation Platform from AWS Marketplace is deployed, it is deployed into an isolated VPC and cannot be accessed. The following sections describe how to connect the VPC used by Ansible Automation Platform from AWS Marketplace to your existing AWS network.

When connected, you must determine how your users connect to Ansible Automation Platform.

There are many ways to enable this connectivity such as VPNs, Direct Connect, or bastion servers for private network access. You can also expose the platform with public internet access using AWS services such as a Load Balancer. How your organization configures application access on AWS is outside the scope of Red Hat’s guidelines and support for Ansible Automation Platform from AWS Marketplace. Red Hat recommends contacting Amazon Web Services for guidelines on these products and topics.

Many networking configurations are possible, but the following configurations have been validated to work with Ansible Automation Platform from AWS Marketplace by Red Hat.

Private deployments omit access from the public internet. This is the default deployment model based on the AWS architecture used by Ansible Automation Platform from AWS Marketplace.

If you use this approach you must configure VPC peering, a transit network gateway, or similar AWS networking connectivity to access Ansible Automation Platform from AWS Marketplace.

When VPC peering and routing are configured, you can access Ansible Automation Platform through a VM on a connected VPC subnet, or directly if your organization has a transit routing setup between AWS and your local networks.

Network peering is required for Ansible Automation Platform to access resources that reside on private VPCs or where transit routing between AWS and your on-premises networks exists.

Ansible Automation Platform requires peering and routing for outbound communication to perform automations against devices on your AWS networks and connected on-premise or multi-cloud networks.

AWS offers different ways to peer private networks together. This document focuses on basic network peering and routing models:

VPC Peering offers the ability to directly connect different networks within your AWS infrastructure. When two or more networks are peered, the peering only establishes the connection between the networks. You must also update routing tables to direct the networks to send traffic over the appropriate networking peer.

The following procedure lets you configure VPC peering with Ansible Automation Platform.

When you have configured the direct network peering you must configure the route tables, security groups, and Network ACLs for both VPCs for traffic to route properly.

For additional information on route tables, security groups and other networking components regarding VPC Peering, see What is VPC peering? in the AWS documentation.

Transit Gateways provide a more advanced hub-and-spoke peering model than direct VPC peering provides. When Ansible Automation Platform from AWS Marketplace is peered to this type of model, the hub has an additional peering with the CIDR range deployed for the Ansible Automation Platform from AWS Marketplace VPC. The Ansible Automation Platform from AWS Marketplace VPC can be peered to a transit gateway to participate in the peering model that this AWS service provides. Follow Instructions from AWS for configuring a transit gateway.

The default Administrator password for Ansible Automation Platform is generated randomly when Ansible Automation Platform from AWS Marketplace is deployed. Follow these steps to change the Administrator password for both automation controller and automation hub:

The default RDS database password for Ansible Automation Platform is generated randomly when Ansible Automation Platform from AWS Marketplace is deployed. Follow these steps to change the RDS password:

By default, EC2 instances are secured with a self-signed SSL/TLS certificate with a validity period of ten years. When the certificate expires or you want EC2 instances to use your own certificate, you are required to replace the SSL/TLS certificate and key.

The following procedure describes how to secure the automation hub load balancer

Updating the automation hub internal Load Balancer Listener

Updating the load balancer security group

The following procedure describes how to secure the automation controller load balancer.

Updating the automation controller internal load balancer listener

Updating the load balancer security group

Pull the Docker image for the Ansible on Clouds operational container with the same tag version as your deployment.

$ docker login registry.redhat.io

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

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

Some, but not all of the playbooks are described in this document. Here, those which are used either to retrieve information from the Ansible on Clouds deployment or to check it are described. These playbooks do not modify the deployment.

aws_add_labels

This playbook adds labels to the deployment.

$ docker run --rm $IMAGE command_generator_vars aws_add_labels

Which generates the following output:

===============================================
Playbook: aws_add_labels
Description: This playbook adds labels to the deployment.
-----------------------------------------------
Add labels to the Ansible Automation Platform from AWS Marketplace deployment.

-----------------------------------------------
Command generator template:

docker run --rm $IMAGE command_generator aws_add_labels -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'aws_region=<aws_region> aws_labels=<aws_labels>'
===============================================

The parameter aws_labels is a comma separated list of key=value pairs to add or update. For example: key1=value1,key2=value2

Launching this command by replacing the parameters generates a new command to launch and outputs:

...
PLAY RECAP *********************************************************************
localhost                  : ok=22   changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

aws_check_aoc_version

This playbook checks whether the Ansible on Cloud version is the same as the command generator container. The check is done each time a playbook is called.

$ docker run --rm $IMAGE command_generator_vars aws_check_aoc_version

Which generates the following output:

===============================================
Playbook: aws_check_aoc_version
Description: Check the operational container version matches the Ansible on Clouds version.
-----------------------------------------------
Check the operational container version matches the Ansible on Clouds version.

-----------------------------------------------
Command generator template:

docker run --rm $IMAGE command_generator aws_check_aoc_version [--ansible-config ansible_config_path>] -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'aws_region=<aws_region> aws_ssm_bucket_name=<aws_ssm_bucket_name>'
===============================================

Launching this command by replacing the parameters generates a new command to launch and outputs:

...
TASK [redhat.ansible_on_clouds.standalone_check_aoc_version : Verify operational playbook and Ansible on Clouds deployment versions] ***
fatal: [localhost]: FAILED! => {
    "assertion": "ops_version == aoc_version",
    "changed": false,
    "evaluated_to": false,
    "msg": "This operation playbook version 2.4.20230606-00 is not valid for the Ansible on Clouds deployment version 2.4.20230531-00"
}

PLAY RECAP *********************************************************************
localhost                  : ok=7    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

A failed not equal zero indicates that the Ansible on Clouds deployment version does not match the command_generator container and a different version is required for the command generator to manage that deployment.

aws_get_aoc_version

This playbook retrieves the version of the Ansible on Clouds deployment.

$ docker run --rm $IMAGE command_generator_vars aws_get_aoc_version

Which generates the following output:

===============================================
Playbook: aws_get_aoc_version
Description: Get the current Ansible on Clouds version.
-----------------------------------------------
Get the current Ansible on Clouds version.

-----------------------------------------------
Command generator template:

docker run --rm $IMAGE command_generator aws_get_aoc_version [--ansible-config ansible_config_path>] -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'aws_region=<aws_region> aws_ssm_bucket_name=<aws_ssm_bucket_name>'
===============================================

Launching this command by replacing the parameters generates a new command to launch and outputs:

...
TASK [Print version] ***********************************************************
ok: [localhost] => {
    "msg": "The AOC version is 2.4.20230531-00"
}

PLAY RECAP *********************************************************************
localhost                  : ok=5    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

aws_remove_labels

This playbook removes labels from the deployment.

$ docker run --rm $IMAGE command_generator_vars aws_remove_labels

Which generates the following output:

===============================================
Playbook: aws_remove_labels
Description: This playbook removes labels from the deployment.
-----------------------------------------------
Remove labels from the Ansible Automation Platform from AWS Marketplace deployment.

-----------------------------------------------
Command generator template:

docker run --rm $IMAGE command_generator aws_remove_labels -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'aws_region=<aws_region> aws_labels=<aws_labels>'
===============================================

The parameter aws_labels is a single key to remove. For example, key1. To remove multiple keys, run the command multiple times.

Launching this command by replacing the parameters generates a new command to launch and outputs:

...
PLAY RECAP *********************************************************************
localhost                  : ok=22   changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

Automating against the managed node allotment in the offer is provided with the following operational expectations. Automating outside of the boundaries of these criteria is not supported, but can still function depending on your automation.

If you want to scale your deployment beyond the initial number of supported managed nodes, Ansible Automation Platform from AWS Marketplace can be manually scaled using separately sold extension nodes. Extension nodes are additional compute instances that can be deployed to scale-up or scale-out depending on the immediate scaling requirements. If your requirements are for higher parallel automation operations you can select compute shapes that scale-up, while if you have a requirement to automate more nodes over time you can select compute shapes that scale out.

Extension nodes are the supported way of extending the capabilities of Ansible Automation Platform from AWS Marketplace.

Use the following procedures to ensure a smooth backup process.

aws_backup_stack:
  cloud_credentials_path: ~/.aws/credentials
  deployment_name: AnsibleAutomationPlatform
  extra_vars:
    aws_backup_iam_role_arn: arn:aws:iam::<Your AWS Account Number>:role/service-role/AWSBackupDefaultServiceRole
    aws_backup_vault_name: Default
    aws_region: us-east-1
    aws_s3_bucket: ansible-automation-platform-bucket
    aws_ssm_bucket_name: aap-ssm-bucket
    backup_prefix: aoc-backup

Use the following procedures to ensure a smooth restore process.

If you would like to restore the earlier version of your Ansible Automation Platform environment to the state it was in before the upgrade, follow the Ansible on Clouds 2.3 restore instructions.

If you have deployed extension nodes, you must take the following steps to remove the extension nodes before uninstalling the stack.

If you have added extension nodes, follow the procedures in Removing extension nodes to remove them.

It can take some time to complete the deletion.

The following procedures describes how to delete any resources left behind after an upgrade.

The following procedures describe how to delete any resources left behind when uninstalling your Ansible Automation Platform deployment, after having run a backup on it.

Tags are custom fields that you assign to an AWS resource to help organize and identify your instances. Ansible Automation Platform from AWS Marketplace supports stack-level tagging during stack deployment time. A stack-level tag, when applied to the stack itself, is also applied to all tag supported components that make up the stack.

Using the add or remove labels playbooks only updates the tags for the individual components of a stack and not the tag applied to the stack itself. Stack-level tags are never modified after deployment.

The aws_remove_labels playbook only supports removing a single AWS tag at a time. The parameter aws_labels is a single key to remove. To remove multiple keys, run the command multiple times.

Having a deployment with the same name in multiple regions will break the functionality of the add extension node, remove extension node and backup stack playbooks found in the Ansible on Clouds Ops Container. To ensure these playbooks function as expected, please ensure that Ansible Automation Platform from AWS Marketplace deployments are uniquely named across all regions.

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:

# Change the owner of the command_generator_data directory recursively
$ sudo chown -R $USER:$USER command_generator_data/

# Check the permissions
$ ls -la command_generator_data/

The command generator currently expects to use the Docker CLI in the daemon mode. The default Docker installation does not have User namespace mapping for Discretionary access control (DAC). So, for any file created by root from the container will also be owned by root on the host if the file is located in a shared volume.

You can learn more about the Linux namespaces, including the User namespace at the article The 7 most used Linux namespaces.

Upgrading Ansible Automation Platform to 2.4.20230630 updates the protocol of the listeners attached to the internal load balancers from HTTP to HTTPs. To update the listener protocol, the listener must be deleted and recreated properly. For this operation to succeed there must not have been an added resource dependancy on the listener. If there is a resource dependancy on the listener, this halts the upgrade, and the dependancy must be manually removed for the upgrade to succeed. When the upgrade has suceeded, the dependant resource can be recreated. You must revalidate any additional added networking configurations after upgrade.

API endpoints for Controller must contain a trailing slash in order for requests to go through. Automatic trailing slash redirects are not supported in this current offering of Ansible Automation Platform from AWS Marketplace. For example a request such as <controller_base_url>/api/v2/metrics times out while <controller_base_url>/api/v2/metrics/ goes through.

The command generator only supports the AWS credentials file with a default profile name.

Example of a supported AWS credentials file:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Example of an unsupported AWS credentials file:

[something_else]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Red Hat supports changes to the following options: