Chapter 1. Ansible Automation Platform containerized installation
Chapter 1. Ansible Automation Platform containerized installation Ansible Automation Platform is a commercial offering that helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments. This guide helps you to understand the installation requirements and processes behind our new containerized version of Ansible Automation Platform. This initial version is based upon Ansible Automation Platform 2.4 and is being released as a Technical Preview. Please see Technology Preview Features Support Scope to understand what a technical preview entails. Prerequisites A RHEL 9.2 based host. Minimal OS base install is recommended. A non-root user for the RHEL host, with sudo or other Ansible supported privilege escalation (sudo recommended). This user is responsible for the installation of containerized Ansible Automation Platform. It is recommended setting up an SSH public key authentication for the non-root user. For guidelines on setting up an SSH public key authentication for the non-root user, see How to configure SSH public key authentication for passwordless login . SSH keys are only required when installing on remote hosts. If doing a self contained local VM based installation, you can use ansible_connection: local as per the example which does not require SSH. Internet access from the RHEL host if using the default online installation method. 1.1. System Requirements Your system must meet the following minimum system requirements to install and run Red Hat Containerized Ansible Automation Platform. Memory 16Gb RAM CPU 4 CPU Disk space 40Gb Disk IOPs 1500 1.2. Preparing the RHEL host for containerized installation Procedure Containerized Ansible Automation Platform runs the component services as podman based containers on top of a RHEL host. The installer takes care of this once the underlying host has been prepared. Use the following instructions for this. Log into your RHEL host as your non-root user. Run dnf repolist to validate only the BaseOS and appstream repos are setup and enabled on the host: USD dnf repolist Updating Subscription Management repositories. repo id repo name rhel-9-for-x86_64-appstream-rpms Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs) rhel-9-for-x86_64-baseos-rpms Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs) Ensure that these repos and only these repos are available to the host OS. If you need to know how to do this use this guide: Chapter 10. Managing custom software repositories Red Hat Enterprise Linux Ensure that the host has DNS configured and can resolve hostnames and IPs using a fully qualified domain name (FQDN). This is essential to ensure services can talk to one another. Using unbound DNS To configure unbound DNS refer to Chapter 2. Setting up an unbound DNS server Red Hat Enterprise Linux 9 . Using BIND DNS To configure DNS using BIND refer to Chapter 1. Setting up and configuring a BIND DNS server Red Hat Enterprise Linux 9 . Optional To have the installer automatically pick up and apply your Ansible Automation Platform subscription manifest license, use this guide to generate a manifest file which can be downloaded for the installer: Chapter 2. Obtaining a manifest file Red Hat Ansible Automation Platform 2. . 1.3. Installing ansible-core Procedure Install ansible-core and other tools: sudo dnf install -y ansible-core wget git rsync Set a fully qualified hostname: sudo hostnamectl set-hostname your-FQDN-hostname 1.4. Downloading Ansible Automation Platform Procedure Download the latest installer tarball from access.redhat.com . This can be done directly within the RHEL host, which saves time. If you have downloaded the tarball and optional manifest zip file onto your laptop, copy them onto your RHEL host. Decide where you would like the installer to reside on the filesystem. Installation related files will be created under this location and require at least 10Gb for the initial installation. Unpack the installer tarball into your installation directory, and cd into the unpacked directory. online installer USD tar xfvz ansible-automation-platform-containerized-setup-2.4-2.tar.gz bundled installer USD tar xfvz ansible-automation-platform-containerized-setup-bundle-2.4-2-<arch name>.tar.gz 1.5. Using postinstall feature of containerized Ansible Automation Platform Use the experimental postinstaller feature of containerized Ansible Automation Platform to define and load the configuration during the initial installation. This uses a configuration-as-code approach, where you simply define your configuration to be loaded as simple YAML files. To use this optional feature, you need to uncomment the following vars in the inventory file: controller_postinstall=true The default is false, so you need to enable this to activate the postinstaller. You need a Ansible Automation Platform license for this feature that must reside on the local filesystem so it can be automatically loaded: controller_license_file=/full_path_to/manifest_file.zip You can pull your configuration-as-code from a Git based repository. To do this, set the following variables to dictate where you pull the content from and where to store it for upload to the Ansible Automation Platform controller: controller_postinstall_repo_url=https://your_cac_scm_repo controller_postinstall_dir=/full_path_to_where_you_want_the pulled_content_to_reside The controller_postinstall_repo_url variable can be used to define the postinstall repository URL which must include authentication information. http(s)://<host>/<repo>.git (public repository without http(s) authentication) http(s)://<user>:<password>@<host>:<repo>.git (private repository with http(s) authentication) git@<host>:<repo>.git (public/private repository with ssh authentication) Note When using ssh based authentication, the installer does not configure anything for you, so you must configure everything on the installer node. Definition files use the infra certified collections . The controller_configuration collection is preinstalled as part of the installation and uses the installation controller credentials you supply in the inventory file for access into the Ansible Automation Platform controller. You simply need to give the YAML configuration files. You can setup Ansible Automation Platform configuration attributes such as credentials, LDAP settings, users and teams, organizations, projects, inventories and hosts, job and workflow templates. The following example shows a sample your-config.yml file defining and loading controller job templates. The example demonstrates a simple change to the preloaded demo example provided with an Ansible Automation Platform installation. /full_path_to_your_configuration_as_code/ ├── controller └── job_templates.yml controller_templates: - name: Demo Job Template execution_environment: Default execution environment instance_groups: - default inventory: Demo Inventory 1.6. Installing containerized Ansible Automation Platform Installation of Ansible Automation Platform is controlled with inventory files. Inventory files define the hosts and containers used and created, variables for components, and other information needed to customize the installation. For convenience an example inventory file is provided, that you can copy and modify to quickly get started. Note There is no default database choice given in the inventory file. You must follow the instructions in the inventory file to make the appropriate choice between an internally provided postgres, or provide your own externally managed and supported database option. Edit the inventory file by replacing the < > placeholders with your specific variables, and uncommenting any lines specific to your needs. # This is the AAP installer inventory file # Please consult the docs if you're unsure what to add # For all optional variables please consult the included README.md # This section is for your AAP Controller host(s) # ------------------------------------------------- [automationcontroller] fqdn_of_your_rhel_host ansible_connection=local # This section is for your AAP Automation Hub host(s) # ----------------------------------------------------- [automationhub] fqdn_of_your_rhel_host ansible_connection=local # This section is for your AAP EDA Controller host(s) # ----------------------------------------------------- [automationeda] fqdn_of_your_rhel_host ansible_connection=local # This section is for your AAP Execution host(s) # ------------------------------------------------ #[execution_nodes] #fqdn_of_your_rhel_host # This section is for the AAP database(s) # ----------------------------------------- # Uncomment the lines below and amend appropriately if you want AAP to install and manage the postgres databases # Leave commented out if you intend to use your own external database and just set appropriate _pg_hosts vars # see mandatory sections under each AAP component #[database] #fqdn_of_your_rhel_host ansible_connection=local [all:vars] # Common variables needed for installation # ---------------------------------------- postgresql_admin_username=postgres postgresql_admin_password=<set your own> # If using the online (non-bundled) installer, you need to set RHN registry credentials registry_username=<your RHN username> registry_password=<your RHN password> # If using the bundled installer, you need to alter defaults by using: #bundle_install=true # The bundle directory must include /bundle in the path #bundle_dir=<full path to the bundle directory> # To add more decision environment images you need to set the de_extra_images variable #de_extra_images=[{'name': 'Custom decision environment', 'image': '<registry>/<namespace>/<image>:<tag>'}] # To add more execution environment images you need to set the ee_extra_images variable #ee_extra_images=[{'name': 'Custom execution environment', 'image': '<registry>/<namespace>/<image>:<tag>'}] # To use custom TLS CA certificate/key you need to set these variables #ca_tls_cert=<full path to your TLS CA certificate file> #ca_tls_key=<full path to your TLS CA key file> # AAP Database - optional # -------------------------- # To use custom TLS certificate/key you need to set these variables #postgresql_tls_cert=<full path to your TLS certificate file> #postgresql_tls_key=<full path to your TLS key file> # AAP Controller - mandatory # -------------------------- controller_admin_password=<set your own> controller_pg_host=fqdn_of_your_rhel_host controller_pg_password=<set your own> # AAP Controller - optional # ------------------------- # To use the postinstall feature you need to set these variables #controller_postinstall=true #controller_license_file=<full path to your manifest .zip file> #controller_postinstall_dir=<full path to your config-as-code directory> # When using config-as-code in a git repository #controller_postinstall_repo_url=<url to your config-as-code git repository> #controller_postinstall_repo_ref=main # To use custom TLS certificate/key you need to set these variables #controller_tls_cert=<full path to your TLS certificate file> #controller_tls_key=<full path to your TLS key file> # AAP Automation Hub - mandatory # ------------------------------ hub_admin_password=<set your own> hub_pg_host=fqdn_of_your_rhel_host hub_pg_password=<set your own> # AAP Automation Hub - optional # ----------------------------- # To use the postinstall feature you need to set these variables #hub_postinstall=true #hub_postinstall_dir=<full path to your config-as-code directory> # When using config-as-code in a git repository #hub_postinstall_repo_url=<url to your config-as-code git repository> #hub_postinstall_repo_ref=main # To customize the number of worker containers #hub_workers=2 # To use the collection signing feature you need to set these variables #hub_collection_signing=true #hub_collection_signing_key=<full path to your gpg key file> # To use the container signing feature you need to set these variables #hub_container_signing=true #hub_container_signing_key=<full path to your gpg key file> # To use custom TLS certificate/key you need to set these variables #hub_tls_cert=<full path to your TLS certificate file> #hub_tls_key=<full path to your TLS key file> # AAP EDA Controller - mandatory # ------------------------------ eda_admin_password=<set your own> eda_pg_host=fqdn_of_your_rhel_host eda_pg_password=<set your own> # AAP EDA Controller - optional # ----------------------------- # When using an external controller node unmanaged by the installer. #controller_main_url=https://fqdn_of_your_rhel_host # To customize the number of default/activation worker containers #eda_workers=2 #eda_activation_workers=2 # To use custom TLS certificate/key you need to set these variables #eda_tls_cert=<full path to your TLS certificate file> #eda_tls_key=<full path to your TLS key file> # AAP Execution Nodes - optional # ----------------------------- #receptor_port=27199 #receptor_protocol=tcp # To use custom TLS certificate/key you need to set these variables #receptor_tls_cert=<full path to your TLS certificate file> #receptor_tls_key=<full path to your TLS key file> # To use custom RSA key pair you need to set these variables #receptor_signing_private_key=<full path to your RSA private key file> #receptor_signing_public_key=<full path to your RSA public key file> Use the following command to install containerized Ansible Automation Platform: ansible-playbook -i inventory ansible.containerized_installer.install Note If your privilege escalation requires a password to be entered, append *-K* to the command line. You will then be prompted for the *BECOME* password. You can use increasing verbosity, up to 4 v's (-vvvv) to see the details of the installation process. Note This can significantly increase installation time, so it is recommended that you use it only as needed or requested by Red Hat support. 1.7. Accessing automation controller, automation hub, and Event-Driven Ansible controller After the installation completes, these are the default protocol and ports used: http/https protocol Ports 8080/8443 for automation controller Ports 8081/8444 for automation hub Ports 8082/8445 for Event-Driven Ansible controller These can be changed. Consult the README.md for further details. It is recommended that you leave the defaults unless you need to change them due to port conflicts or other factors. Accessing automation controller UI The automation controller UI is available by default at: https://<your_rhel_host>:8443 Log in as the admin user with the password you created for controller_admin_password . If you supplied the license manifest as part of the installation, the Ansible Automation Platform dashboard is displayed. If you did not supply a license file, the Subscription screen is displayed where you must supply your license details. This is documented here: Chapter 1. Activating Red Hat Ansible Automation Platform . Accessing automation hub UI The automation hub UI is available by default at: https://<hub node>:8444 Log in as the admin user with the password you created for hub_admin_password . Accessing Event-Driven Ansible UI The Event-Driven Ansible UI is available by default at: https://<eda node>:8445 Log in as the admin user with the password you created for eda_admin_password . 1.8. Using custom TLS certificates By default, the installer generates TLS certificates and keys for all services which are signed by a custom Certificate Authority (CA). You can provide a custom TLS certificate/key for each service. If that certificate is signed by a custom CA, you must provide the CA TLS certificate and key. Certificate Authority ca_tls_cert=/full/path/to/tls/certificate ca_tls_key=/full/path/to/tls/key Automation Controller controller_tls_cert=/full/path/to/tls/certificate controller_tls_key=/full/path/to/tls/key Automation Hub hub_tls_cert=/full/path/to/tls/certificate hub_tls_key=/full/path/to/tls/key Automation EDA eda_tls_cert=/full/path/to/tls/certificate eda_tls_key=/full/path/to/tls/key Postgresql postgresql_tls_cert=/full/path/to/tls/certificate postgresql_tls_key=/full/path/to/tls/key Receptor receptor_tls_cert=/full/path/to/tls/certificate receptor_tls_key=/full/path/to/tls/key 1.9. Using custom Receptor signing keys Receptor signing is now enabled by default unless receptor_disable_signing=true is set, and a RSA key pair (public/private) is generated by the installer. However, you can provide custom RSA public/private keys by setting the path variable. receptor_signing_private_key=/full/path/to/private/key receptor_signing_public_key=/full/path/to/public/key 1.10. Enabling Automation hub collection and container signing Automation hub allows you to sign Ansible collections and container images. This feature is not enabled by default, and you must provide the GPG key. hub_collection_signing=true hub_collection_signing_key=/full/path/to/collections/gpg/key hub_container_signing=true hub_container_signing_key=/full/path/to/containers/gpg/key When the GPG key is protected by a passphrase, you must provide the passphrase. hub_collection_signing_pass=<collections gpg key passphrase> hub_container_signing_pass=<containers gpg key passphrase> 1.11. Adding execution nodes The containerized installer can deploy remote execution nodes. This is handled by the execution_nodes group in the ansible inventory file. [execution_nodes] fqdn_of_your_execution_host An execution node is by default configured as an execution type running on port 27199 (TCP). This can be changed by the following variables: receptor_port=27199 receptor_protocol=tcp receptor_type=hop Receptor type value can be either execution or hop, while the protocol is either TCP or UDP. By default, the nodes in the execution_nodes group will be added as peers for the controller node. However, you can change the peers configuration by using the receptor_peers variable. [execution_nodes] fqdn_of_your_execution_host fqdn_of_your_hop_host receptor_type=hop receptor_peers='["fqdn_of_your_execution_host"]' 1.12. Uninstalling containerized Ansible Automation Platform To uninstall a containerized deployment, execute the uninstall.yml playbook. USD ansible-playbook -i inventory ansible.containerized_installer.uninstall This will stop all systemd units and containers and then delete all resources used by the containerized installer such as: config and data directories/files systemd unit files podman containers and images RPM packages To keep container images, you can set the container_keep_images variable to true. USD ansible-playbook -i inventory ansible.containerized_installer.uninstall -e container_keep_images=true To keep postgresql databases, you can set the postgresql_keep_databases variable to true. USD ansible-playbook -i </path/to/inventory> ansible.containerized_installer.uninstall -e postgresql_keep_databases=true Note You will have to use the same django secret key values rather than the auto-generated ones.
dnf repolist Updating Subscription Management repositories. repo id repo name rhel-9-for-x86_64-appstream-rpms Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs) rhel-9-for-x86_64-baseos-rpms Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs) sudo dnf install -y ansible-core wget git rsync sudo hostnamectl set-hostname your-FQDN-hostname tar xfvz ansible-automation-platform-containerized-setup-2.4-2.tar.gz tar xfvz ansible-automation-platform-containerized-setup-bundle-2.4-2-<arch name>.tar.gz controller_postinstall=true controller_license_file=/full_path_to/manifest_file.zip controller_postinstall_repo_url=https://your_cac_scm_repo controller_postinstall_dir=/full_path_to_where_you_want_the pulled_content_to_reside http(s)://<host>/<repo>.git (public repository without http(s) authentication) http(s)://<user>:<password>@<host>:<repo>.git (private repository with http(s) authentication) git@<host>:<repo>.git (public/private repository with ssh authentication) /full_path_to_your_configuration_as_code/ ├── controller └── job_templates.yml controller_templates: - name: Demo Job Template execution_environment: Default execution environment instance_groups: - default inventory: Demo Inventory This is the AAP installer inventory file Please consult the docs if you're unsure what to add For all optional variables please consult the included README.md This section is for your AAP Controller host(s) ------------------------------------------------- [automationcontroller] fqdn_of_your_rhel_host ansible_connection=local This section is for your AAP Automation Hub host(s) ----------------------------------------------------- [automationhub] fqdn_of_your_rhel_host ansible_connection=local This section is for your AAP EDA Controller host(s) ----------------------------------------------------- [automationeda] fqdn_of_your_rhel_host ansible_connection=local This section is for your AAP Execution host(s) ------------------------------------------------ #[execution_nodes] #fqdn_of_your_rhel_host This section is for the AAP database(s) ----------------------------------------- Uncomment the lines below and amend appropriately if you want AAP to install and manage the postgres databases Leave commented out if you intend to use your own external database and just set appropriate _pg_hosts vars see mandatory sections under each AAP component #[database] #fqdn_of_your_rhel_host ansible_connection=local Common variables needed for installation ---------------------------------------- postgresql_admin_username=postgres postgresql_admin_password=<set your own> If using the online (non-bundled) installer, you need to set RHN registry credentials registry_username=<your RHN username> registry_password=<your RHN password> If using the bundled installer, you need to alter defaults by using: #bundle_install=true The bundle directory must include /bundle in the path #bundle_dir=<full path to the bundle directory> To add more decision environment images you need to set the de_extra_images variable #de_extra_images=[{'name': 'Custom decision environment', 'image': '<registry>/<namespace>/<image>:<tag>'}] To add more execution environment images you need to set the ee_extra_images variable #ee_extra_images=[{'name': 'Custom execution environment', 'image': '<registry>/<namespace>/<image>:<tag>'}] To use custom TLS CA certificate/key you need to set these variables #ca_tls_cert=<full path to your TLS CA certificate file> #ca_tls_key=<full path to your TLS CA key file> AAP Database - optional -------------------------- To use custom TLS certificate/key you need to set these variables #postgresql_tls_cert=<full path to your TLS certificate file> #postgresql_tls_key=<full path to your TLS key file> AAP Controller - mandatory -------------------------- controller_admin_password=<set your own> controller_pg_host=fqdn_of_your_rhel_host controller_pg_password=<set your own> AAP Controller - optional ------------------------- To use the postinstall feature you need to set these variables #controller_postinstall=true #controller_license_file=<full path to your manifest .zip file> #controller_postinstall_dir=<full path to your config-as-code directory> When using config-as-code in a git repository #controller_postinstall_repo_url=<url to your config-as-code git repository> #controller_postinstall_repo_ref=main To use custom TLS certificate/key you need to set these variables #controller_tls_cert=<full path to your TLS certificate file> #controller_tls_key=<full path to your TLS key file> AAP Automation Hub - mandatory ------------------------------ hub_admin_password=<set your own> hub_pg_host=fqdn_of_your_rhel_host hub_pg_password=<set your own> AAP Automation Hub - optional ----------------------------- To use the postinstall feature you need to set these variables #hub_postinstall=true #hub_postinstall_dir=<full path to your config-as-code directory> When using config-as-code in a git repository #hub_postinstall_repo_url=<url to your config-as-code git repository> #hub_postinstall_repo_ref=main To customize the number of worker containers #hub_workers=2 To use the collection signing feature you need to set these variables #hub_collection_signing=true #hub_collection_signing_key=<full path to your gpg key file> To use the container signing feature you need to set these variables #hub_container_signing=true #hub_container_signing_key=<full path to your gpg key file> To use custom TLS certificate/key you need to set these variables #hub_tls_cert=<full path to your TLS certificate file> #hub_tls_key=<full path to your TLS key file> AAP EDA Controller - mandatory ------------------------------ eda_admin_password=<set your own> eda_pg_host=fqdn_of_your_rhel_host eda_pg_password=<set your own> AAP EDA Controller - optional ----------------------------- When using an external controller node unmanaged by the installer. #controller_main_url=https://fqdn_of_your_rhel_host To customize the number of default/activation worker containers #eda_workers=2 #eda_activation_workers=2 To use custom TLS certificate/key you need to set these variables #eda_tls_cert=<full path to your TLS certificate file> #eda_tls_key=<full path to your TLS key file> AAP Execution Nodes - optional ----------------------------- #receptor_port=27199 #receptor_protocol=tcp To use custom TLS certificate/key you need to set these variables #receptor_tls_cert=<full path to your TLS certificate file> #receptor_tls_key=<full path to your TLS key file> To use custom RSA key pair you need to set these variables #receptor_signing_private_key=<full path to your RSA private key file> #receptor_signing_public_key=<full path to your RSA public key file> ansible-playbook -i inventory ansible.containerized_installer.install If your privilege escalation requires a password to be entered, append *-K* to the command line. You will then be prompted for the *BECOME* password. https://<your_rhel_host>:8443 https://<hub node>:8444 https://<eda node>:8445 ca_tls_cert=/full/path/to/tls/certificate ca_tls_key=/full/path/to/tls/key controller_tls_cert=/full/path/to/tls/certificate controller_tls_key=/full/path/to/tls/key hub_tls_cert=/full/path/to/tls/certificate hub_tls_key=/full/path/to/tls/key eda_tls_cert=/full/path/to/tls/certificate eda_tls_key=/full/path/to/tls/key postgresql_tls_cert=/full/path/to/tls/certificate postgresql_tls_key=/full/path/to/tls/key receptor_tls_cert=/full/path/to/tls/certificate receptor_tls_key=/full/path/to/tls/key receptor_signing_private_key=/full/path/to/private/key receptor_signing_public_key=/full/path/to/public/key hub_collection_signing=true hub_collection_signing_key=/full/path/to/collections/gpg/key hub_container_signing=true hub_container_signing_key=/full/path/to/containers/gpg/key hub_collection_signing_pass=<collections gpg key passphrase> hub_container_signing_pass=<containers gpg key passphrase> [execution_nodes] fqdn_of_your_execution_host [execution_nodes] fqdn_of_your_execution_host fqdn_of_your_hop_host receptor_type=hop receptor_peers='["fqdn_of_your_execution_host"]' ansible-playbook -i inventory ansible.containerized_installer.uninstall ansible-playbook -i inventory ansible.containerized_installer.uninstall -e container_keep_images=true ansible-playbook -i </path/to/inventory> ansible.containerized_installer.uninstall -e postgresql_keep_databases=true