Chapter 3. Installing Red Hat Ansible Automation Platform components on a single machine

You can install Red Hat Ansible Automation Platform components on a single machine in one of the following supported scenarios.

3.1. Installing automation controller with a database on the same node

You can use these instructions to install a standalone instance of automation controller with a database on the same node, or a non-installer managed database. This scenario includes installation of automation controller, including the web frontend, REST API backend, and database on a single machine. It installs PostgreSQL, and configures the automation controller to use that as its database. This is considered the standard automation controller installation scenario.

3.1.1. Prerequisites

Warning

You may experience errors if you do not fully upgrade your RHEL nodes prior to your Ansible Automation Platform installation.

3.1.2. Editing the Red Hat Ansible Automation Platform installer inventory file

You can use the Red Hat Ansible Automation Platform installer inventory file to specify your installation scenario.

Procedure

  1. Navigate to the installer

    1. [bundled installer]

      $ cd ansible-automation-platform-setup-bundle-<latest-version>
    2. [online installer]

      $ cd ansible-automation-platform-setup-<latest-version>
  2. Open the inventory file with a text editor.
  3. Edit inventory file parameters to specify your installation scenario. Follow the example below.

3.1.3. Example Red Hat Ansible Automation Platform single node inventory file

This example describes how you can populate the inventory file for a single node installation of automation controller.

Important
  • Do not use special characters for pg_password. It may cause the setup to fail.
  • Enter your Red Hat Registry Service Account credentials in registry_username and registry_password to link to the Red Hat container registry.
[automationcontroller]
controller.example.com 1

[database]

[all:vars]
admin_password='<password>'

pg_host=''
pg_port=''

pg_database='awx'
pg_username='awx'
pg_password='<password>'

registry_url='registry.redhat.io'
registry_username='<registry username>'
registry_password='<registry password>'
1
This should be set as a FQDN/IP.

3.1.4. Setup script flags and extra variables

You can also pass flags and extra variables when running the setup script to install automation controller:

Table 3.1. Flags

ArgumentDescription

-h

Show this help message and exit

-i INVENTORY_FILE

Path to Ansible inventory file (default: inventory)

-e EXTRA_VARS

Set additional Ansible variables as key=value or YAML/JSON

-b

Perform a database backup in lieu of installing

-r

Perform a database restore in lieu of installing

-k

Generate and distribute a SECRET_KEY.

When you execute the setup.sh script using this argument, by default, a new secret key is generated and distributed for the automation controller but not for the automation services catalog.

To generate and distribute a new secret key for both the automation controller and the automation services catalog, specify the variable rekey_catalog: true.

Use the -- separator to add any Ansible arguments you wish to apply. For example: ./setup.sh -i my_awesome_inventory.yml -e matburt_is_country_gold=True — -K.

Note
  • When passing -r to perform a database restore default restore path is used unless EXTRA_VARS are provided with a non-default path. See the example below that passed an EXTRA_VAR specifying the restore path:

    ./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r
  • You can force an online installation by passing -e bundle_install=false:

    $ ./setup.sh -e bundle_install=false

Table 3.2. Extra variables

VariableDescriptionDefault

upgrade_ansible_with_tower

When installing automation controller make sure Ansible is also up to date

False

create_preload_data

When installing Tower also create the Demo Org, project, credential, Job Template, etc.

True

bundle_install_folder

When installing from a bundle where to put the bundled repos

var/lib/tower-bundle

nginx_disable_https

Disable HTTPS traffic through nginx, this is useful if offloading HTTPS to a load balancer

False

nginx_disable_hsts

Disable HSTS web-security policy mechanism

False

nginx_http_port

Port to configure nginx to listen to for HTTP

80

nginx_https_port

Port to configure nginx to listen to for HTTPS

443

backup_dir

A temp location to use when backing up

/var/backups/tower/

restore_backup_file

Specify an alternative backup file to restore from

None

required_ram

The minimum RAM required to install Tower (should only be changed for test installation)

3750

min_open_fds

The minimum open file descriptions (should only be changed for test installations)

None

ignore_preflight_errors

Ignore preflight checks, useful when installing into a template or other non-system image (overrides required_ram and min_open_fds)

False

rekey_catalog

When you execute the setup.sh script using this variable set to true, by default, a new secret key is generated and distributed for both the automation controller and the automation services catalog.

False

Examples

  • To upgrade core:
./setup.sh -e upgrade_ansible_with_tower=1
  • To disable https handling at nginx:
./setup.sh -e nginx_disable_https=true
  • To specify a non-default path when restoring from a backup file:
./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r

3.1.5. Running the Red Hat Ansible Automation Platform installer setup script

You can run the setup script once you finish updating the inventory file with required parameters for installing your Private Automation Hub.

Procedure

  1. Run the setup.sh script

    $ ./setup.sh

The installation will begin.

3.1.6. Verifying automation controller installation

Once the installation completes, you can verify your automation controller has been installed successfully by logging in with the admin credentials you inserted into the inventory file.

Procedure

  1. Navigate to the IP address specified for the automation controller node in the inventory file.
  2. Log in with the Admin credentials you set in the inventory file.
Note

