The deployment method

The deployment method indicates the deployment actions and steps. It is an input file, which can be created or modified by the enterprise architect only.

To make the most of the following explanations, you must be familiar with The Wazi Deploy workflow.

What is a deployment method

The deployment method is a YAML file that describes the actions to be completed on the artifacts of an application to be deployed. For example, a deployment method can be created to deploy the load modules and database request modules (DBRMs) of an application. So, the new load modules and DBRMs must be added and copied to partitioned data sets (PDSs), the updated ones must be updated and copied to PDSs, and the deleted ones must be deleted and removed from their PDSs.

The deployment method can also specify actions that are not related to an artifact, for example preprocessing or postprocessing actions. For example, an INITIALIZATION action can describe the preprocessing tasks.

This file is generic and can be reused for different applications. It corresponds to a type of deployment, such as the deployment of CICS® applications.

It is recommended to store the deployment methods in a Git repository different from the repository that contains the application source files.

The deployment method must not contain any information about the target environment. Its model is constrained and must follow a predefined model.

Structure and parameters

The following code shows a sample deployment method that is adapted to a static deployment.

---
apiVersion: deploy.ibm.com/v1
kind: DeploymentMethod
metadata:
  name: "CICS"
  version: "1.0.0"
  description: |
    This deployment method can be used for the deployment of a CICS application
  annotations:
    deployVersion: "1.0.0"

activities:
  - name: PACKAGE
    description: |
      This activity handles the package
    actions:
        - name: PACKAGE
          steps:
          - name: PACKAGE
    tags:
    - package
    
  - name: DEPLOY_MODULES
    description: |
      This activity is dedicated to the deployment of the artifacts into the PDS
    actions:
        - name: UPDATE
          description: |
            This action is applicable when artifacts are updated
          states:
             - UNDEFINED
          steps:
          - name: MEMBER_COPY
            description: |
              This step copies artifacts into PDSs
    types:
      - name: 'DBRM'
      - name: 'LOAD'
      - name: 'CICSLOAD'
      - name: 'MAPLOAD'
    is_artifact: True
    tags:
    - deploy_modules

  - name: DB2
    description: |
      This activity is dedicated to DBRM bind modules
    actions:
        - name: UPDATE
          description: |
            This action is applicable when DBRM modules are updated
          states:
             - UNDEFINED
          steps:
          - name: DB2_BIND_PACKAGE
          - name: DB2_BIND_PLAN
    types:
      - name: 'DBRM'
    is_artifact: True
    tags:
    - db2
        
  - name: CICS
    description: |
       This activity is dedicated to CICS load modules
    actions:
        - name: UPDATE
          states:
             - UNDEFINED
          steps:
          - name: PROG_UPDATE
            properties:
            - key: "template"
              value: "cics_cmci_prog_update"
    types:
      - name: 'CICSLOAD'
      - name: 'MAPLOAD'
    is_artifact: True
    tags:
    - cics

A deployment method is constituted of the following levels:

The metadata level
The activities level
The actions level, inside each activities level
The steps level, inside each actions level

The parameters are grouped and explained according to their level in the structure of the deployment method.

You can use the Wazi Deploy YAML schemas to validate the structure of the file.

The `metadata` level

metadata

name
Required
The name of the deployment method, between double quotation marks.
version
Required
The deployment method version number, between double quotation marks.
description
The optional description of the deployment method.
annotations
Annotations that can be associated with the deployment method. You can add any valid YAML properties under annotations.

The `rescue` level

This level is optional. It is a global rescue, which runs only if a step, an action, or an activity ended with a Failed status and if the error that caused the failure has not already been processed by other conditional deployment instructions.

To know when this rescue level is run, see the explanations on the rescue instruction in loop, when, failed_when, jumps_when, or rescue.

The `activities` level

activities

A set of ordered actions. Some standard activities are available but you can create your own activity. If the activity applies to artifacts, you must specify the types of the artifacts.

