Chapter 2. Installation

2.1. Prerequisites

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:

  • Deploying solutions from the AWS Marketplace
  • Elastic Compute Cloud (EC2) instances
  • Elastic Block Store (EBS) volumes
  • Elastic File Storage (EFS)
  • AWS Virtual Private Clouds (VPCs)

    • Subnets
    • Route Tables
    • Security Groups
    • Load Balancers
  • Network Design
  • Hub-and-spoke networking designs
  • VPC Peering
  • Class Inter-Domain Routing (CIDR) blocks
  • Transit routing
  • AWS CloudWatch
  • SSH
  • RDS
  • AWS SecretsManager

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

2.1.1. Policies and permissions

Your AWS account must have the following Identity and Access Management (IAM) permissions to create and manage Ansible Automation Platform deployments as well as the resources described in Application architecture.

Your AWS account must also be licensed to deploy Ansible Automation Platform from AWS Marketplace.

The application can fail to deploy if your IAM policies restrict deployment and management of these resources.

The application has two deployment options:

  1. Deployment with new VPC
  2. Deployment with existing VPC

The following table contains a list of necessary IAM policies:

For deployment with a new VPCFor deployment with an existing VPC
  • Managed Policies

    • AWSMarketplaceFullAccess
  • Managed Policies

    • AWSMarketplaceFullAccess
  • CloudFormation inline IAM policies

    • cloudformation:DeleteStack
    • cloudformation:CreateUploadBucket
    • cloudformation:CreateStack
    • cloudformation:UpdateStack
    • cloudformation:GetTemplateSummary
    • cloudformation:ListStacks
    • cloudformation:GetStackPolicy
    • cloudformation:DescribeStacks
    • cloudformation:ListStackResources
    • cloudformation:DescribeStackEvents
  • CloudFormation inline IAM policies

    • cloudformation:DeleteStack
    • cloudformation:CreateUploadBucket
    • cloudformation:CreateStack
    • cloudformation:UpdateStack
    • cloudformation:GetTemplateSummary
    • cloudformation:ListStacks
    • cloudformation:GetStackPolicy
    • cloudformation:DescribeStacks
    • cloudformation:ListStackResources
    • cloudformation:DescribeStackEvents
  • S3 inline IAM policies

    • s3:CreateBucket
    • s3:PutObject
    • s3:GetObject
  • S3 inline IAM policies

    • s3:CreateBucket
    • s3:PutObject
    • s3:GetObject
  • IAM inline IAM policies

    • iam:DetachRolePolicy
    • iam:RemoveRoleFromInstanceProfile
    • iam:DeleteInstanceProfile
    • iam:DeleteRolePolicy
    • iam:CreateRole
    • iam:PutRolePolicy
    • iam:DeleteRole
    • iam:AttachRolePolicy
    • iam:CreateInstanceProfile
    • iam:AddRoleToInstanceProfile
    • iam:PassRole
    • iam:ListRoles
    • iam:GetRolePolicy
    • iam:TagRole
  • IAM inline IAM policies

    • iam:DetachRolePolicy
    • iam:RemoveRoleFromInstanceProfile
    • iam:DeleteInstanceProfile
    • iam:DeleteRolePolicy
    • iam:CreateRole
    • iam:PutRolePolicy
    • iam:DeleteRole
    • iam:AttachRolePolicy
    • iam:CreateInstanceProfile
    • iam:AddRoleToInstanceProfile
    • iam:PassRole
    • iam:ListRoles
    • iam:GetRolePolicy
    • iam:TagRole
  • SecretsManager inline IAM policies

    • secretsmanager:DeleteSecret
    • secretsmanager:GetSecretValue
    • secretsmanager:GetRandomPassword
    • secretsmanager:CreateSecret
    • secretsmanager:TagResource
    • secretsmanager:PutSecretValue
  • SecretsManager inline IAM policies

    • secretsmanager:DeleteSecret
    • secretsmanager:GetSecretValue
    • secretsmanager:GetRandomPassword
    • secretsmanager:CreateSecret
    • secretsmanager:TagResource
    • secretsmanager:PutSecretValue
  • RDS inline IAM policies

    • rds:DeleteDBSubnetGroup
    • rds:DeleteDBInstance
    • rds:CreateDBSubnetGroup
    • rds:AddTagsToResource
    • rds:CreateDBInstance
    • rds:DescribeDBSubnetGroups
    • rds:DescribeDBInstances
  • RDS inline IAM policies

    • rds:DeleteDBSubnetGroup
    • rds:DeleteDBInstance
    • rds:CreateDBSubnetGroup
    • rds:AddTagsToResource
    • rds:CreateDBInstance
    • rds:DescribeDBSubnetGroups
    • rds:DescribeDBInstances
  • Elastic File System inline IAM policies

    • elasticfilesystem:DeleteFileSystem
    • elasticfilesystem:DeleteMountTarget
    • elasticfilesystem:DeleteAccessPoint
    • elasticfilesystem:CreateFileSystem
    • elasticfilesystem:CreateAccessPoint
    • elasticfilesystem:CreateMountTarget
    • elasticfilesystem:DescribeFileSystems
    • elasticfilesystem:DescribeFileSystemPolicy
    • elasticfilesystem:DescribeBackupPolicy
    • elasticfilesystem:DescribeLifecycleConfiguration
    • elasticfilesystem:DescribeAccessPoints
    • elasticfilesystem:DescribeMountTargets
  • Elastic File System inline IAM policies

    • elasticfilesystem:DeleteFileSystem
    • elasticfilesystem:DeleteMountTarget
    • elasticfilesystem:DeleteAccessPoint
    • elasticfilesystem:CreateFileSystem
    • elasticfilesystem:CreateAccessPoint
    • elasticfilesystem:CreateMountTarget
    • elasticfilesystem:DescribeFileSystems
    • elasticfilesystem:DescribeFileSystemPolicy
    • elasticfilesystem:DescribeBackupPolicy
    • elasticfilesystem:DescribeLifecycleConfiguration
    • elasticfilesystem:DescribeAccessPoints
    • elasticfilesystem:DescribeMountTargets
  • EC2 inline IAM policies

    • ec2:RevokeSecurityGroupEgress
    • ec2:RevokeSecurityGroupIngress
    • ec2:DescribeKeyPairs
    • ec2:CreateSecurityGroup
    • ec2:DescribeSecurityGroups
    • ec2:DeleteSecurityGroup
    • ec2:CreateTags
    • ec2:AuthorizeSecurityGroupEgress
    • ec2:AuthorizeSecurityGroupIngress
    • ec2:DescribeInstances
    • ec2:CreateVpc
    • ec2:DescribeVpcs
    • ec2:DeleteVpc
    • ec2:CreateSubnet
    • ec2:DeleteSubnet
    • ec2:DescribeSubnets
    • ec2:DeleteSubnetCidrReservation
    • ec2:AssociateSubnetCidrBlock
    • ec2:DisassociateSubnetCidrBlock
    • ec2:CreateSubnetCidrReservation
    • ec2:GetSubnetCidrReservations
    • ec2:DescribeAvailabilityZones
    • ec2:CreateRouteTable
    • ec2:DeleteRouteTable
    • ec2:CreateRoute
    • ec2:DeleteRoute
    • ec2:CreateInternetGateway
    • ec2:DeleteInternetGateway
    • ec2:DescribeInternetGateways
    • ec2:AttachInternetGateway
    • ec2:DetachInternetGateway
    • ec2:AssociateRouteTable
    • ec2:DescribeRouteTables
    • ec2:DisassociateRouteTable
    • ec2:ModifyVpcAttribute
    • ec2:DescribeAccountAttributes
    • ec2:DescribeAddresses
    • ec2:AssociateAddress
    • ec2:DisassociateAddress
    • ec2:DescribeAddressesAttribute
    • ec2:ModifyAddressAttribute
    • ec2:AssociateNatGatewayAddress
    • ec2:DisassociateNatGatewayAddress
    • ec2:CreateNatGateway
    • ec2:DeleteNatGateway
    • ec2:DescribeNatGateways
    • ec2:AllocateAddress
    • ec2:ReleaseAddress
  • EC2 inline IAM policies

    • ec2:RevokeSecurityGroupEgress
    • ec2:RevokeSecurityGroupIngress
    • ec2:DescribeKeyPairs
    • ec2:CreateSecurityGroup
    • ec2:DescribeSecurityGroups
    • ec2:DeleteSecurityGroup
    • ec2:CreateTags
    • ec2:AuthorizeSecurityGroupEgress
    • ec2:AuthorizeSecurityGroupIngress
    • ec2:DescribeInstances
  • AutoScaling inline IAM policies

    • autoscaling:CreateLaunchConfiguration
    • autoscaling:CreateAutoScalingGroup
    • autoscaling:DeleteLaunchConfiguration
    • autoscaling:UpdateAutoScalingGroup
    • autoscaling:DeleteAutoScalingGroup
    • autoscaling:DescribeAutoScalingGroups
    • autoscaling:DescribeLaunchConfigurations
    • autoscaling:DescribeScalingActivities
    • autoscaling:DescribeAutoScalingInstances
  • AutoScaling inline IAM policies

    • autoscaling:CreateLaunchConfiguration
    • autoscaling:CreateAutoScalingGroup
    • autoscaling:DeleteLaunchConfiguration
    • autoscaling:UpdateAutoScalingGroup
    • autoscaling:DeleteAutoScalingGroup
    • autoscaling:DescribeAutoScalingGroups
    • autoscaling:DescribeLaunchConfigurations
    • autoscaling:DescribeScalingActivities
    • autoscaling:DescribeAutoScalingInstances
  • ElasticLoadBalancing inline IAM policies

    • elasticloadbalancing:CreateTargetGroup
    • elasticloadbalancing:ModifyTargetGroupAttributes
    • elasticloadbalancing:DeleteTargetGroup
    • elasticloadbalancing:AddTags
    • elasticloadbalancing:CreateLoadBalancer
    • elasticloadbalancing:ModifyLoadBalancerAttributes
    • elasticloadbalancing:DescribeTargetGroups
    • elasticloadbalancing:DescribeListeners
    • elasticloadbalancing:CreateListener
    • elasticloadbalancing:DeleteListener
    • elasticloadbalancingv2:DeleteLoadBalancer
    • elasticloadbalancingv2:DescribeLoadBalancers
  • ElasticLoadBalancing inline IAM policies

    • elasticloadbalancing:CreateTargetGroup
    • elasticloadbalancing:ModifyTargetGroupAttributes
    • elasticloadbalancing:DeleteTargetGroup
    • elasticloadbalancing:AddTags
    • elasticloadbalancing:CreateLoadBalancer
    • elasticloadbalancing:ModifyLoadBalancerAttributes
    • elasticloadbalancing:DescribeTargetGroups
    • elasticloadbalancing:DescribeListeners
    • elasticloadbalancing:CreateListener
    • elasticloadbalancing:DeleteListener
    • elasticloadbalancingv2:DeleteLoadBalancer
    • elasticloadbalancingv2:DescribeLoadBalancers
  • SNS inline IAM policies

    • sns:ListTopics
  • SNS inline IAM policies

    • sns:ListTopics

