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
- A GCP credentials file
- An internet connection to Google Cloud
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: gcp_upgrade Description: Performs the upgrade of the Ansible Automation Platform from GCP Marketplace components to the latest version. ----------------------------------------------- Performs the upgrade of the Ansible Automation Platform from GCP Marketplace components to the latest version. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_upgrade [--ansible-config ansible_config_path>] \ -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'gcp_compute_region=<gcp_compute_region> gcp_compute_zone=<gcp_compute_zone> gcp_backup_taken=<true|false>' ===============================================
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
gcp_backup_deploymentplaybook.$ docker run --rm -v <local_data_file_directory>:/data $IMAGE command_generator_vars gcp_backup_deployment \ --output-data-file /data/backup.yml
Producing the following output.
=============================================== Playbook: gcp_backup_deployment Description: This playbook is used to backup the AoC Self-managed GCP environment. ----------------------------------------------- This playbook is used to backup the AoC Self-managed GCP environment. For more information regarding backup and restore, visit our official documentation - ----------------------------------------------- Command generator template: docker run --rm -v /tmp:/data $IMAGE command_generator gcp_backup_deployment --data-file /data/backup.yml Data template: gcp_backup_deployment: cloud_credentials_path: deployment_name: extra_vars: gcp_bucket_backup_name: gcp_compute_region: gcp_compute_zone: ===============================================
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
gcp_backup_deploymentplaybook, the file becomes:gcp_backup_deployment cloud_credentials_path: /path/to/credentials deployment_name: my-deployment extra_vars: cp_bucket_backup_name: my-bucket gcp_compute_region: us-east1 gcp_compute_zone: us-east1-b
7.5. Running the generated command
Procedure
Ensure that the mounted volume points to the directory where the data file is.
For the
gcp_backup_deploymentplaybook example, this is:$ docker run --rm -v /tmp:/data $IMAGE command_generator gcp_backup_deployment --data-file /data/backup.yml
Which generates the following output:
Command to run playbook: $ docker run --rm --env PLATFORM=GCP -v /path/to/credentials:/home/runner/.gcp/credentials:ro \ --env ANSIBLE_CONFIG=../gcp-ansible.cfg $IMAGE\ redhat.ansible_on_clouds.gcp_backup_deployment \ -e 'gcp_service_account_credentials_json_path=/home/runner/.gcp/credentials \ gcp_deployment_name=my-deployment gcp_compute_region=us-east1 gcp_compute_zone=us-east1-b'
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.
gcp_aap_health_check
This playbook checks if the Ansible application is healthy.
$ docker run --rm $IMAGE command_generator_vars gcp_aap_health_check
Which generates the following output:
=============================================== Playbook: gcp_aap_health_check Description: This playbook checks if the deployment is healthy using the Ansible health service. ----------------------------------------------- The health check consists of checking the Ansible Automation Platform from GCP Marketplace environemnt to verify it is healthy. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_aap_health_check [--ansible-config ansible_config_path>] -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'gcp_compute_region=<gcp_compute_region> gcp_compute_zone=<gcp_compute_zone>' ===============================================
Launching this command by replacing the parameters generates a new command to launch and outputs:
... PLAY RECAP ********************************************************************* localhost : ok=29 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
A failed not equal zero indicates an issue with Ansible on Cloud deployment.
gcp_add_labels
This playbook adds labels to the deployment.
$ docker run --rm $IMAGE command_generator_vars gcp_add_labels
Which generates the following output:
=============================================== Playbook: gcp_add_labels Description: This playbook adds labels to the deployment. ----------------------------------------------- Add labels to the Ansible Automation Platform from GCP Marketplace deployment. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_add_labels -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'gcp_compute_region=<gcp_compute_region> gcp_compute_zone=<gcp_compute_zone> gcp_labels=<gcp_labels>' ===============================================
The parameter gcp_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
gcp_remove_labels
This playbook removes labels from the deployment.
$ docker run --rm $IMAGE command_generator_vars gcp_remove_labels
Which generates the following output:
=============================================== Playbook: gcp_remove_labels Description: This playbook removes labels from the deployment. ----------------------------------------------- Remove labels from the Ansible Automation Platform from GCP Marketplace deployment. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_remove_labels -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'gcp_compute_region=<gcp_compute_region> gcp_compute_zone=<gcp_compute_zone> gcp_labels=<gcp_labels>' ===============================================
The parameter gcp_labels is a comma separated list of keys to remove. For example: key1,key2
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
gcp_check_aoc_version
This playbook checks if 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 gcp_check_aoc_version
Which generates the following output:
=============================================== Playbook: gcp_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 gcp_check_aoc_version [--ansible-config ansible_config_path>] -c <cloud_credentials_path> -d <deployment_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] ***
ok: [localhost] => {
"changed": false,
"msg": "This operation playbook version and the Ansible on Clouds deployment version are identical: 2.4.20230606-00"
}
PLAY RECAP *********************************************************************
localhost : ok=8 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
A failed not equal zero means 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.
gcp_get_aoc_version
This playbook retrieves the version of the Ansible on Clouds deployment.
$ docker run --rm $IMAGE command_generator_vars gcp_get_aoc_version
Which generates the following output:
=============================================== Playbook: gcp_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 gcp_get_aoc_version [--ansible-config ansible_config_path>] -c <cloud_credentials_path> -d <deployment_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.20230606-00"
}
PLAY RECAP *********************************************************************
localhost : ok=5 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0gcp_health_check
This playbook checks if the nodes and Ansible application are healthy.
$ docker run --rm $IMAGE command_generator_vars gcp_health_check
Which generates the following output:
=============================================== Playbook: gcp_health_check Description: This playbook checks if the Ansible Automation Platform from GCP Marketplace deployment is healthy. ----------------------------------------------- The health check consists of checking the Ansible Automation Platform from GCP Marketplace heatlh checks and the health of the monitoring exporter. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_health_check [--ansible-config ansible_config_path>] -c <cloud_credentials_path> -d <deployment_name> --extra-vars 'gcp_compute_region=<gcp_compute_region> gcp_compute_zone=<gcp_compute_zone>' ===============================================
Launching this command by replacing the parameters will generate a new command to launch and will output:
... PLAY RECAP ********************************************************************* localhost : ok=47 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
A failed not equal zero indicates an issue with nodes or the Ansible on Cloud deployment.
gcp_list_deployments
This playbook list the deployments, the region and zone are optional.
$ docker run --rm $IMAGE command_generator_vars gcp_list_deployments
Which generates the following output:
=============================================== Playbook: gcp_list_deployments Description: This playbook generates a list of available Ansible Automation Platform from GCP Marketplace deployments. ----------------------------------------------- This playbook is used to generate a list of available Ansible Automation Platform from GCP Marketplace deployments. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_list_deployments -c <cloud_credentials_path> --extra-vars '[gcp_compute_region=<gcp_compute_region>] [gcp_compute_zone=<gcp_compute_zone>]' ===============================================
Launching this command by replacing the parameters generates a new command to launch and outputs:
...
TASK [Show deployment list] ****************************************************
ok: [localhost] => {
"msg": [
"Deployment list: ['dep1', 'dep2', 'dep3']"
]
}
PLAY RECAP *********************************************************************
localhost : ok=7 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0gcp_nodes_health_check
This playbook checks if the nodes are healthy.
$ docker run --rm $IMAGE command_generator_vars gcp_nodes_health_check
Which generates the following output:
=============================================== Playbook: gcp_nodes_health_check Description: This role runs a health check on a group of nodes in the Ansible Automation Platform from GCP Marketplace deployment ----------------------------------------------- The playbook checks if the Ansible Automation Platform from GCP Marketplace monitoring exporter is up and running. ----------------------------------------------- Command generator template: docker run --rm $IMAGE command_generator gcp_nodes_health_check [--ansible-config ansible_config_path>] -d <deployment_name> -c <cloud_credentials_path> --extra-vars 'check_monitoring=True' ===============================================
Launching this command by replacing the parameters generates a new command to launch and outputs:
... PLAY RECAP ********************************************************************* localhost : ok=47 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
A failed not equal zero indicates an issue with nodes in the deployment.