name
Required
The name of each activity.
short_name
The optional short name, whose length cannot exceed 30 characters. Only the following characters are valid: a-z, A-Z, 0-9, and _. You cannot use a white space.
The short name is displayed in the console during the deployment process.
description
The optional description of the activity.
types
Required if is_artifact is set to True
The types of artifacts that the activity applies to, if the activity applies to artifacts.
The types field is a list of types that are present in the package file. It corresponds to the extension of the artifacts in the .tar file. The following types are given only as examples:
- CICSLOAD
- DBRM
- LOAD
- MAPLOAD
is_artifact
Required if the activity, action, or step applies to artifacts
Values: True or False
A Boolean that specifies whether the activity, action, or step applies to artifacts.
tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Wazi Deploy generation command to include or exclude activities, actions, or steps during the generation of the application .tar file and of the deployment plan.

Note: As tags are propagated to the deployment plan at generation time, you can use them to include or exclude activities, actions, or steps in the deployment stage in The Python deployment command or The Ansible deployment command, if tags are not excluded explicitly in the Wazi Deploy generate command. For more information, see plan_tags in this section.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the generation if this string is specified in the --tags argument of the Wazi Deploy generation command.
  
  On the other hand, they are excluded from the generation if this string is specified in the --skipTags argument of the Wazi Deploy generation command.
- always.
  The activities, actions, and steps that include this string are always included in the generation, except if always is specified in the --skipTags argument of the Wazi Deploy generation command.
- never.
  The activities, actions, and steps that include this string are never included in the generation, except if never is specified in the --tags argument of the Wazi Deploy generation command.
If an action does not include any tags, it inherits the tags from its activity. If a step does not include any tags, it inherits the tags from its action or the tags from its activity if its action does not include any tags.
plan_tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Python deployment command or The Ansible deployment command to include or exclude activities, actions, or steps in the deployment stage.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to plan_tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the deployment if this string is specified in the planTags argument of the deployment command.
  
  On the other hand, the activities, actions, and steps are excluded from the deployment if this string is specified in the planSkipTags argument of the deployment command.
  
  Notes:
  For the Wazi Deploy Python deployment command, you can select at deployment time which plan_tags are to be considered by using the --planTags and --planSkipTags arguments. In these arguments, you give a list of plan_tags separated by a comma.
  
  For the Ansible deployment command, you can select at deployment time which plan_tags are to be considered by using the planTags and planSkipTags variables that you can specify in your Ansible inventory. In these variables, you give a list of plan_tags separated by a comma.
  Important: These tags are not at all related to the Ansible native tags and skipTags options.
- always.
  The activities, actions, and steps that include this string are always included in the deployment, except if always is specified in the planSkipTags argument of the deployment command.
- never.
  The activities, actions, and steps that include this string are never included in the deployment, except if never is specified in the planTags argument of the deployment command.
If an action does not include any plan_tags, it inherits the plan_tags from its activity. If a step does not include any plan_tags, it inherits the plan_tags from its action or the plan_tags from its activity if its action does not include any plan_tags.
properties
A pair of key and associated value.
Note: You can use the following predefined properties to filter the artifacts that you want to use for the activity, action, or step: path_filter, name_filter, and type_filter. You enter the value of such properties with a regular expression. For example, you can specify the path_filter property in the following way:
```
properties:
- key: "path_filter"
  value: "cmds_files/.\*"
```
loop, when, failed_when, jumps_when, or rescue.
Instructions that you can use to specify conditions on an activity, an action, or a step:
- loop to iteratively run the activity, action, or step.
- when to specify a condition that must return True for the activity, action, or step to run. If this instruction is used on the same activity, action, or step as a loop instruction, then the loop is restricted to the items that meet the condition.
- failed_when to set the status of the current activity, action, or step result to Failed or Successful if the condition is met.
- jumps_when to jump to the specified target location at the end of the current activity, action, or step if the condition is met. The activity, action, or step mentioned in the target location must have a short_name attribute.
- rescue to jump to a target step, action, or activity if the execution status of a step, an action, or an activity is Failed and if no failed_when or jumps_when has already run on the step, action, or activity. The activity, action, or step mentioned in the target location must have a short_name attribute. No condition is indicated.
  If a rescue is found at the failed level (step, then action, and finally activity), it is run. Eventually, if the error is not handled at the activity level, the rescue instruction specified at the root level of the deployment method is run if it exists. If none exists, the deployment ends with an error.