2.1.2. Creating an EC2 pair

An SSH key pair is required to set up Ansible Automation Platform from AWS Marketplace. You can use an existing key pair or create a new one. If you have an existing key pair, then you can skip this step.

Procedure

  1. In the AWS Console, navigate to EC2.
  2. In the Network and Security section, click Key Pairs.
  3. Click Create key pair.
  4. Fill out the fields in the input form.

    • Use ED25519 as the key pair type.
    • Use PEM as the key file format.
  5. Click Create key pair.
  6. The private key will download automatically to your /downloads folder. Apply appropriate local file permissions to secure the key file.

2.2. AWS Marketplace

Public Offer

Ansible Automation Platform from AWS Marketplace can be obtained directly from the AWS Marketplace. Follow these steps to purchase and deploy the public offer.

Procedure

  1. In the AWS Console, navigate to AWS Marketplace Subscriptions.
  2. In the navigation bar, click Discover Products.
  3. Click the listing for Red Hat Ansible Automation Platform 2 - Up to 100 Managed Nodes.
  4. Click Continue to Subscribe.
  5. Click Continue to Configuration.
  6. Select the appropriate fulfillment options.

    • Note that some selectors can have only one option.
  7. In the Fulfillment option field, ensure Ansible Platform CloudFormations Topology is selected.
  8. In the Software version field, select the latest available version from the list.
  9. In the Region field, select the region with your EC2 key pair. The CloudFormation stack deploys in the same region.
  10. Click Continue to Launch.
  11. In the Choose Action field, select Launch CloudFormation.
  12. Click Launch.

    • This opens the CloudFormation create stack page, which is already preconfigured.
  13. Next, follow the instructions in Application deployment for detailed guidance about how to configure the deployment using this form.

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 and deploy the solution.

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.
  3. After accepting the offer terms, click Continue to Configuration.
  4. Select the appropriate fulfillment options.

    • Note that some selectors can have only one option.
  5. In the Fulfillment option field, ensure Ansible Platform CloudFormations Topology is selected.
  6. In the Software version field, select the latest available version from the list.
  7. In the Region field, select the region with your EC2 key pair. The CloudFormation stack deploys in the same region.
  8. Click Continue to Launch.
  9. In the Choose Action field, select Launch CloudFormation.
  10. Click Launch.

    • This opens the CloudFormation create stack page, which is already preconfigured.
  11. Next, follow the instructions in Application deployment for detailed guidance about how to configure the deployment using this form.
