Actions

Edit online

In the actions section, you can define shell actions that the composite template executes at the time of applying the template in both provisioning and migration mode. For example, if you want to ensure that you have the system resources required for a provisioning operation, you can define a shell action in the composite template definition that will check the system resources before starting the provisioning operation.

The actions defined in the template are executed as remote actions on the target hosts, using the details of the SSH connection defined for the target host in the bootstrapInfo section under nodes. The actions are executed on the Command Central server host as local actions only when:

  • The actions are defined in the environments section.
  • The actions are executed on the local node.

Each action is defined either inline in the composite template or in an external file located on the Command Central server, the target node, or in the composite template archive. Based on the section in which you include an actions section, Command Central will execute the actions in a different way. The following table describes how the actions in the different sections are executed:

The actions in this section are executed
environment/default/actions on the local node for all types of environments.
layers/default/actions on the remote nodes for all layers, except for the layers that map to the local node.
templates/default/actions on the remote nodes for all templates, except for the templates applied on the local node.
nodes/default/actions on all nodes. If the action is executed for the local node, it is a local action.
environments/environment.type/actions on the local node, only for this environment type.
layers/layerAlias /actions when processing the layer with the specified alias. If the layer maps to the local node, the actions are executed as local actions.
templates/templateAlias /actions when processing the inline template with the specified alias. If the template is applied on the local node, the actions are executed as local actions.
nodes/nodeAlias /actions on the node with the specified alias.

Action Parameters

The following table lists and describes the parameters, included in the actions section:

Parameter Description
actionName: Required. The name of the action. If the action is executed on Windows, the name of the action ends with ".bat", for example: actionName.bat:
description: Optional. States the goal of the action.
phase: {pre | post} Optional. Specifies whether to execute the actions before or after the operation defined in the composite template section. For example, in the nodes/default/actions section, if phase:pre, the actions are executed before bootstrapping Platform Manager. If phase:post, the actions are executed after bootstrapping Platform Manager. The actions defined in the default sub-sections of top level sections are executed as follows:
  • Default actions with the phase:pre parameters are executed before regular pre actions.
  • Default actions with the phase:post parameters are executed after regular post actions.

Default: phase: post


                              failOnError: {true | false}
                          
Indicates whether applying the composite template will fail if the action fails with an error. Valid values:
  • true (default) - The composite template apply operation fails.
  • false - The composite template apply operation ignores the error and continues processing the composite template.
script: Required when you do not specify the file property. Includes script commands, defined inline.

When the shell scripts are included inline, the shell variables using the notation ${var} are evaluated against the properties defined in the composite template. The shell variables using the notation $var are not evaluated against the properties defined in the composite template and the script is executed as it stands.

To avoid exposing the password in plain text, you can include the credentials alias that matches the username or password for different sets of credentials (such as Platform Manager or repo credentials) as follows:
${@credentials.credentialsAlias.password}
${@credentials.credentialsAlias.username}

If you include both script and file properties, Command Central uses the script property and ignores the file property.

file: Required when you do not specify the script property. Specifies either the absolute or the relative location path to an external script file. If you specify a relative location path to the composite template archive, the file is taken from the template archive. For example, file: scripts/main.sh
target: POSIX | WINDOWS Optional. Indicates on which operating systems to execute the action. Valid values:
  • POSIX (default) - the action is executed on POSIX-compliant operating systems.
  • WINDOWS - the action is executed only on Windows operating systems.
namePrefix: hexTimestamp | none Optional. Indicates whether Command Central adds a prefix to the names of action files created on the file system. Valid values:
  • hexTimestamp (default) - the filename for an action is prefixed by a hexadecimal representation of the timestamp at the time of template evaluation.
  • none - the filename for an action does not get a prefix.
skipOnTemplateError: {true | false} Optional. Indicates whether Command Central executes the action if applying the template fails with an ERROR status. Valid values:
  • true - does not execute the action.
  • false (default) - executes the action before stopping the template application.
verbose Optional. Indicates whether to include the standard output from the shell actions defined in the template in the Command Central logs. Valid values:
  • true - include the standard output.
  • false (default) - do not include the standard output.

Usage Notes

  • The script code in the shell action can use any interpreter available on the system, such as Perl, Python, or Ruby.
  • When you define actions under the templates section and you apply the template with environment.mode=provision, even if failOnError: true, the template does not fail if the action fails.
  • When configuring the target property for an action, you must consider the following:
    • For a local action, set target: WINDOWS if the operating system of the local node is Windows and you want to use a Windows script. If the local node has a Unix operating system and you want to use a Unix script, set target: POSIX.
    • For a remote action executed on a target host with a Windows operating system, ensure that the target host is configured for SSH access using the Windows OpenSSH Server. For more information about installing and using OpenSSH on Windows, see the official Microsoft documentation available here: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui&pivots=windows-11.
  • If applying the template fails at a certain operation, all actions pending execution after that operation are discarded and will not be executed. For example, if the template fails at the provisioning stage and the template includes an environment action with phase: POST, the action will not get executed.
  • By default Command Central completes all post actions defined in the template even when Command Central stops the template application because of a failed configuration or a layer startup failure. When you want to skip executing an action if applying the template fails, set skipOnTemplateError: true
  • Note that when setting verbose: true for actions that contain sensitive information (such as plain text passwords), the sensitive information will get included in the Command Central logs.

Example

In the following example, the actions section defines a “cleanUpEnvDefault” action that the composite template will execute after the provisioning operation for all environment types. The composite template application will fail if the action fails with an error. The script command is specified inline in the “script” property.

The “${temporary.data}” variable in the “rm -r” command of the inline script is evaluated against the properties defined in the composite template. If the composite template definition includes a property with name “temporary.data”, the script will use the value of that property. If the template does not include a “temporary.data” property, the script is executed as it stands. The script will use ADMINISTRATOR as the credentials alias for the Platform Manager node. The standard output from the “cleanUpEnvDefault” action will get included in the Command Central logs. 

environments: 
    default: 
      actions: 
        cleanUpEnvDefault: 
          description: “Default clean up of the environment after provisioning” 
          phase: post 
          failOnError: true
          verbose: true 
          script: |  
            #!/bin/sh 
            rm -r ${temporary.data}
            echo "The SPM username is ${@credentials.ADMINISTRATOR.username}"