If these instructions are specified on the same step, action, or activity, they are processed in the following precedence order: loop, when, failed_when, jumps_when, and rescue. The loop and when instructions are always run. The failed_when, jumps_when, and rescue are exclusive of one another.

If several conditions apply to the same activity, action, or step, you can combine the conditions by creating YAML lists or use an or operator between the conditions.

See Syntax of the conditional deployment to know how you can specify a condition for the deployment.

The `actions` level

actions

The ordered list of the actions to be completed for the activity. If the action applies to artifacts, it is completed if the state of the artifact is one of the states that are associated with the action.

name
Required
The name of each action. You can enter any name.
short_name
The optional short name, whose length cannot exceed 30 characters. Only the following characters are valid: a-z, A-Z, 0-9, and _. You cannot use a white space.
The short name is displayed in the console during the deployment process.
description
The optional description of the action.
types
Required if is_artifact is set to True
The types of artifacts that the action applies to, if the action applies to artifacts.
The types field is a list of types that are present in the package file. It corresponds to the extension of the artifacts in the .tar file. The following types are given only as examples:
- CICSLOAD
- DBRM
- LOAD
- MAPLOAD
If types is present in the action, it overrides the activity types.
states
The states of the artifacts that the action applies to, if the action applies to artifacts.

In a static deployment, only the UNDEFINED and DELETED states are managed. If you do not specify any state, the default value is UNDEFINED.
tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Wazi Deploy generation command to include or exclude activities, actions, or steps during the generation of the application .tar file and of the deployment plan.

Note: As tags are propagated to the deployment plan at generation time, you can use them to include or exclude activities, actions, or steps in the deployment stage in The Python deployment command or The Ansible deployment command, if tags are not excluded explicitly in the Wazi Deploy generate command. For more information, see plan_tags in this section.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the generation if this string is specified in the --tags argument of the Wazi Deploy generation command.
  
  On the other hand, they are excluded from the generation if this string is specified in the --skipTags argument of the Wazi Deploy generation command.
- always.
  The activities, actions, and steps that include this string are always included in the generation, except if always is specified in the --skipTags argument of the Wazi Deploy generation command.
- never.
  The activities, actions, and steps that include this string are never included in the generation, except if never is specified in the --tags argument of the Wazi Deploy generation command.
If an action does not include any tags, it inherits the tags from its activity. If a step does not include any tags, it inherits the tags from its action or the tags from its activity if its action does not include any tags.
plan_tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Python deployment command or The Ansible deployment command to include or exclude activities, actions, or steps in the deployment stage.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to plan_tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the deployment if this string is specified in the planTags argument of the deployment command.
  
  On the other hand, the activities, actions, and steps are excluded from the deployment if this string is specified in the planSkipTags argument of the deployment command.
  
  Notes:
  For the Wazi Deploy Python deployment command, you can select at deployment time which plan_tags are to be considered by using the --planTags and --planSkipTags arguments. In these arguments, you give a list of plan_tags separated by a comma.
  
  For the Ansible deployment command, you can select at deployment time which plan_tags are to be considered by using the planTags and planSkipTags variables that you can specify in your Ansible inventory. In these variables, you give a list of plan_tags separated by a comma.
  Important: These tags are not at all related to the Ansible native tags and skipTags options.
- always.
  The activities, actions, and steps that include this string are always included in the deployment, except if always is specified in the planSkipTags argument of the deployment command.
