Chapter 2. Automation mesh for operator-based Red Hat Ansible Automation Platform

1. You require a Red Hat Enterprise Linux operating system. Each node in the mesh requires a static IP address, or a resolvable DNS hostname that Ansible Automation Platform can access.
2. Ensure that you have the minimum requirements for the RHEL virtual machine before proceeding. For more information, see the System requirements.

3. Deploy the RHEL instances within the remote networks where communication is required. For information about creating virtual machines, see Creating Virtual Machines in the Red Hat Enterprise Linux documentation. Remember to scale the capacity of your virtual machines sufficiently so that your proposed tasks can run on them.

   • RHEL ISOs can be obtained from access.redhat.com.
   • RHEL cloud images can be built using Image Builder from console.redhat.com.

Procedure

1. SSH into each of the RHEL instances and perform the following steps. Depending on your network access and controls, SSH proxies or other access models might be required.

   Use the following command:

   ssh [username]@[host_ip_address]

   Copy to Clipboard Toggle word wrap

   For example, for an Ansible Automation Platform instance running on Amazon Web Services.

   ssh ec2-user@10.0.0.6

   Copy to Clipboard Toggle word wrap
2. Create or copy an SSH key that can be used to connect from the hop node to the execution node in later steps. This can be a temporary key used just for the automation mesh configuration, or a long-lived key. The SSH user and key are used in later steps.

3. Enable your RHEL subscription with baseos and appstream repositories. Ansible Automation Platform RPM repositories are only available through subscription-manager, not the Red Hat Update Infrastructure (RHUI). If you attempt to use any other Linux footprint, including RHEL with RHUI, this causes errors.

   sudo subscription-manager register --auto-attach

   Copy to Clipboard Toggle word wrap

   If Simple Content Access is enabled for your account, use:

   sudo subscription-manager register

   Copy to Clipboard Toggle word wrap

   For more information about Simple Content Access, see Getting started with simple content access.

4. Enable Ansible Automation Platform subscriptions and the proper Red Hat Ansible Automation Platform channel:

   For RHEL 8

   # subscription-manager repos --enable ansible-automation-platform-2.5-for-rhel-8-x86_64-rpms

   Copy to Clipboard Toggle word wrap

   For RHEL 9

   # subscription-manager repos --enable ansible-automation-platform-2.5-for-rhel-9-x86_64-rpms

   Copy to Clipboard Toggle word wrap

   For ARM

   # subscription-manager repos --enable ansible-automation-platform-2.5-for-rhel-aarch64-rpms

   Copy to Clipboard Toggle word wrap

5. Ensure the packages are up to date:

   sudo dnf upgrade -y

   Copy to Clipboard Toggle word wrap

6. Install the ansible-core packages on the machine where the downloaded bundle is to run:

   sudo dnf install -y ansible-core

   Copy to Clipboard Toggle word wrap
   Note

   Ansible core is required on the machine that runs the automation mesh configuration bundle playbooks. This document assumes that happens on the execution node. However, this step can be omitted if you run the playbook from a different machine. You cannot run directly from the control node, this is not currently supported, but future support expects that the control node has direct connectivity to the execution node.

Procedure

1. From the navigation panel, select Automation Execution Infrastructure Instances.

2. On the Instances list page, click Add instance. The Add Instance window opens.

   

   View larger image

   

   An instance requires the following attributes:

   • Host name: (required) Enter a fully qualified domain name (public DNS) or IP address for your instance. This field is equivalent to hostname for installer-based deployments.

     Note

     If the instance uses private DNS that cannot be resolved from the control cluster, DNS lookup routing fails, and the generated SSL certificates is invalid. Use the IP address instead.

   • Optional: Description: Enter a description for the instance.
   • Instance state: This field is auto-populated, indicating that it is being installed, and cannot be modified.
   • Listener port: This port is used for the receptor to listen on for incoming connections. You can set the port to one that is appropriate for your configuration. This field is equivalent to listener_port in the API. The default value is 27199, though you can set your own port value.

   • Instance type: Only execution and hop nodes can be created. Operator based deployments do not support Control or Hybrid nodes.

     Options:

     • Enable instance: Check this box to make it available for jobs to run on an execution node.
     • Check the Managed by policy box to enable policy to dictate how the instance is assigned.

     • Peers from control nodes:

       • If you are configuring a hop node:

         • If the hop node needs to have requests pushed directly from automation controller, then check the Peers from Control box.
         • If the hop node is peered to another hop node, then make sure Peers from Control is not checked.

       • If you are configuring an execution node:

         • If the execution node needs to have requests pushed directly from automation controller, then check the Peers from Control box.
         • If the execution node is peered to a hop node, then make sure that Peers from Control is not checked.
