The Ansible deployment command

Edit online

To deploy the application artifacts to the target z/OS® environment from a distributed environment, you must use the Wazi Deploy Ansible® translator. You run this translator by starting an Ansible command.

Installation requirements

Wazi Deploy and its prerequisites must be installed, as it is explained in the installation requirements.

Checks before the deployment

Wazi Deploy automatically controls the following conditions before it starts the deployment:
  • At least one Wazi Deploy callback must be installed.
  • The environment_vars root must be present in the target environment.
  • The ibm_zos_core Ansible collection must be 1.9.x or must be greater than or equal to 1.12 (1.12.1 or greater recommended).
  • If ibm_zos_core is 1.9.x, the IBM Z Open Automation Utilities (ZOAU) version must be between 1.2.4.x and 1.2.5.x.
  • If ibm_zos_core is greater than or equal to 1.12, the ZOAU version must be greater than or equal to 1.3.3.x.
  • If ibm_zos_cics Ansible is installed, its version must be greater than or equal to 1.0.6.
  • If ibm_zos_ims Ansible is installed, its version must be greater than or equal to 1.3.0.

If one of these conditions is not met, the deployment is not triggered.

The presence of the generic environment variables is also controlled. The variables that are not specified are displayed as warnings in the console and in The evidence file. For more information about the Ansible generic environment variables, see The generic environment variables for the Ansible and Python building blocks.

Configuration checks

Before you start the deployment, make sure that the following requirements are also met:
  • All the building blocks that implement the deployment steps must be available. If not, you must create the missing building blocks.
  • All the variables that are used by the building blocks must be assigned values in the Ansible variables environment file.
  • All the generic variables must be assigned values in the Ansible variables environment file. See The generic environment variables for Ansible.
  • An Ansible playbook (deploy.yml for example) must call the Wazi Deploy role in the following way:
    - hosts: "{{ wd_hosts if wd_hosts is defined else 'all' }}"
  gather_facts: "{{ wd_gather_facts if wd_gather_facts is defined else 'no' }}"
  serial: "{{ wd_serial if wd_serial is defined else 5 }}"
  tasks:
      - import_role:
          name: ibm.ibm_zos_wazi_deploy.zos_deploy
  • An ansible.cfg file must include the following contents:
    #####
[defaults]
forks = 25
host_key_checking = False
#callbacks_enabled = ibm.ibm_zos_wazi_deploy.cb_aggregate_evidences
stdout_callback = ibm.ibm_zos_wazi_deploy.cb_evidences
[ssh_connection]
pipelining = True
#ssh_args = -o ControlMaster=auto -o ControlPersist=3600s -o PreferredAuthentications=publickey
####

    If you are using Red Hat® Ansible Automation Platform or want to keep the default Ansible stdout callback, comment the stdout_callback line and uncomment the callbacks_enabled line.

    Important: The evidences that the Wazi Deploy building blocks create when they run are generated only if the ansible.cfg file contains the following line:
    stdout_callback = ibm.ibm_zos_wazi_deploy.cb_evidences
    By default, the evidences are generated in the current folder, in an evidences subfolder. You can change this subfolder in either of the following ways:
    • Add an entry in the ansible.cfg file by creating a section between squared brackets and by entering an evidences_folder property in this section like in the following example:
      [callback_evidences]
evidences_folder = /tmp/my_evidences_folder
    • Set the EVIDENCES_FOLDER environment variable before you run the Ansible deployment command like in the following example:
      export EVIDENCES_FOLDER=/tmp/my_evidences_folder

Syntax of the Ansible deployment command

When you are sure that the requirements are met, you can start the deployment by running the following command in Ansible:
ansible-playbook deploy.yml
Enter the following arguments for this command:
  • -i inventories to provide the variables of the building blocks.
  • -e wd_deployment_plan_file=<path to deployment_plan.yml> to specify the path to the generated deployment plan.
  • -e wd_package_file=<path to the package.tar> to specify the path to the package file that contains the artifacts of the application.

    If your deployment corresponds to deletions only, the package file does not exist and you do not specify this argument.

  • -e wd_log=True (optional) to increase the verbosity of the log messages.
For more information on how to specify the -e (extra-vars) arguments in the Ansible deployment command line, see Defining variables at runtime in the Ansible documentation. If an extra-vars argument is not a string, you must conform to the required input format.
Example: To declare a boolean variable as an extra-vars that you want to define, you must use a JSON format in the command line. Frame the variable with curly brackets and simple quotation marks. In the following example, you indicate that the extra-vars (named variable) is a boolean that must be set to True:
-e '{"variable": True}'
You can optionally indicate two types of extra-vars arguments to add filters to the deployment stage:
  • With the plan_tags argument in The deployment method, you include or exclude activities, actions, and steps.
    • With -e planTags=tag1,tag2, only the activities, actions, and steps that are tagged with these values in the generated deployment plan are included in the deployment. tag1 and tag2 are two examples of plan_tags values.
    • With -e planSkipTags=tag3,tag4, only the activities, actions, and steps that are tagged with these values in the generated deployment plan are excluded from the deployment. tag3 and tag4 are two examples of plan_tags values.
  • With the includes_artifacts or excludes_artifacts argument, you indicate a filter that applies to the artifacts to be included or excluded during the deployment phase. For each deployment, you can specify both filters or only one of them. A filter is a regular expression.

    In the following example, only the artifacts whose name contain LGA are to be deployed. For more information about the various ways to declare filters, see Deployment filters. 

    -e {"includes_artifacts": [".*LGA.*"]}
The following code is a sample of the deployment command in Ansible:
ansible-playbook deploy.yml \
  -i inventories\
  -e wd_deployment_plan_file=inputs/deployment_plan.yml\
  -e wd_package_file=inputs/package.tar