Chapter 7. The command generator

The Command Generator is used to generate commands for launching operational playbooks provided by the Ansible-on-clouds operational playbook collection.

The process involves five steps:

  1. Pull the ansible-on-clouds-ops container image.
  2. List the available playbooks.
  3. Use a command generator to generate a data file and the next command to run. command_generator_vars and the command_generator are implemented using a docker container and are run using the docker command line interface.
  4. Populate the data file and run the previous generated command. This generates the final command with all parameters.

    Note

    When this step is complete, you can save the generated command and run the playbook when it is required.

  5. Run the final command.

Prerequisites

  • Docker
  • An AWS credentials file
  • An internet connection to Amazon Web Services

7.1. Pulling the ansible-on-clouds-ops container image

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

Note

Before Pulling the docker image, ensure you are logged in to registry.redhat.io using docker. Use the following command to login to registry.redhat.io.

$ docker login registry.redhat.io

For more information about registry login, see Registry Authentication

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

Use the following commands:

$ export IMAGE=registry.redhat.io/ansible-on-clouds/ansible-on-clouds-ops-rhel9:2.4.20230630
$ docker pull $IMAGE --platform=linux/amd64

7.2. Listing the available playbooks

Procedure

  1. For the list of available playbooks without details, use the following command.

    $ docker run --rm $IMAGE command_generator_vars | grep Playbook
    
    The current version of the operational playbooks collection contains the following playbooks:
    
    Playbook: aws_add_extension_nodes
    Playbook: aws_add_labels
    Playbook: aws_backup_delete
    Playbook: aws_backup_stack
    Playbook: aws_backups_delete
    Playbook: aws_check_aoc_version
    Playbook: aws_deployment_inventory
    Playbook: aws_get_aoc_version
    Playbook: aws_remove_extension_nodes
    Playbook: aws_remove_labels
    Playbook: aws_restore_stack
    Playbook: aws_upgrade
    Playbook: gcp_aap_health_check
    Playbook: gcp_add_extension_nodes
    Playbook: gcp_add_labels
    Playbook: gcp_backup_delete
    Playbook: gcp_backup_deployment
    Playbook: gcp_backup_list
    Playbook: gcp_backups_delete
    Playbook: gcp_check_aoc_version
    Playbook: gcp_deployment_inventory
    Playbook: gcp_get_aoc_version
    Playbook: gcp_health_check
    Playbook: gcp_list_deployments
    Playbook: gcp_nodes_health_check
    Playbook: gcp_remove_extension_nodes
    Playbook: gcp_remove_labels
    Playbook: gcp_restore_deployment
    Playbook: gcp_setup_logging_monitoring
    Playbook: gcp_upgrade
  2. To provide a list of all available playbooks, and to use the command generator, use the following command.

    $ docker run --rm $IMAGE command_generator_vars

    This provides a list of playbooks and a command similar to the following:

    ===============================================
    Playbook: aws_add_extension_nodes
    Description: Add extension nodes to an existing Ansible Automation Platform from AWS Marketplace stack
    -----------------------------------------------
    This playbook is used to deploy extension nodes to an existing Ansible Automation Platform from AWS Marketplace environment.
    For more information regarding extension nodes, visit our official documentation -
    https://access.redhat.com/documentation/en-us/ansible_on_clouds/2.x/html/red_hat_ansible_automation_platform_from_aws_marketplace_guide/assembly-aap-aws-extension
    
    -----------------------------------------------
    Command generator template:
    
    docker run --rm $IMAGE command_generator aws_add_extension_nodes [--ansible-config ansible_config_path>] \
    -d <deployment_name> -c <cloud_credentials_path> \
    --extra-vars 'aws_region=<aws_region> aws_launch_template_name=<aws_launch_template_name> aws_autoscaling_group_name=<aws_autoscaling_group_name> aws_asg_min_size=<aws_asg_min_size> aws_asg_desired_capacity=<aws_asg_desired_capacity> aws_offer_type=<aws_offer_type> [seller_name=<seller_name>]'
    ===============================================

7.3. Generating the data file

Procedure

  1. Run the command generator.

    $ docker run --rm -v <local_directory_data_file>:/data $IMAGE command_generator_vars <playbook_name> --output-data-file /data/<data-file>.yml

    The outputs of this command are the command to run and the data file template. The data file is also saved in your <local_data_file_directory>. This is the template which you populate with your data.

    The following example uses the aws_backup_stack playbook.

    $ docker run --rm -v <local_data_file_directory>:/data $IMAGE command_generator_vars aws_backup_stack \
    --output-data-file /data/backup.yml
  2. Producing the following output.

    ===============================================
    Playbook: aws_backup_stack
    Description: This playbook is used to backup the Ansible Automation Platform from AWS Marketplace environment.
    -----------------------------------------------
    This playbook is used to backup the Ansible Automation Platform from AWS Marketplace environment.
    For more information regarding backup and restore, visit our official documentation -
    
    -----------------------------------------------
    Command generator template:
    
    docker run --rm -v /tmp:/data $IMAGE command_generator aws_backup_deployment --data-file /data/backup.yml
    
    Data template:
    
    aws_backup_stack:
      cloud_credentials_path:
      deployment_name:
      extra_vars:
        aws_backup_iam_role:
    	aws_backup_vault_name:
        aws_region:
        aws_s3_bucket:
    
    ===============================================

7.4. Populating the data file

Procedure

  • Edit the data-file generated in Generating the data file.

    Any attribute that represents a path must be an absolute path. The command_generator automatically mounts a volume for it in the final command.

    For example, in the case of the aws_backup_stack playbook, the file becomes:

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

7.5. Running the generated command

Procedure

  1. Ensure that the mounted volume points to the directory where the data file is.

    For the aws_backup_stack playbook example, this is:

    $ docker run --rm -v /tmp:/data $IMAGE command_generator aws_backup_stack --data-file /data/backup.yml

    Which generates the following output:

    Command to run playbook:
    
    $ docker run --rm --env PLATFORM=AWS -v ~/.aws/credentials:/home/runner/.aws/credentials:ro \
    --env ANSIBLE_CONFIG=../aws-ansible.cfg  $IMAGE redhat.ansible_on_clouds.aws_backup_stack \
    -e 'aws_foundation_stack_name=AnsibleAutomationPlatform aws_region=us-east-1 \
    aws_backup_vault_name=Default \
    aws_backup_iam_role_arn=arn:aws:iam::123456789012:role/service-role/AWSBackupDefaultServiceRole \ aws_s3_bucket=AnsibleAutomationPlatform-bucket'

    This new command has the required parameters, environment variables and mounted volumes to run the playbook.

  2. Run the generated command. You can save this command to rerun it later if required.

7.6. Using the playbooks

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

aws_add_labels

This playbook adds labels to the deployment.

$ docker run --rm $IMAGE command_generator_vars aws_add_labels

Which generates the following output:

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

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

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

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

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

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

aws_check_aoc_version

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

$ docker run --rm $IMAGE command_generator_vars aws_check_aoc_version

Which generates the following output:

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

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

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

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

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

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

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

aws_get_aoc_version

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

$ docker run --rm $IMAGE command_generator_vars aws_get_aoc_version

Which generates the following output:

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

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

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

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

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

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

aws_remove_labels

This playbook removes labels from the deployment.

$ docker run --rm $IMAGE command_generator_vars aws_remove_labels

Which generates the following output:

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

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

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

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

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

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