3. Click Associate peers.

4. To verify peering configuration and the direction of traffic, you can use the topology view to view a graphical representation of your updated topology. This can help to determine where your firewall rules might need to be updated. For more information, see Topology view.

   Note

   Complete the following steps from any computer that has SSH access to the newly created instance.

5. Click the icon next to Download Bundle to download the tar file that includes this new instance and the files necessary to install the created node into the automation mesh.

   The install bundle has TLS certificates and keys, a certificate authority, and a proper Receptor configuration file.

   receptor-ca.crt
   work-public-key.pem
   receptor.key
   install_receptor.yml
   inventory.yml
   group_vars/all.yml
   requirements.yml

   Copy to Clipboard Toggle word wrap
6. Extract the downloaded tar.gz Install Bundle from the location where you downloaded it. To ensure that these files are in the correct location on the remote machine, the install bundle includes the install_receptor.yml playbook.

7. Before running the ansible-playbook command, edit the following fields in the inventory.yml file:

   all:
     hosts:
       remote-execution:
         ansible_host: localhost # change to the mesh node host name
             ansible_user: <username> # user provided
             ansible_ssh_private_key_file: ~/.ssh/<id_rsa>

   Copy to Clipboard Toggle word wrap
   • Ensure ansible_host is set to the IP address or DNS of the node.
   • Set ansible_user to the username running the installation.
   • Set ansible_ssh_private_key_file to contain the filename of the private key used to connect to the instance.
   • The content of the inventory.yml file serves as a template and contains variables for roles that are applied during the installation and configuration of a receptor node in a mesh topology. You can modify some of the other fields, or replace the file in its entirety for advanced scenarios. For more information, see Role Variables.

8. For a node that uses a private DNS, add the following line to inventory.yml:

    ansible_ssh_common_args: <your ssh ProxyCommand setting>

   Copy to Clipboard Toggle word wrap

   This instructs the install-receptor.yml playbook to use the proxy command to connect through the local DNS node to the private node.

9. When the attributes are configured, click Save. The Details page of the created instance opens.
10. Save the file to continue.

11. The system that is going to run the install bundle to setup the remote node and run ansible-playbook requires the ansible.receptor collection to be installed:

    ansible-galaxy collection install ansible.receptor

    Copy to Clipboard Toggle word wrap

    or

    ansible-galaxy install -r requirements.yml

    Copy to Clipboard Toggle word wrap
    • Installing the receptor collection dependency from the requirements.yml file consistently retrieves the receptor version specified there. Additionally, it retrieves any other collection dependencies that might be needed in the future.
    • Install the receptor collection on all nodes where your playbook will run, otherwise an error occurs.

12. If receptor_listener_port is defined, the machine also requires an available open port on which to establish inbound TCP connections, for example, 27199. Run the following command to open port 27199 for receptor communication (Make sure you have port 27199 open in your firewall):

    sudo firewall-cmd --permanent --zone=public --add-port=27199/tcp

    Copy to Clipboard Toggle word wrap
13. Run the following playbook on the machine where you want to update your automation mesh:

Procedure

1. From the navigation panel, select Automation Execution Infrastructure Instance Groups.
2. Click Create group and select Create instance group from the list.

3. Enter the appropriate details into the following fields:

   • Name: Names must be unique and must not be named "controller".
   • Policy instance minimum: Enter the minimum number of instances to automatically assign to this group when new instances come online.

   • Policy instance percentage: Use the slider to select a minimum percentage of instances to automatically assign to this group when new instances come online.

     Note

     Policy instance fields are not required to create a new instance group. If you do not specify values, then the Policy instance minimum and Policy instance percentage default to 0.

   • Max concurrent jobs: Specify the maximum number of forks that can be run for any given job.

   • Max forks: Specify the maximum number of concurrent jobs that can be run for any given job.

     Note

     The default value of 0 for Max concurrent jobs and Max forks denotes no limit. For more information, see Instance group capacity limits.