The automation controller server is accessible from port 80 (https://<TOWER_SERVER_NAME>/) but will redirect to port 443 so 443 needs to be available also.

Important

If the installation fails and you are a customer who has purchased a valid license for Red Hat Ansible Automation Platform, please contact Ansible via the Red Hat Customer portal at https://access.redhat.com/.

Upon a successful login to automation controller, your installation of Red Hat Ansible Automation Platform 2.2 is now complete.

3.1.6.1. Additional automation controller configuration and resources

See the following resources to explore additional automation controller configurations.

Table 3.3. Resources to configure automation controller

LinkDescription

Automation Controller Quick Setup Guide

Set up automation controller and run your first playbook

Automation Controller Administration Guide

Configure automation controller administration through customer scripts, management jobs, etc.

Configuring proxy support for Red Hat Ansible Automation Platform

Set up automation controller with a proxy server

Managing usability analytics and data collection from automation controller

Manage what automation controller information you share with Red Hat

Automation Controller User Guide

Review automation controller functionality in more detail

3.1.7. What’s next with Ansible Automation Platform 2.2

Whether you are a new Ansible Automation Platform user looking to start automating, or an existing administrator looking to migrate old Ansible content to your latest installed version of Red Hat Ansible Automation Platform, explore the next steps to begin leveraging the new features of Ansible Automation Platform 2.2:

3.1.7.1. Migrating data to Ansible Automation Platform 2.2

For platform administrators looking to complete an upgrade to the Ansible Automation Platform 2.2, there may be additional steps needed to migrate data to a new instance:

3.1.7.1.1. Migrating from legacy virtual environments (venvs) to automation execution environments

Ansible Automation Platform 2.2 moves you away from custom Python virtual environments (venvs) in favor of automation execution environments - containerized images that packages the necessary components needed to execute and scale your Ansible automation. This includes Ansible Core, Ansible Content Collections, Python dependencies, Red Hat Enterprise Linux UBI 8, and any additional package dependencies.

If you are looking to migrate your venvs to execution environments, you will (1) need to use the awx-manage command to list and export a list of venvs from your original instance, then (2) use ansible-builder to create execution environments. For more information, see the Upgrading to Automation Execution Environments guide and the Creating and Consuming Execution Environments.

3.1.7.1.2. Migrating to Ansible Engine 2.9 images using Ansible Builder

To migrate Ansible Engine 2.9 images for use with Ansible Automation Platform 2.2, the ansible-builder tool automates the process of rebuilding images (including its custom plugins and dependencies) for use with automation execution environments. For more information on using Ansible Builder to build execution environments, see the Creating and Consuming Execution Environments.

3.1.7.1.3. Migrating to Ansible Core 2.13

When upgrading to Ansible Core 2.13, you need to update your playbooks, plugins, or other parts of your Ansible infrastructure in order to be supported by the latest version of Ansible Core. For instructions on updating your Ansible content for Ansible Core 2.13 compatibility, see the Ansible-core 2.13 Porting Guide.

3.1.7.2. Scale up your automation using automation mesh

The automation mesh component of the Red Hat Ansible Automation Platform simplifies the process of distributing automation across multi-site deployments. For enterprises with multiple isolated IT environments, automation mesh provides a consistent and reliable way to deploy and scale up automation across your execution nodes using a peer-to-peer mesh communication network.

When upgrading from version 1.x to the latest version of the Ansible Automation Platform, you will need to migrate the data from your legacy isolated nodes into execution nodes necessary for automation mesh. You can implement automation mesh by planning out a network of hybrid and control nodes, then editing the inventory file found in the Ansible Automation Platform installer to assign mesh-related values to each of your execution nodes.

For instructions on how to migrate from isolated nodes to execution nodes, see the upgrade & migration guide.

For information about automation mesh and the various ways to design your automation mesh for your environment, see the Red Hat Ansible Automation Platform automation mesh guide.

3.2. Installing automation controller with an external managed database

You can use these instructions to install a standalone automation controller server on a single machine configured to communicate with a remote PostgreSQL instance as its database. This remote PostgreSQL can be a server you manage, or can be provided by a cloud service such as Amazon RDS.

3.2.1. Prerequisites

Warning

You may experience errors if you do not fully upgrade your RHEL nodes prior to your Ansible Automation Platform installation.

3.2.2. Editing the Red Hat Ansible Automation Platform installer inventory file

You can use the Red Hat Ansible Automation Platform installer inventory file to specify your installation scenario.

Procedure

  1. Navigate to the installer

    1. [bundled installer]

      $ cd ansible-automation-platform-setup-bundle-<latest-version>
    2. [online installer]

      $ cd ansible-automation-platform-setup-<latest-version>
  2. Open the inventory file with a text editor.
  3. Edit inventory file parameters to specify your installation scenario. Follow the example below.

3.2.3. Example inventory file for a standalone automation controller with an external managed database

This example describes how you can populate the inventory file to deploy an installation of automation controller with an external database.

Important
  • Do not use special characters for pg_password. It may cause the setup to fail.
  • Enter your Red Hat Registry Service Account credentials in registry_username and registry_password to link to the Red Hat container registry.
[automationcontroller]
controller.example.com  1


[database]
database.example.com

[all:vars]
admin_password='<password>'
pg_password='<password>'

pg_host='database.example.com'
pg_port='5432'

pg_database='awx'
pg_username='awx'

registry_url='registry.redhat.io'
registry_username='<registry username>'
registry_password='<registry password>'
1
This should be set as a FQDN/IP.

3.2.4. Setup script flags and extra variables

You can also pass flags and extra variables when running the setup script to install automation controller:

Table 3.4. Flags

ArgumentDescription

-h

Show this help message and exit

-i INVENTORY_FILE

Path to Ansible inventory file (default: inventory)

-e EXTRA_VARS

Set additional Ansible variables as key=value or YAML/JSON

-b

Perform a database backup in lieu of installing

-r

Perform a database restore in lieu of installing

-k

Generate and distribute a SECRET_KEY.

When you execute the setup.sh script using this argument, by default, a new secret key is generated and distributed for the automation controller but not for the automation services catalog.

To generate and distribute a new secret key for both the automation controller and the automation services catalog, specify the variable rekey_catalog: true.

Use the -- separator to add any Ansible arguments you wish to apply. For example: ./setup.sh -i my_awesome_inventory.yml -e matburt_is_country_gold=True — -K.

Note
  • When passing -r to perform a database restore default restore path is used unless EXTRA_VARS are provided with a non-default path. See the example below that passed an EXTRA_VAR specifying the restore path:

    ./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r
  • You can force an online installation by passing -e bundle_install=false:

    $ ./setup.sh -e bundle_install=false

Table 3.5. Extra variables

VariableDescriptionDefault

upgrade_ansible_with_tower

When installing automation controller make sure Ansible is also up to date

False

create_preload_data

When installing Tower also create the Demo Org, project, credential, Job Template, etc.

True

bundle_install_folder

When installing from a bundle where to put the bundled repos

var/lib/tower-bundle

nginx_disable_https

Disable HTTPS traffic through nginx, this is useful if offloading HTTPS to a load balancer

False

nginx_disable_hsts

Disable HSTS web-security policy mechanism

False

nginx_http_port

Port to configure nginx to listen to for HTTP

80

nginx_https_port

Port to configure nginx to listen to for HTTPS

443

backup_dir

A temp location to use when backing up

/var/backups/tower/

restore_backup_file

Specify an alternative backup file to restore from

None

required_ram

The minimum RAM required to install Tower (should only be changed for test installation)

3750

min_open_fds

The minimum open file descriptions (should only be changed for test installations)

None

ignore_preflight_errors

Ignore preflight checks, useful when installing into a template or other non-system image (overrides required_ram and min_open_fds)

False

rekey_catalog

When you execute the setup.sh script using this variable set to true, by default, a new secret key is generated and distributed for both the automation controller and the automation services catalog.

False

Examples

  • To upgrade core:
./setup.sh -e upgrade_ansible_with_tower=1
  • To disable https handling at nginx:
./setup.sh -e nginx_disable_https=true
  • To specify a non-default path when restoring from a backup file:
./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r

3.2.5. Running the Red Hat Ansible Automation Platform installer setup script

You can run the setup script once you finish updating the inventory file with required parameters for installing your Private Automation Hub.

Procedure

  1. Run the setup.sh script

    $ ./setup.sh

The installation will begin.

3.2.6. Verifying automation controller installation

Once the installation completes, you can verify your automation controller has been installed successfully by logging in with the admin credentials you inserted into the inventory file.

Procedure

  1. Navigate to the IP address specified for the automation controller node in the inventory file.
  2. Log in with the Admin credentials you set in the inventory file.
Note

The automation controller server is accessible from port 80 (https://<TOWER_SERVER_NAME>/) but will redirect to port 443 so 443 needs to be available also.

Important

If the installation fails and you are a customer who has purchased a valid license for Red Hat Ansible Automation Platform, please contact Ansible via the Red Hat Customer portal at https://access.redhat.com/.

Upon a successful login to automation controller, your installation of Red Hat Ansible Automation Platform 2.2 is now complete.

3.2.6.1. Additional automation controller configuration and resources

See the following resources to explore additional automation controller configurations.

Table 3.6. Resources to configure automation controller

LinkDescription

Automation Controller Quick Setup Guide

Set up automation controller and run your first playbook

Automation Controller Administration Guide

Configure automation controller administration through customer scripts, management jobs, etc.

Configuring proxy support for Red Hat Ansible Automation Platform

Set up automation controller with a proxy server

Managing usability analytics and data collection from automation controller

Manage what automation controller information you share with Red Hat

Automation Controller User Guide

Review automation controller functionality in more detail

3.2.7. What’s next with Ansible Automation Platform 2.2

Whether you are a new Ansible Automation Platform user looking to start automating, or an existing administrator looking to migrate old Ansible content to your latest installed version of Red Hat Ansible Automation Platform, explore the next steps to begin leveraging the new features of Ansible Automation Platform 2.2:

3.2.7.1. Migrating data to Ansible Automation Platform 2.2

For platform administrators looking to complete an upgrade to the Ansible Automation Platform 2.2, there may be additional steps needed to migrate data to a new instance:

3.2.7.1.1. Migrating from legacy virtual environments (venvs) to automation execution environments

Ansible Automation Platform 2.2 moves you away from custom Python virtual environments (venvs) in favor of automation execution environments - containerized images that packages the necessary components needed to execute and scale your Ansible automation. This includes Ansible Core, Ansible Content Collections, Python dependencies, Red Hat Enterprise Linux UBI 8, and any additional package dependencies.

If you are looking to migrate your venvs to execution environments, you will (1) need to use the awx-manage command to list and export a list of venvs from your original instance, then (2) use ansible-builder to create execution environments. For more information, see the Upgrading to Automation Execution Environments guide and the Creating and Consuming Execution Environments.

3.2.7.1.2. Migrating to Ansible Engine 2.9 images using Ansible Builder

To migrate Ansible Engine 2.9 images for use with Ansible Automation Platform 2.2, the ansible-builder tool automates the process of rebuilding images (including its custom plugins and dependencies) for use with automation execution environments. For more information on using Ansible Builder to build execution environments, see the Creating and Consuming Execution Environments.

3.2.7.1.3. Migrating to Ansible Core 2.13

When upgrading to Ansible Core 2.13, you need to update your playbooks, plugins, or other parts of your Ansible infrastructure in order to be supported by the latest version of Ansible Core. For instructions on updating your Ansible content for Ansible Core 2.13 compatibility, see the Ansible-core 2.13 Porting Guide.

3.2.7.2. Scale up your automation using automation mesh

The automation mesh component of the Red Hat Ansible Automation Platform simplifies the process of distributing automation across multi-site deployments. For enterprises with multiple isolated IT environments, automation mesh provides a consistent and reliable way to deploy and scale up automation across your execution nodes using a peer-to-peer mesh communication network.

When upgrading from version 1.x to the latest version of the Ansible Automation Platform, you will need to migrate the data from your legacy isolated nodes into execution nodes necessary for automation mesh. You can implement automation mesh by planning out a network of hybrid and control nodes, then editing the inventory file found in the Ansible Automation Platform installer to assign mesh-related values to each of your execution nodes.

For instructions on how to migrate from isolated nodes to execution nodes, see the upgrade & migration guide.

For information about automation mesh and the various ways to design your automation mesh for your environment, see the Red Hat Ansible Automation Platform automation mesh guide.

3.3. Installing automation hub with a database on the same node

You can use these instructions to install a standalone instance of automation hub with a database on the same node, or a non-installer managed database.

3.3.1. Prerequisites

Warning

You may experience errors if you do not fully upgrade your RHEL nodes prior to your Ansible Automation Platform installation.

3.3.2. Editing the Red Hat Ansible Automation Platform installer inventory file

You can use the Red Hat Ansible Automation Platform installer inventory file to specify your installation scenario.

Procedure

  1. Navigate to the installer

    1. [bundled installer]

      $ cd ansible-automation-platform-setup-bundle-<latest-version>
    2. [online installer]

      $ cd ansible-automation-platform-setup-<latest-version>
  2. Open the inventory file with a text editor.
  3. Edit inventory file parameters to specify your installation scenario. Follow the example below.

3.3.3. Example standalone automation hub inventory file

This example describes how you can populate the inventory file to deploy a standalone instance of automation hub.

Important
  • For Red Hat Ansible Automation Platform or automation hub: Add an automation hub host in the [automationhub] group. You cannot install automation controller and automation hub on the same node.
  • Provide a reachable IP address or fully qualified domain name (FQDN) for the [automationhub] host to ensure users can sync and install content from automation hub from a different node. Do not use 'localhost'.
  • Enter your Red Hat Registry Service Account credentials in registry_username and registry_password to link to the Red Hat container registry.
[automationcontroller]


[automationhub]
<FQDN> ansible_connection=local

[all:vars]
registry_url='registry.redhat.io'
registry_username='<registry username>'
registry_password='<registry password>'

automationhub_admin_password= <PASSWORD>

automationhub_pg_host=''
automationhub_pg_port=''

automationhub_pg_database='automationhub'
automationhub_pg_username='automationhub'
automationhub_pg_password=<PASSWORD>
automationhub_pg_sslmode='prefer'

# The default install will deploy a TLS enabled Automation Hub.
# If for some reason this is not the behavior wanted one can
# disable TLS enabled deployment.
#
# automationhub_disable_https = False
# The default install will generate self-signed certificates for the Automation
# Hub service. If you are providing valid certificate via automationhub_ssl_cert
# and automationhub_ssl_key, one should toggle that value to True.
#
# automationhub_ssl_validate_certs = False
# SSL-related variables
# If set, this will install a custom CA certificate to the system trust store.
# custom_ca_cert=/path/to/ca.crt
# Certificate and key to install in Automation Hub node
# automationhub_ssl_cert=/path/to/automationhub.cert
# automationhub_ssl_key=/path/to/automationhub.key

3.3.4. Setup script flags and extra variables

You can also pass flags and extra variables when running the setup script to install automation controller:

Table 3.7. Flags

ArgumentDescription

-h

Show this help message and exit

-i INVENTORY_FILE

Path to Ansible inventory file (default: inventory)

-e EXTRA_VARS

Set additional Ansible variables as key=value or YAML/JSON

-b

Perform a database backup in lieu of installing

-r

Perform a database restore in lieu of installing

-k

Generate and distribute a SECRET_KEY.

When you execute the setup.sh script using this argument, by default, a new secret key is generated and distributed for the automation controller but not for the automation services catalog.

To generate and distribute a new secret key for both the automation controller and the automation services catalog, specify the variable rekey_catalog: true.

Use the -- separator to add any Ansible arguments you wish to apply. For example: ./setup.sh -i my_awesome_inventory.yml -e matburt_is_country_gold=True — -K.

Note
  • When passing -r to perform a database restore default restore path is used unless EXTRA_VARS are provided with a non-default path. See the example below that passed an EXTRA_VAR specifying the restore path:

    ./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r
  • You can force an online installation by passing -e bundle_install=false:

    $ ./setup.sh -e bundle_install=false

Table 3.8. Extra variables

VariableDescriptionDefault

upgrade_ansible_with_tower

When installing automation controller make sure Ansible is also up to date

False

create_preload_data

When installing Tower also create the Demo Org, project, credential, Job Template, etc.

True

bundle_install_folder

When installing from a bundle where to put the bundled repos

var/lib/tower-bundle

nginx_disable_https

Disable HTTPS traffic through nginx, this is useful if offloading HTTPS to a load balancer

False

nginx_disable_hsts

Disable HSTS web-security policy mechanism

False

nginx_http_port

Port to configure nginx to listen to for HTTP

80

nginx_https_port

Port to configure nginx to listen to for HTTPS

443

backup_dir

A temp location to use when backing up

/var/backups/tower/

restore_backup_file

Specify an alternative backup file to restore from

None

required_ram

The minimum RAM required to install Tower (should only be changed for test installation)

3750

min_open_fds

The minimum open file descriptions (should only be changed for test installations)

None

ignore_preflight_errors

Ignore preflight checks, useful when installing into a template or other non-system image (overrides required_ram and min_open_fds)

False

rekey_catalog

When you execute the setup.sh script using this variable set to true, by default, a new secret key is generated and distributed for both the automation controller and the automation services catalog.

False

Examples

  • To upgrade core:
./setup.sh -e upgrade_ansible_with_tower=1
  • To disable https handling at nginx:
./setup.sh -e nginx_disable_https=true
  • To specify a non-default path when restoring from a backup file:
./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r

3.3.5. Running the Red Hat Ansible Automation Platform installer setup script

You can run the setup script once you finish updating the inventory file with required parameters for installing your Private Automation Hub.

Procedure

  1. Run the setup.sh script

    $ ./setup.sh

The installation will begin.

3.3.6. Verifying automation hub installation

Once the installation completes, you can verify your automation hub has been installed successfully by logging in with the admin credentials you inserted into the inventory file.

Procedure

  1. Navigate to the IP address specified for the automation hub node in the inventory file.
  2. Log in with the Admin credentials you set in the inventory file.
Important

If the installation fails and you are a customer who has purchased a valid license for Red Hat Ansible Automation Platform, please contact Ansible via the Red Hat Customer portal at https://access.redhat.com/.

Upon a successful login to automation hub, your installation of Red Hat Ansible Automation Platform 2.2 is now complete.

3.3.6.1. Additional automation hub configuration and resources

See the following resources to explore additional automation hub configurations.

Table 3.9. Resources to configure automation controller

LinkDescription

Managing user access in private automation hub

Configure user access for automation hub

Managing Red Hat Certified and Ansible Galaxy collections in automation hub

Add content to your automation hub

Publishing proprietary content collections in automation hub

Publish internally developed collections on your automation hub

3.3.7. What’s next with Ansible Automation Platform 2.2

Whether you are a new Ansible Automation Platform user looking to start automating, or an existing administrator looking to migrate old Ansible content to your latest installed version of Red Hat Ansible Automation Platform, explore the next steps to begin leveraging the new features of Ansible Automation Platform 2.2:

3.3.7.1. Migrating data to Ansible Automation Platform 2.2

For platform administrators looking to complete an upgrade to the Ansible Automation Platform 2.2, there may be additional steps needed to migrate data to a new instance:

3.3.7.1.1. Migrating from legacy virtual environments (venvs) to automation execution environments

Ansible Automation Platform 2.2 moves you away from custom Python virtual environments (venvs) in favor of automation execution environments - containerized images that packages the necessary components needed to execute and scale your Ansible automation. This includes Ansible Core, Ansible Content Collections, Python dependencies, Red Hat Enterprise Linux UBI 8, and any additional package dependencies.

If you are looking to migrate your venvs to execution environments, you will (1) need to use the awx-manage command to list and export a list of venvs from your original instance, then (2) use ansible-builder to create execution environments. For more information, see the Upgrading to Automation Execution Environments guide and the Creating and Consuming Execution Environments.

3.3.7.1.2. Migrating to Ansible Engine 2.9 images using Ansible Builder

To migrate Ansible Engine 2.9 images for use with Ansible Automation Platform 2.2, the ansible-builder tool automates the process of rebuilding images (including its custom plugins and dependencies) for use with automation execution environments. For more information on using Ansible Builder to build execution environments, see the Creating and Consuming Execution Environments.

3.3.7.1.3. Migrating to Ansible Core 2.13

When upgrading to Ansible Core 2.13, you need to update your playbooks, plugins, or other parts of your Ansible infrastructure in order to be supported by the latest version of Ansible Core. For instructions on updating your Ansible content for Ansible Core 2.13 compatibility, see the Ansible-core 2.13 Porting Guide.

3.3.7.2. Scale up your automation using automation mesh

The automation mesh component of the Red Hat Ansible Automation Platform simplifies the process of distributing automation across multi-site deployments. For enterprises with multiple isolated IT environments, automation mesh provides a consistent and reliable way to deploy and scale up automation across your execution nodes using a peer-to-peer mesh communication network.

When upgrading from version 1.x to the latest version of the Ansible Automation Platform, you will need to migrate the data from your legacy isolated nodes into execution nodes necessary for automation mesh. You can implement automation mesh by planning out a network of hybrid and control nodes, then editing the inventory file found in the Ansible Automation Platform installer to assign mesh-related values to each of your execution nodes.

For instructions on how to migrate from isolated nodes to execution nodes, see the upgrade & migration guide.

For information about automation mesh and the various ways to design your automation mesh for your environment, see the Red Hat Ansible Automation Platform automation mesh guide.

3.4. Installing automation hub with an external database

You can use these instructions to install a standalone instance of automation hub with an external managed database. This installs the automation hub server on a single machine and installs a remote PostgreSQL database using the Ansible Automation Platform installer.

3.4.1. Prerequisites

Warning

You may experience errors if you do not fully upgrade your RHEL nodes prior to your Ansible Automation Platform installation.

3.4.2. Editing the Red Hat Ansible Automation Platform installer inventory file

You can use the Red Hat Ansible Automation Platform installer inventory file to specify your installation scenario.

Procedure

  1. Navigate to the installer

    1. [bundled installer]

      $ cd ansible-automation-platform-setup-bundle-<latest-version>
    2. [online installer]

      $ cd ansible-automation-platform-setup-<latest-version>
  2. Open the inventory file with a text editor.
  3. Edit inventory file parameters to specify your installation scenario. Follow the example below.

3.4.3. Example standalone automation hub inventory file

This example describes how you can populate the inventory file to deploy a standalone instance of automation hub.

Important
  • For Red Hat Ansible Automation Platform or automation hub: Add an automation hub host in the [automationhub] group. You cannot install automation controller and automation hub on the same node.
  • Provide a reachable IP address or fully qualified domain name (FQDN) for the [automationhub] host to ensure users can sync and install content from automation hub from a different node. Do not use 'localhost'.
  • Enter your Red Hat Registry Service Account credentials in registry_username and registry_password to link to the Red Hat container registry.
[automationcontroller]


[automationhub]
<FQDN> ansible_connection=local

[database]
host2

[all:vars]
registry_url='registry.redhat.io'
registry_username='<registry username>'
registry_password='<registry password>'

automationhub_admin_password= <PASSWORD>

automationhub_pg_host=''
automationhub_pg_port=''

automationhub_pg_database='automationhub'
automationhub_pg_username='automationhub'
automationhub_pg_password=<PASSWORD>
automationhub_pg_sslmode='prefer'

# The default install will deploy a TLS enabled Automation Hub.
# If for some reason this is not the behavior wanted one can
# disable TLS enabled deployment.
#
# automationhub_disable_https = False
# The default install will generate self-signed certificates for the Automation
# Hub service. If you are providing valid certificate via automationhub_ssl_cert
# and automationhub_ssl_key, one should toggle that value to True.
#
# automationhub_ssl_validate_certs = False
# SSL-related variables
# If set, this will install a custom CA certificate to the system trust store.
# custom_ca_cert=/path/to/ca.crt
# Certificate and key to install in Automation Hub node
# automationhub_ssl_cert=/path/to/automationhub.cert
# automationhub_ssl_key=/path/to/automationhub.key

3.4.4. LDAP configuration on private automation hub

You must set the following six variables in your Red Hat Ansible Automation Platform installer inventory file to configure your private automation hub for LDAP authentication:

  • automationhub_authentication_backend
  • automationhub_ldap_server_uri
  • automationhub_ldap_bind_dn
  • automationhub_ldap_bind_password
  • automationhub_ldap_user_search_base_dn
  • automationhub_ldap_group_search_base_dn

If any of these variables are missing, the Ansible Automation installer will not complete the installation.

3.4.4.1. Setting up your inventory file variables

When you configure your private automation hub with LDAP authentication, you must set the proper variables in your inventory files during the installation process.

Prerequisites

  • Ensure that your system is running Red Hat Ansible Automation Platform 2.2.1 or later.
  • Ensure that you are using private automation hub 4.5.2 or later.

Procedure

  1. Access your inventory file according to the procedure in Editing the Red Hat Ansible Automation Platform installer inventory file.
  2. Use the following example as a guide to set up your Ansible Automation Platform inventory file:

    automationhub_authentication_backend = "ldap"
    
    automationhub_ldap_server_uri = "ldap://ldap:389"   (for LDAPs use automationhub_ldap_server_uri = "ldaps://ldap-server-fqdn")
    automationhub_ldap_bind_dn = "cn=admin,dc=ansible,dc=com"
    automationhub_ldap_bind_password = "GoodNewsEveryone"
    automationhub_ldap_user_search_base_dn = "ou=people,dc=ansible,dc=com"
    automationhub_ldap_group_search_base_dn = "ou=people,dc=ansible,dc=com"
    Note

    The following variables will be set with default values, unless you set them with other options.

    auth_ldap_user_search_scope= `SUBTREE'
    auth_ldap_user_search_filter= `(uid=%(user)s)`
    auth_ldap_group_search_scope= 'SUBTREE'
    auth_ldap_group_search_filter= '(objectClass=Group)`
    auth_ldap_group_type_class= 'django_auth_ldap.config:GroupOfNamesType'
  3. If you plan to set up extra parameters in your private automation hub (such as user groups, superuser access, mirroring, or others), proceed to the next section.

3.4.4.2. Configuring extra LDAP parameters

If you plan to set up superuser access, user groups, mirroring or other extra parameters, you can create a YAML file that comprises them in your ldap_extra_settings dictionary.

Procedure

  1. Create a YAML file that will contain ldap_extra_settings, such as the following:

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_USER_ATTR_MAP: '{"first_name": "givenName", "last_name": "sn", "email": "mail"}'
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  2. Use this example to set up a superuser flag based on membership in an LDAP group.

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_USER_FLAGS_BY_GROUP: {"is_superuser": "cn=pah-admins,ou=groups,dc=example,dc=com",}
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  3. Use this example to set up superuser access.

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_USER_FLAGS_BY_GROUP: {"is_superuser": "cn=pah-admins,ou=groups,dc=example,dc=com",}
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  4. Use this example to mirror all LDAP groups you belong to.

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_MIRROR_GROUPS: True
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  5. Use this example to map LDAP user attributes (such as first name, last name, and email address of the user).

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_USER_ATTR_MAP: {"first_name": "givenName", "last_name": "sn", "email": "mail",}
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  6. Use the following examples to grant or deny access based on LDAP group membership.

    1. To grant private automation hub access (for example, members of the cn=pah-nosoupforyou,ou=groups,dc=example,dc=com group):

      #ldapextras.yml
      ---
      ldap_extra_settings:
        AUTH_LDAP_REQUIRE_GROUP: "cn=pah-users,ou=groups,dc=example,dc=com'
      ...
    2. To deny private automation hub access (for example, members of the cn=pah-nosoupforyou,ou=groups,dc=example,dc=com group):

      #ldapextras.yml
      ---
      ldap_extra_settings:
        AUTH_LDAP_DENY_GROUP: 'cn=pah-nosoupforyou,ou=groups,dc=example,dc=com'
      ...

      Then run setup.sh -e @ldapextras.yml during private automation hub installation.

  7. Use this example to enable LDAP debug logging.

    #ldapextras.yml
    ---
    ldap_extra_settings:
      GALAXY_LDAP_LOGGING: True
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

    Note

    If it is not practical to re-run setup.sh or if debug logging is enabled for a short time, you can add a line containing GALAXY_LDAP_LOGGING: True manually to the /etc/pulp/settings.py file on private automation hub. Restart both pulpcore-api.service and nginx.service for the changes to take effect. To avoid failures due to human error, use this method only when necessary.

  8. Use this example to configure LDAP caching by setting the variable AUTH_LDAP_CACHE_TIMEOUT.

    #ldapextras.yml
    ---
    ldap_extra_settings:
      AUTH_LDAP_CACHE_TIMEOUT: 3600
    ...

    Then run setup.sh -e @ldapextras.yml during private automation hub installation.

You can view all of your settings in the /etc/pulp/settings.py file on your private automation hub.

3.4.5. Setup script flags and extra variables

You can also pass flags and extra variables when running the setup script to install automation controller:

Table 3.10. Flags

ArgumentDescription

-h

Show this help message and exit

-i INVENTORY_FILE

Path to Ansible inventory file (default: inventory)

-e EXTRA_VARS

Set additional Ansible variables as key=value or YAML/JSON

-b

Perform a database backup in lieu of installing

-r

Perform a database restore in lieu of installing

-k

Generate and distribute a SECRET_KEY.

When you execute the setup.sh script using this argument, by default, a new secret key is generated and distributed for the automation controller but not for the automation services catalog.

To generate and distribute a new secret key for both the automation controller and the automation services catalog, specify the variable rekey_catalog: true.

Use the -- separator to add any Ansible arguments you wish to apply. For example: ./setup.sh -i my_awesome_inventory.yml -e matburt_is_country_gold=True — -K.

Note
  • When passing -r to perform a database restore default restore path is used unless EXTRA_VARS are provided with a non-default path. See the example below that passed an EXTRA_VAR specifying the restore path:

    ./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r
  • You can force an online installation by passing -e bundle_install=false:

    $ ./setup.sh -e bundle_install=false

Table 3.11. Extra variables

VariableDescriptionDefault

upgrade_ansible_with_tower

When installing automation controller make sure Ansible is also up to date

False

create_preload_data

When installing Tower also create the Demo Org, project, credential, Job Template, etc.

True

bundle_install_folder

When installing from a bundle where to put the bundled repos

var/lib/tower-bundle

nginx_disable_https

Disable HTTPS traffic through nginx, this is useful if offloading HTTPS to a load balancer

False

nginx_disable_hsts

Disable HSTS web-security policy mechanism

False

nginx_http_port

Port to configure nginx to listen to for HTTP

80

nginx_https_port

Port to configure nginx to listen to for HTTPS

443

backup_dir

A temp location to use when backing up

/var/backups/tower/

restore_backup_file

Specify an alternative backup file to restore from

None

required_ram

The minimum RAM required to install Tower (should only be changed for test installation)

3750

min_open_fds

The minimum open file descriptions (should only be changed for test installations)

None

ignore_preflight_errors

Ignore preflight checks, useful when installing into a template or other non-system image (overrides required_ram and min_open_fds)

False

rekey_catalog

When you execute the setup.sh script using this variable set to true, by default, a new secret key is generated and distributed for both the automation controller and the automation services catalog.

False

Examples

  • To upgrade core:
./setup.sh -e upgrade_ansible_with_tower=1
  • To disable https handling at nginx:
./setup.sh -e nginx_disable_https=true
  • To specify a non-default path when restoring from a backup file:
./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r

3.4.6. Running the Red Hat Ansible Automation Platform installer setup script

You can run the setup script once you finish updating the inventory file with required parameters for installing your Private Automation Hub.

Procedure

  1. Run the setup.sh script

    $ ./setup.sh

The installation will begin.

3.4.7. Verifying automation controller installation

Once the installation completes, you can verify your automation controller has been installed successfully by logging in with the admin credentials you inserted into the inventory file.

Procedure

  1. Navigate to the IP address specified for the automation controller node in the inventory file.
  2. Log in with the Admin credentials you set in the inventory file.
Note

The automation controller server is accessible from port 80 (https://<TOWER_SERVER_NAME>/) but will redirect to port 443 so 443 needs to be available also.

Important

If the installation fails and you are a customer who has purchased a valid license for Red Hat Ansible Automation Platform, please contact Ansible via the Red Hat Customer portal at https://access.redhat.com/.

Upon a successful login to automation controller, your installation of Red Hat Ansible Automation Platform 2.2 is now complete.

3.4.7.1. Additional automation hub configuration and resources

See the following resources to explore additional automation hub configurations.

Table 3.12. Resources to configure automation controller

LinkDescription

Managing user access in private automation hub

Configure user access for automation hub

Managing Red Hat Certified and Ansible Galaxy collections in automation hub

Add content to your automation hub

Publishing proprietary content collections in automation hub

Publish internally developed collections on your automation hub

3.4.8. What’s next with Ansible Automation Platform 2.2

Whether you are a new Ansible Automation Platform user looking to start automating, or an existing administrator looking to migrate old Ansible content to your latest installed version of Red Hat Ansible Automation Platform, explore the next steps to begin leveraging the new features of Ansible Automation Platform 2.2:

3.4.8.1. Migrating data to Ansible Automation Platform 2.2

For platform administrators looking to complete an upgrade to the Ansible Automation Platform 2.2, there may be additional steps needed to migrate data to a new instance:

3.4.8.1.1. Migrating from legacy virtual environments (venvs) to automation execution environments

Ansible Automation Platform 2.2 moves you away from custom Python virtual environments (venvs) in favor of automation execution environments - containerized images that packages the necessary components needed to execute and scale your Ansible automation. This includes Ansible Core, Ansible Content Collections, Python dependencies, Red Hat Enterprise Linux UBI 8, and any additional package dependencies.

If you are looking to migrate your venvs to execution environments, you will (1) need to use the awx-manage command to list and export a list of venvs from your original instance, then (2) use ansible-builder to create execution environments. For more information, see the Upgrading to Automation Execution Environments guide and the Creating and Consuming Execution Environments.

3.4.8.1.2. Migrating to Ansible Engine 2.9 images using Ansible Builder

To migrate Ansible Engine 2.9 images for use with Ansible Automation Platform 2.2, the ansible-builder tool automates the process of rebuilding images (including its custom plugins and dependencies) for use with automation execution environments. For more information on using Ansible Builder to build execution environments, see the Creating and Consuming Execution Environments.

3.4.8.1.3. Migrating to Ansible Core 2.13

When upgrading to Ansible Core 2.13, you need to update your playbooks, plugins, or other parts of your Ansible infrastructure in order to be supported by the latest version of Ansible Core. For instructions on updating your Ansible content for Ansible Core 2.13 compatibility, see the Ansible-core 2.13 Porting Guide.

3.4.8.2. Scale up your automation using automation mesh

The automation mesh component of the Red Hat Ansible Automation Platform simplifies the process of distributing automation across multi-site deployments. For enterprises with multiple isolated IT environments, automation mesh provides a consistent and reliable way to deploy and scale up automation across your execution nodes using a peer-to-peer mesh communication network.

When upgrading from version 1.x to the latest version of the Ansible Automation Platform, you will need to migrate the data from your legacy isolated nodes into execution nodes necessary for automation mesh. You can implement automation mesh by planning out a network of hybrid and control nodes, then editing the inventory file found in the Ansible Automation Platform installer to assign mesh-related values to each of your execution nodes.

For instructions on how to migrate from isolated nodes to execution nodes, see the upgrade & migration guide.

For information about automation mesh and the various ways to design your automation mesh for your environment, see the Red Hat Ansible Automation Platform automation mesh guide.