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
  • 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.

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: 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

  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 gcp_backup_deployment playbook.

    $ docker run --rm -v <local_data_file_directory>:/data $IMAGE command_generator_vars gcp_backup_deployment \
    --output-data-file /data/backup.yml
  2. 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_generator automatically mounts a volume for it in the final command.

    For example, in the case of the gcp_backup_deployment playbook, 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

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

    For the gcp_backup_deployment playbook 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.

  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.

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=0

gcp_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=0

gcp_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.