- never.
  The activities, actions, and steps that include this string are never included in the deployment, except if never is specified in the planTags argument of the deployment command.
If an action does not include any plan_tags, it inherits the plan_tags from its activity. If a step does not include any plan_tags, it inherits the plan_tags from its action or the plan_tags from its activity if its action does not include any plan_tags.
properties
A pair of key and associated value.
Note: You can use the following predefined properties to filter the artifacts that you want to use for the activity, action, or step: path_filter, name_filter, and type_filter. You enter the value of such properties with a regular expression. For example, you can specify the path_filter property in the following way:
```
properties:
- key: "path_filter"
  value: "cmds_files/.\*"
```
loop, when, failed_when, jumps_when, or rescue.
Instructions that you can use to specify conditions on an activity, an action, or a step:
- loop to iteratively run the activity, action, or step.
- when to specify a condition that must return True for the activity, action, or step to run. If this instruction is used on the same activity, action, or step as a loop instruction, then the loop is restricted to the items that meet the condition.
- failed_when to set the status of the current activity, action, or step result to Failed or Successful if the condition is met.
- jumps_when to jump to the specified target location at the end of the current activity, action, or step if the condition is met. The activity, action, or step mentioned in the target location must have a short_name attribute.
- rescue to jump to a target step, action, or activity if the execution status of a step, an action, or an activity is Failed and if no failed_when or jumps_when has already run on the step, action, or activity. The activity, action, or step mentioned in the target location must have a short_name attribute. No condition is indicated.
  If a rescue is found at the failed level (step, then action, and finally activity), it is run. Eventually, if the error is not handled at the activity level, the rescue instruction specified at the root level of the deployment method is run if it exists. If none exists, the deployment ends with an error.
If these instructions are specified on the same step, action, or activity, they are processed in the following precedence order: loop, when, failed_when, jumps_when, and rescue. The loop and when instructions are always run. The failed_when, jumps_when, and rescue are exclusive of one another.

If several conditions apply to the same activity, action, or step, you can combine the conditions by creating YAML lists or use an or operator between the conditions.

See Syntax of the conditional deployment to know how you can specify a condition for the deployment.

The `steps` level

steps

A command that is part of an action. Each step must be implemented by an Ansible or Python building block on the targeted z/OS environment.

name
Required
The name of each step. Uppercase and lowercase letters are equivalent.

A step is implemented by a building block.

One of the ways to call a building block is to enter the exact name of the building block in the step name of the deployment method. See How to trigger the execution of a building block to know how else you can call a building block to implement a step processing.

Example: The first step of a deployment method is usually the PACKAGE step. Embedded in a PACKAGE activity and a PACKAGE action, it calls the package building block that handles the application package file.
short_name
The optional short name, whose length cannot exceed 30 characters. Only the following characters are valid: a-z, A-Z, 0-9, and _. You cannot use a white space.
The short name of a step can be used to trigger the execution of the building block that implements the step. See How to trigger the execution of a building block.
description
The optional description of the step.
types
Required if is_artifact is set to True
The types of artifacts that the step applies to, if the step applies to artifacts.
The types field is a list of types that are present in the package file. It corresponds to the extension of the artifacts in the .tar file. The following types are given only as examples:
- CICSLOAD
- DBRM
- LOAD
- MAPLOAD
If types is present in the step, it overrides the action types if present, or the activity types if types is not present in the action.
tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Wazi Deploy generation command to include or exclude activities, actions, or steps during the generation of the application .tar file and of the deployment plan.

Note: As tags are propagated to the deployment plan at generation time, you can use them to include or exclude activities, actions, or steps in the deployment stage in The Python deployment command or The Ansible deployment command, if tags are not excluded explicitly in the Wazi Deploy generate command. For more information, see plan_tags in this section.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the generation if this string is specified in the --tags argument of the Wazi Deploy generation command.
  
  On the other hand, they are excluded from the generation if this string is specified in the --skipTags argument of the Wazi Deploy generation command.