4. Click Create instance group, or, if you have edited an existing Instance Group click Save instance group

Procedure

1. Select the Instances tab on the Details page of an Instance Group.
2. Click Associate instance.
3. Click the checkbox next to one or more available instances from the list to select the instances you want to associate with the instance group and click Confirm

Procedure

1. The Templates list view shows job templates that are currently available. From this screen you can launch , edit , and duplicate a workflow job template.
2. Select the job you want and click the icon.
3. Select the Instance Group on which you want to run the job. Note that a System Administrator must grant you or your team permissions to be able to use an instance group in a job template. If you select multiple jobs templates, the order in which you select them sets the execution precedence.
4. Click Next.
5. Click Launch.

Procedure

1. Create a YAML file (in this case named oc_meshingress.yml) to set up the mesh ingress node.

   Your file should resemble the following:

   apiVersion: automationcontroller.ansible.com/v1alpha1
   kind: AutomationControllerMeshIngress
   metadata:
       name:
       namespace:
   spec:
       deployment_name: aap-controller

   Copy to Clipboard Toggle word wrap

   Where:

   • apiVersion: defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and might reject unrecognized values. This value is static.

   • kind: Is the type of node to create.

     Use the value AutomationControllerMeshIngress.

     AutomationControllerMeshIngress controls the deployment and configuration of mesh ingress on automation controller.

   • name: enter a name for the mesh ingress node.

   • namespace: enter a name for the Kubernetes namespace to deploy the mesh ingress into.

     This must be in the same namespace as the automation controller that the mesh is connected to.

   • deployment_name: is the automation controller instance that this mesh ingress is attached to. Provide the name of your automation controller instance.

2. Apply this YAML file using:

   oc apply -f oc_meshingress.yml

   Copy to Clipboard Toggle word wrap

   Run this playbook to creates the AutomationControllerMeshIngress resource. The operator creates a hop node in automation controller with the name you supplied.

3. When the MeshIngress instance has been created, it appears in the Instances page.

   Important

   Any instance that is to function as a remote execution node in "pull" mode need to be created after this procedure and must be configured as follows:

   instance type: Execution
   listener port: keep empty
   options:
       Enable instance: checked
       Managed by Policy: as needed
       Peers from control nodes: unchecked (this one is important)

   Copy to Clipboard Toggle word wrap
4. Associate this new instance with the hop node you created using the procedure in this paragraph

5. Download the tarball.

   Note

   Association with the hop node must be done before creating the tarball.

Procedure

1. Create a secret using the following command:

   oc create secret generic ee-pull-secret \
        --from-literal=username=<username> \
        --from-literal=password=<password> \
        --from-literal=url=registry.redhat.io

   Copy to Clipboard Toggle word wrap

2. Add ee_pull_credentials_secret and ee-pull-secret to the specification by editing the deployment specification:

   oc edit automationcontrollers aap-controller-o yaml

   Copy to Clipboard Toggle word wrap

   and add the following:

   spec
     ee_pull_credentials_secret=ee-pull-secret

   Copy to Clipboard Toggle word wrap
3. To manage instances from the automation controller UI, you must have System Administrator or System Auditor permissions.

Procedure

1. Check the current receptor version:

   receptor --version

   Copy to Clipboard Toggle word wrap

2. Update the receptor:

   sudo dnf update ansible-runner receptor -y

   Copy to Clipboard Toggle word wrap
   Note

   To upgrade all packages (not just the receptor), use dnf update, then reboot with reboot.

3. Verify the installation. After the update is complete, check the receptor version again to verify the update:

   receptor --version

   Copy to Clipboard Toggle word wrap

4. Restart the receptor service:

   sudo systemctl restart receptor

   Copy to Clipboard Toggle word wrap
5. Ensure the receptor is working correctly and is properly connected to the controller or other nodes in the system.