Note

If you are accepting terms for the Ansible Automation Platform foundation offer, then accept the discount rate for three virtual machines. All Ansible Automation Platform foundation deployments use three VMs.

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 will directly correlate to the number of licensed managed active nodes that you have purchased.

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

2.3. Application deployment

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.

2.3.1. Deploying an application with a new VPC

Note

The following procedure assumes that you have a marketplace offer. The instructions are a continuation from AWS Marketplace. Complete the procedure in that section before continuing with this section.

This procedure creates a new VPC network and deploys the application in the created VPC.

Procedure

  1. For Step 1, on the Create stack page, click Next.
  2. For Step 2, on the Specify stack details page

    1. In the Stack name field, enter a unique stack name.
    2. In the EC2 KeyPair field, select your previously created EC2 keypair.
    3. In the Select VPC field, select New.
    4. In the New Network Configuration section, fill the following fields

      • In the VPC CIDR Range, enter the CIDR range to use for the new VPC. Example: 192.168.0.0/16
      • In the Public Subnet 1 CIDR Range, enter the CIDR range to use for the first public subnet, for example, 192.168.0.0/24
      • In the Public Subnet 2 CIDR Range, enter the CIDR range to use for the second public subnet, for example, 192.168.1.0/24
      • In the Private Subnet 1 CIDR Range, enter the CIDR range to use for the first private subnet, for example, 192.168.2.0/24
      • In the Private Subnet 2 CIDR Range, enter the CIDR range to use for the second private subnet, for example, 192.168.3.0/24

        Important

        It is crucial to ensure the CIDR ranges provided for your subnets are within your VPC CIDR range and do not overlap with each other to avoid CIDR collisions.

        You can look at the default subnet CIDR ranges as a point of reference.

    5. Ignore the fields under the Existing network configuration section.
  3. Click Next to move to Step 3.
  4. For Step 3, on the Configure stack options page, no changes are necessary.

    • All configurations are optional or have the correct default values.
  5. Click Next to move to Step 4.
  6. For Step 4, on the Review page, scroll to the bottom.

    • In the Capabilities section, check to acknowledge that CloudFormation can create IAM resources.
  7. Click Submit.
  8. The application begins provisioning.

    • It can take some time for the infrastructure and application to fully provision.

