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:
-
Pull the
ansible-on-clouds-opscontainer image. - List the available playbooks.
-
Use a command generator to generate a data file and the next command to run.
command_generator_varsand the command_generator are implemented using a docker container and are run using the docker command line interface. Populate the data file and run the previous generated command. This generates the final command with all parameters.
NoteWhen this step is complete, you can save the generated command and run the playbook when it is required.
- 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.
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
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
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
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_stackplaybook.$ docker run --rm -v <local_data_file_directory>:/data $IMAGE command_generator_vars aws_backup_stack \ --output-data-file /data/backup.yml
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_generatorautomatically mounts a volume for it in the final command.For example, in the case of the
aws_backup_stackplaybook, 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
Ensure that the mounted volume points to the directory where the data file is.
For the
aws_backup_stackplaybook 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.
- 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=0aws_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