- always.
  The activities, actions, and steps that include this string are always included in the generation, except if always is specified in the --skipTags argument of the Wazi Deploy generation command.
- never.
  The activities, actions, and steps that include this string are never included in the generation, except if never is specified in the --tags argument of the Wazi Deploy generation command.
If an action does not include any tags, it inherits the tags from its activity. If a step does not include any tags, it inherits the tags from its action or the tags from its activity if its action does not include any tags.
plan_tags
A string that can be associated with an activity, an action, or a step. It can be used in the The Python deployment command or The Ansible deployment command to include or exclude activities, actions, or steps in the deployment stage.

If tags and plan_tags are indicated on the same activity, action, or step, plan_tags takes precedence and the tags values are not propagated to the deployment plan.
You can assign the following values to plan_tags:
- Any string with the following characters: a-z, A-Z, 0-9, and _.
  The activities, actions, and steps that include this string are included in the deployment if this string is specified in the planTags argument of the deployment command.
  
  On the other hand, the activities, actions, and steps are excluded from the deployment if this string is specified in the planSkipTags argument of the deployment command.
  
  Notes:
  For the Wazi Deploy Python deployment command, you can select at deployment time which plan_tags are to be considered by using the --planTags and --planSkipTags arguments. In these arguments, you give a list of plan_tags separated by a comma.
  
  For the Ansible deployment command, you can select at deployment time which plan_tags are to be considered by using the planTags and planSkipTags variables that you can specify in your Ansible inventory. In these variables, you give a list of plan_tags separated by a comma.
  Important: These tags are not at all related to the Ansible native tags and skipTags options.
- always.
  The activities, actions, and steps that include this string are always included in the deployment, except if always is specified in the planSkipTags argument of the deployment command.
- never.
  The activities, actions, and steps that include this string are never included in the deployment, except if never is specified in the planTags argument of the deployment command.
If an action does not include any plan_tags, it inherits the plan_tags from its activity. If a step does not include any plan_tags, it inherits the plan_tags from its action or the plan_tags from its activity if its action does not include any plan_tags.
properties
A pair of key and associated value.

Some properties have a specific use. Their values are used by the building blocks. See The building blocks for the Ansible and Python translators.
The values of some of these properties overwrite the default values of the variables in the environment variables file. The following properties are used by the building blocks:
- A properties element whose key field is set to template and whose value field is the name of the building block, such as cics_cmci_prog_create.
  For example, to call cics_cmci_prog_create to implement a PROG_CREATE step, you can enter the following code in the deployment method:
```
actions:
    - name: RUN A CICS CMCI PROG CREATE
      short_name: CICS_PROG_CREATE 
      steps:  
      - name: TEST STEP FOR PROG_CREATE
        short_name: PROG_CREATE_TEST 
        properties:
        - key: template
          value: cics_cmci_prog_create
```
- A properties element whose key field is set to var_template and whose value field is the name of the variable that contains the building block name. The variable is declared in the environment variables file.
  For example, to call the cics_cmci_prog_create building block to implement a PROG_CREATE step, you can enter the following code in the deployment method:
```
actions:
    - name: RUN A CICS CMCI PROG CREATE
      short_name: CICS_PROG_CREATE 
      steps:  
      - name: TEST STEP FOR PROG_CREATE
        short_name: PROG_CREATE_TEST 
        properties:
        - key: var_template
          value: PROG_CREATE_BLOCK
```
  In the environment variables file used by the building block, enter the following line to define the PROG_CREATE_BLOCK variable that represents cics_cmci_prog_create:
```
PROG_CREATE_BLOCK: cics_cmci_prog_create
```
- A properties element that overwrites the default variable from the environment variables file. Its key field must contain the variable that the building block expects. Its value field must contain the name of the variable whose value must be set in the environment variables file.
  Example: If a step of the deployment method is implemented by the job_submit building block, then you can enter, in the step of the deployment method, a var_job_submit key and set its value to a string, such as my_var_job_submit.