If you want to modify your CIDR ranges post deployment, your current deployment must be deleted, then follow the instructions in Deploying an application with an existing VPC.

2.3.2. Deploying an application with an existing VPC

Note

The following procedure assumes that you have a marketplace offer. The instructions are a continuation from AWS Marketplace. Complete the procedure in that section before continuing with this section.

The following procedure uses an existing VPC network to deploy an application.

Procedure

  1. For Step 1, on the Create stack page, click Next.
  2. For Step 2, on the Specify stack details page

    1. In the Stack name field, enter a unique stack name.
    2. In the EC2 KeyPair field, select your previously created EC2 keypair.
    3. In the Select VPC field, select Existing.
    4. Ignore the fields under the New network configuration section.
    5. In the Existing network configuration section, fill the following fields

      • In the Which VPC ID should this be deployed to? field, enter the VpcId of your existing Virtual Private Cloud (VPC), for example, vpc-01234567890abcdef
      • In the Existing VPC CIDR Range, enter the CIDR Range of your existing Virtual Private Cloud (VPC), for example, 192.168.0.0/16
      • In the Existing Private Subnet 1 ID, enter the ID of your first existing private subnet, for example, subnet-077dd9969c32371f7
      • In the Existing Private Subnet 2 ID, enter the ID of your second existing private subnet, for example, subnet-077dd9969c32371f7

        Note that copying and pasting these from the AWS console introduces hidden characters, and can cause the entries to fail.

  3. Click Next to move to Step 3.
  4. For Step 3, on the Configure stack options page, no changes are necessary.

    • All configurations are optional or have the correct default values.
  5. Click Next to move to Step 4.
  6. For Step 4, on the Review page, scroll to the bottom.

    • In the Capabilities section, check to acknowledge that CloudFormation can create IAM resources.
  7. Click Submit.
  8. The application begins provisioning.

    • It can take some time for the infrastructure and application to fully provision.