```
actions:
    - name: SUBMIT A JCL TO RUN A JOB
      short_name: SUBMIT_JCL
      steps:
      - name: TEST STEP FOR THE SUBMISSION OF A JCL
        short_name: JOB_TEST
        properties:
        - key: template
          value: job_submit
        - key: var_job_submit
          value: my_var_job_submit

is_artifact: False
```
  Then, you must assign the real value to this string in the environment variables file.
  
  In the Ansible environment variables file, you can enter the following code:
  my_var_job_submit: src: '/tmp/HELLO1.JCL' location: "USS"
  
  In the Python environment variables file, you can enter the following code:
  my_var_job_submit: src: 'tmp/HELLO1.jcl' max_rc: 8 wait_time_s: 25
  If you do not use the deployment method to indicate the variable that the building block expects, then the building block uses the default variable from the environment variables file.
  You can define properties that are specific to your situation and then manage these properties in your own building blocks because properties are propagated to the deployment plan.
  Note: You can use the following predefined properties to filter the artifacts that you want to use for the activity, action, or step: path_filter, name_filter, and type_filter. You enter the value of such properties with a regular expression. For example, you can specify the path_filter property in the following way:
  properties: - key: "path_filter" value: "cmds_files/.\*"
loop, when, failed_when, jumps_when, or rescue.
Instructions that you can use to specify conditions on an activity, an action, or a step:
- loop to iteratively run the activity, action, or step.
- when to specify a condition that must return True for the activity, action, or step to run. If this instruction is used on the same activity, action, or step as a loop instruction, then the loop is restricted to the items that meet the condition.
- failed_when to set the status of the current activity, action, or step result to Failed or Successful if the condition is met.
- jumps_when to jump to the specified target location at the end of the current activity, action, or step if the condition is met. The activity, action, or step mentioned in the target location must have a short_name attribute.
- rescue to jump to a target step, action, or activity if the execution status of a step, an action, or an activity is Failed and if no failed_when or jumps_when has already run on the step, action, or activity. The activity, action, or step mentioned in the target location must have a short_name attribute. No condition is indicated.
  If a rescue is found at the failed level (step, then action, and finally activity), it is run. Eventually, if the error is not handled at the activity level, the rescue instruction specified at the root level of the deployment method is run if it exists. If none exists, the deployment ends with an error.
If these instructions are specified on the same step, action, or activity, they are processed in the following precedence order: loop, when, failed_when, jumps_when, and rescue. The loop and when instructions are always run. The failed_when, jumps_when, and rescue are exclusive of one another.

If several conditions apply to the same activity, action, or step, you can combine the conditions by creating YAML lists or use an or operator between the conditions.

See Syntax of the conditional deployment to know how you can specify a condition for the deployment.

Deployment method fragments to be reused in various deployment methods

You can include fragments in a deployment method. These fragments can be generic and reused in various deployments.

To reuse a fragment, create a YAML file for your fragment and call it from a deployment method with !include.

The following steps illustrate how you can declare and reuse a fragment.

Create a deployment_method_package.yml fragment. The following code is an example.

---
name: PACKAGE
short_name: PACKAGE
description: |
This activity handles the package
actions:
 - name: PACKAGE
   description: |
      This action handles the package
   steps:
   - name: PACKAGE
     description: |
        This step handles the package
tags:
- package

In your deployment method, call this fragment, like in the following example:

---
apiVersion: deploy.ibm.com/v1
kind: DeploymentMethod
metadata:
 name: "CICS"
 version: "1.0.0"
 description: |
   This deployment method can be used for the deployment of a CICS application.
 annotations:
   deployVersion: "1.0.0"
activities:
 - !include deployment_method_package.yml

The deployment method

What is a deployment method

Structure and parameters

The metadata level

The rescue level

The activities level