2.4. Deployment information

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

2.4.1. Retrieving the administration password

Use the following procedure to retrieve the administration password.

Procedure

  1. In the AWS console, navigate to AWS Secrets Manager.

    • Ensure you are in the correct region
  2. Filter with the name of the deployment. The administration secret is named <DeploymentName>-aap-admin-secret.

    • Replace <DeploymentName> with the name of your CloudFormation stack
  3. Click on the administration secret name
  4. In the Secret value section, click Retrieve secret value.
  5. The administration username and password are displayed.

2.4.2. Retrieving the load balancer addresses

Use the following procedure to retrieve the controller and hub load balancer details.

Procedure

  1. In the AWS UI, navigate to the CloudFormation UI.

    • Ensure you are in the correct region.
  2. Select the deployment name under the Stack name column.
  3. In the pane that opens, select the Resources tab.

    • Ensure Flat view is selected.
  4. In the Resources tab search bar, search for LoadBalancer.
  5. Click the Physical ID of the load balancers to open the load balancers page, with the proper load balancer preselected.
  6. Click on the preselected load balancer to get further detailed information about the load balancer.

2.5. Create credentials for the Command Generator

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.

Note

You must use the default profile name in the credentials file. The Command generator does not recognize any other name. For more information, read the Command generator - AWS Credentials File technical note.

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:

  • /home/user/project/extra_vars.yaml
[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:
  • /home/user/project/my_credentials
[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