Actions Library

Overview

Actions Library is a framework that extends the CloudCenter platform capabilities by enabling you to create, manage, and execute actions for VM management. This framework allows administrators to define actions and execute them on different CloudCenter resources such a VMs, Deployments, or Application profiles. Association criteria defined as part of an action dictates which action is available for execution against which specific resource.

Custom Actions that were configurable in the Policies tab prior to CloudCenter 4.8.0 are now integrated into the Actions Library framework through the Invoke a Web Service action type as explained in the General Settings section later in this page.

Cloud Nuances

While the Actions Library is available for all CloudCenter Supported clouds.

Permissions and Access Control

Permissions define certain actions that users can perform. You can control the permissions for a custom action. See Permission Control > Actions Library Permissions for additional context.

The Actions Library Tab

The Actions Library tab in the CCM UI lists the custom actions that are created by users.

The numbers provided in the image above are identified as follows:

Markup No.IdentifierDescription
1Actions Library tabLocation to view and manage all custom actions in the CloudCenter platform.
2Search iconEnter the name of the custom action to search for the action – this function is useful if you create numerous actions that do not display on this page.
3Actions dropdown

As an action owner, you can perform the following functions on the VM:

  • Share actions to permit other users in your tenant or a group member to also access these custom actions.
  • Delete actions that you no longer need.
4Export icon

Export the entire list of custom actions displayed in the Actions Library tab to a actions.json file – this function is useful if you want to copy the same actions across CloudCenter installations or across different tenant hierarchies.

5Import icon

Import actions used on VMs outside this CloudCenter instance and add it to the list of custom actions – this function is useful if you have multiple instances of CloudCenter and need to configure the same custom actions in all CloudCenter instances. The import function allows you to get (import) the actions defined in another CloudCenter instance or tenant hierarchy into the current CloudCenter instance.

6

Enable (default)

or Disable actions

Enable (default) or Disable the action in the Actions Library page...

...so it is available/not available on the VM page.

Users who only have View permissions on these action cannot toggle this visibility. This setting is controlled by the action owner. See Permission Control for additional context.

 

Types of VM Actions

The types of actions available and visible for each VM for each user depends on the following factors:

  • The cloud being used (see Cloud Nuances for additional context).
  • The OS being used (see Platform actions and VM Management > Install CloudCenter Agent for additional context).
  • The current state of the VM, running or stopped, or other (see Platform Actions for additional context).
  • The permissions for the user implementing the action (see Permissions and Access Control for additional context).
  • The configured object mapping of custom action (see Custom Actions for additional context).

When you manage Virtual Machines, you can perform two types of actions that are executable on individual VMs or on multiple VMs as a batch.

  • Platform Actions: See the Platform Actions section below for additional details.
  • Custom Actions: See the Custom Actions section below for additional details.

Additionally, you can model the Invoke a Web Service custom action to appear for Application Profiles, Deployments, or Virtual Machines. See Custom Actions section below for additional details.

Platform Actions

Platform actions are defined by Cisco for the CloudCenter platform. You cannot modify or manage these actions – you can perform these when required on both CloudCenter Deployed and Imported VMs.

Basic Platform Actions

  • System-defined core actions.
  • Provided out-of-box by the CloudCenter platform.
  • Users cannot modify these actions.
  • Platform specific.
  • Available on all cloud instances.
  • Action Types: The following table identifies the VM action availability for VM resources.
Basic ActionsDescriptionVM Resources (Objects)
StartPower on and start the VMManaged VM
StopStop and power off the VMManaged VM
RebootAttempts a graceful shut down and restart of the VMManaged VM
Terminate

Stops and Remove the VM from the cloud.

  • Managed VM
  • Unmanaged VM
Import to CloudCenterImport a VM from the Unmanaged tab into the Managed category. See VM Management for additional context.Unmanaged VM
Upgrade Agent

Upgrade the agent on a Managed VM to the latest released CloudCenter agent version from the CCM UI. See VM Management > Upgrade Agent for additional details.

You can only upgrade a VM running CloudCenter 4.5 or later versions.

You must manually install the agent on a VM running CloudCenter 4.4 or earlier versions. See VM Management > Install Agent for additional details.

If the latest version of the agent is already installed on a VM, then this action will no longer be available for this VM.

Managed VM

Advanced Platform Actions

  • Core actions to support VM Management tasks on supported clouds.
  • Cloud-specific as identified in the Advanced Platform Actions table below.
  • Used to reconfigure the VM instance.
  • Action Types: The following table identifies the VM action availability, given the current VM state and Cloud type.

    Advance Actions

    DescriptionCurrent StateSupported Clouds

    Attach Volume


    Cisco does not support attaching existing volumes available in the cloud. If storage types are configured in the CCM, you can opt to input volume parameters.

    Cisco enables you to select if the storage types are configured in the CCM and input the volume parameters using this option.

    • Running
    • Stopped

    • Amazon
    • OpenStack

    • VMware

    • vCD*

    • Google*

    Detach VolumeDetaches the volumes from the existing VM.
    • Running
    • Stopped

    Resize Instance TypeResize the VM's instance type or change the CPU and memory size.
    Select the instance type configured in the CCM for the required cloud.

    Stopped

    For OpenStack, it is both Running and Stopped states.


    • Amazon
    • OpenStack

    • VMware

    Create SnapshotCreates the image snapshot for the given VM.
    • Running
    • Stopped

    VMware
    Install CloudCenter Agent

    Install the agent on an Imported VM from the CCM UI. See VM Management > Install Agent for additional details.

    If the latest version of the agent is already installed on a VM, then then this action will no longer be available for this VM.

    Running
    • Amazon
    • Azure RM
    • OpenStack

    • VMware

    • vCD*
    • Google*

    For more information on VM states, see Deployment and VM States.
    * Effective CloudCenter 4.8.1

Custom Actions

You can define custom actions for CloudCenter deployed VM or imported VMS, and in some cases, even Deployments and Application Profiles by clicking the New Action link in the Actions Library page.

Defining Custom Actions

Every custom action that you define in the Custom Actions tab has the following areas of interaction:

  • General Settings – identifies general data.
  • Object Mappings – identifies where this action should be applied.
  • Action Definition – identifies how the execution should be executed. All supported action types have some default fields as well as the ability to enrich the action with Custom Fields. See the Action Definition section below for additional context.

After configuring the action, you can preview the action to see how the action is presented to the end user.

General Settings Section

Define the action properties (type, name, description) and identifies if the action must be executed internally or on a container.

The Action Timeout field allows you to program the action to timeout within a specified limit and defaults to 20 minutes. This field along with the Type, Action Name, and Description fields is available for all custom actions.

The following table identifies the available custom action Type along with a description and identifies examples for when you might use each type.

After you define an action, you cannot change the action type.

TypeDescription
Invoke a Web ServiceExecutes the designated web service request. For example, you can use this action type if you publish an application profile in your ServiceNow catalog.
Command or Script (Default)

Executes the designated command or script on the VM (see Deployment Lifecycle Scripts or Callout Scripts).

If you provide scripts that need to be executed as part of Action Library, be aware that a script is considered to be successful based on OS exit codes for script execution. This behavior is consistent with scripts that are run directly on a Windows or Linux server using their respective shells. Once a script is executed on Linux or Windows, the output shown on running echo $?, is the status code.
For example:

  • On Linux, script execution will be marked as Failed only if the script's last line failed to execute. In all other cases it will be marked as successful.
  • On Windows, scripts will be marked as Failed only if an explicit Exception is thrown.

For user-provided scripts, the onus is on the user to ensure that the script exits successfully.

This type additionally allows you to specify the following options:

  • Where to run this type of action: 
    • On Virtual Machine OS – On a VM with an agent installed. 
    • Externally – On a Docker container that runs on the CCO (not dependent on the worker image in any way). For example, if you need to configure external CLIs on a Docker container for a specific cloud, you can determine a Custom Field with the CLI items in a list format. See the Custom Field section below for additional details.
  • Reboot the VM after action execution – If the action owner determines that a reboot is required after the action execution, then end users using this action do not need to manually perform this extra step! An action owner refers to a user who creates (the New Action link) a custom action.
  • Sync VM information after action execution – This option allows you to update current VM information (for example, size from the cloud) from the CloudCenter platform so the latest VM metadata information like IP addresses are visible. You can perform this operation in bulk by multi-selecting several VMs, or just for one VM.

The possible execution modes for this option are based on your Execute from Bundle setting that is explained in the Action Definition Section later in this page:

  • Download From Bundle is True
    1. The content in Script From Bundle is presumed to be a script inside the bundle specified. 
    2. The bundle is presumed to be an archive (zip/tar/tgz/tar.gz) that is extracted and the file is searched and executed along with any other command line parameters.
  • Download From Bundle is False
    1. The content in the Executable Command field is presumed to be a series of commands separated by semicolons.
    2. A special case is that the first command in this series of commands can be a Script URL. Thus the first command, if a script URL, is processed by first downloading the script and then it is executed along with the rest of the following commands.
Invoke Cisco UCS Director Workflow

Only applicable for VMs that invoke the workflow in a UCSD server (see Configure a Cisco UCSD Cloud for additional context).

Chef

Applicable for both CloudCenter deployed VMs and Imported VMs. See Chef for additional context.

Puppet

Applicable for both CloudCenter deployed VMs and Imported VMs.  See Puppet for additional context.

To run Puppet actions on CloudCenter instance, you must first disable the requiretty setting for that instance in the /etc/sudoers file.

AnsibleApplicable for both CloudCenter deployed VMs and Imported VMs.

Object Mapping Section

Configure at least one or more mappings for each action by specifying the type of custom actions to apply this action so end users can view and invoke the permitted action.

You cannot invoke custom actions from the Job Details page. Navigate to the VM details page or the Virtual Machine tab to view and invoke an action.

Once you add mappings, the Object Mapping area displays the objects by order of highest priority (ALL). You can directly delete unwanted mappings by clicking the Delete icon. You can configure any number of mappings for a custom action – multiple mappings gives action creators the flexibility and power to define the granularity of a mapping on both CloudCenter deployed or Imported VMs. See the table after the image for details on every action type.

This section is key to using any Action type. More details on default and custom fields are captured below.

The following table identifies the available Type along with a brief description and identifies the permitted resources for Object Mapping. Each map automatically lists the corresponding fields that you can configure for each map.

TypeObject Mapping (Permitted Resources)Description
Invoke a Web Service

Deployment

  • Deployment Environment: Identify if this action should map to deployments for all CloudCenter supported clouds or for specific clouds. Default = All clouds.
  • Service: Identify if this mapping is intended for all available services or for specific services. Default = All services.
Virtual Machines
  • Application Profile: Identify if this mapping is intended for all application profiles or for specific profiles. Default = All application profiles.
  • Service: Identify if this mapping is intended for all available services or for specific services. Default = All services.
  • Cloud Region: Identify if this mapping is intended for all cloud regions or for specific regions. Default = All cloud regions.
  • Cloud Account: Identify if this mapping is intended for all cloud accounts or for specific accounts. Default = All clouds accounts.
Application Profiles

This option does not contain any configurable fields as the action is applied to all Application Profiles.

  • Command or Script (Default)
  • Invoke Cisco UCS Director Workflow
  • Chef
  • Puppet
  • Ansible

CloudCenter Deployed VMs

  • Application Profile: Identify if this mapping is intended for all application profiles or for specific profiles. Default = All application profiles.
  • Service: Identify if this mapping is intended for all available services or for specific services. Default = All services.
  • Cloud Region: Identify if this mapping is intended for all cloud regions or for specific regions. Default = All cloud regions.
  • Cloud Account: Identify if this mapping is intended for all cloud accounts or for specific accounts. Default = All clouds accounts.

Imported VMs (with agent installed)

  • Cloud Region: Identify if this mapping is intended for all cloud regions or for specific regions. Default = All cloud regions.
  • Cloud Account: Identify if this mapping is intended for all cloud accounts or for specific accounts. Default = All clouds accounts.
  • OS Types: Identify if this mapping is intended for Linux or Windows operating systems. Default = All

Action Definition Section

The following table identifies the available Type along with a brief description and identifies the permitted resources for Object Mapping.

TypeFieldsNotes
Invoke a Web Service      

Protocol

The transfer protocol to be used by this action when invoking the service – select HTTP or HTTPS.

Web Service URL

The URL used for the web service using the following format:
<host>:<port>/<resource>/<parameter>
For example: webserver.cliqrtech.com:3000/users/post

Use Case: You can also introduce a custom parameter in the Web Service URL field and define that parameter in the Custom Fields section (described below). For example, if you introduce a custom parameter called call the URL:

Define the call parameter in the Custom Fields section to ensure that this parameter is replaced by the value defined in that section:

Username and Password:Credentials required to issue the web service call
HTTP Request Type
  • PUT
  • GET
  • POST
  • DELETE
Content TypeIf the body content should be sent using the JSON or XML format
BodyThe request body contents to be used when issuing the API call for this action.
Command or Script (Default)

Execute From Bundle

If you choose to configure this setting, provide the following details:

  • Location: Select from a list of previously-configured repositories as described in the Share Artifact Repositories section. If repositories have not been configured, you must use the default URL option and provide the entire URL.
  • Relative Path: Specify the path to the folder where the script bundle resides. The CloudCenter platform appends this path to the hostname defined in the repository. All compressed file formats (.tar, .zip, etc.) are acceptable in this field.
  • Script from Bundle: Provide the name of the script that this action should use.

Use Case: To create a new custom action called Add Web Service, use a custom script that already contains the parameter definitions. When you call the script, the defined parameters are displayed in the Custom Fields section. For example, if you had defined two custom parameters called PRM1 to display Test and PRM2 to display Hello in the script and configured the parameters to obtain their values from a webservice type:

Then the custom values are displayed in the resulting popup for this custom action. Preview the Add Web Service popup by clicking the Preview button located in the lower right corner of the New Action page:

When end users see this popup, they can select a value displayed in the dropdown:

After you save the new custom action, the Add Web Service action is displayed with the other actions for this VM:

The newly configured Add-Web-Service action popup displays the type of action and the Node name to identity the action being used in the action. When you use this custom action, you see the History tab updated with the relevant details. This action required two numbers to be added, and the sum of those numbers is displayed (and highlighted) in the History logs.

Imported VMs with AgentLite installed can execute custom scripts/commands. Effective CloudCenter 4.8.1, these scripts can additionally send status messages back to the CloudCenter platform if you invoke the actionSendMessage function within your scripts for custom actions.

To invoke the actionSendMessage function, follow this procedure.

  1. Download and install the Linux and Windows AgentLite bundle. See VM Management > Download AgentLite Bundle for additional context.
  2. Create a New Action to Execute from Bundle.
  3. Create a tar/tgz bundle for Linux and Zip for Windows, that contain the script files. The sample scripts are available in the following locations:

    #LINUX:
    <AGENT_HOME>/scripts/samples/checkActionSendMessage.sh
    
    #WINDOWS: 
    <AGENT_HOME>\scripts\samples\checkActionSendMessage.ps1
  4. The script invokes the actionSendMessage function and sends status messages to the CloudCenter platform.
    Locate the CCM and CCO log files to verify that each sent message is being received. See Locate Log Files for additional context.

    #SAMPLE CCO LOG
    Done executing
    ', status=SUCCEEDED, actionMessages=[ActionMessage
    {id=144354, message='Bundle was downloaded (and extracted if it was a 
    supported archive) at the location: 
    /opt/remoteFiles/checkActionSendMessage', timestamp=2017-08-01 
    02:04:53.458, resourceMessageId=10164, actionMessageStatus=IN_PROGRESS}
    
    
    #SAMPLE CCM LOG
    2017-08-01 02:04:53,782 DEBUG impl.DefaultNodeMessageListener [SimpleAsyncTaskExecutor-1]  - Received Message AgentStatusMessage 
    {
    	status = ActionExecuting
    	jobId = 0
    	nodeId = i-0ebd9fb0
    	taskId = 0
    	actionExecutionId = 9818
    	cloudResourceUniqueId = 4473
    	taskName = 
    	timestamp = Tue Aug 01 02:04:53 UTC 2017
    	helperNode = false
    	data = 
    	msg = ###yes###
    	keyValues = <null>
    	agentVersion = 4.8.1
    	agentType = BROWNFIELD
    }

Executable Command

If you choose to configure this option, provide the command that should be executed as part of the custom action.

Invoke Cisco UCS Director Workflow

API Key

The API key for the UCSD server.
UCSD ServerThe IP address of the UCSD server.
Workflow Name

The name of the workflow created in the UCSD serve – gshar in this example.

This workflow is automatically called by the custom action that you create in the CloudCenter platform:

All the fields configured in the workflow on the UCSD server...

... are displayed in the custom action popup in the CloudCenter platform.

Chef

Chef Server

A Chef server that is maintained by the user can be added to the CloudCenter repository list (see Share Artifact Repositories to configure a repository). A Chef server configured in a CloudCenter platform as a shared repository is referred to as a Chef repository. If multiple Chef repositories exist, they are listed in the dropdown menu and you must pick one of the configured Chef repositories in this field.

When executed, this action displays as follows in the VM page:

In response, the file is executed and the status message is displayed along with the logs and details being updated.

OrganizationThe company or department details. In this example, cliqrtech
EnvironmentThe deployment environment where this action should be executed. In this example, default.
Run List

The combination of the cookbook name and recipe name using the cookbook::recipe formatin this example, jenkins::master

Puppet

Puppet Server

A Puppet server that is maintained by the user can be added to the CloudCenter repository list (see Share Artifact Repositories to configure a repository). A Puppet server configured in a CloudCenter platform as a shared repository is referred to as a Puppet repository. If multiple Puppet repositories exist, they are listed in the dropdown menu and you must pick one of the configured Puppet repositories in this field.

When you call the custom action in the VM page, you will not see any custom fields if none have been defined.

In response, the file is executed and the status message is displayed along with the logs and details being updated.

RoleA role that must exist in the Puppet repository configured above. For example wordpress.
EnvironmentThe deployment environment where this action should be executed. For example, production.
Ansible

Repository

An Ansible server that is maintained by the user can be added to the CloudCenter repository list (see Share Artifact Repositories to configure a repository). An Ansible server configured in a CloudCenter platform as a shared repository is referred to as an Ansible repository. If multiple Ansible repositories exist, they are listed in the dropdown menu and you must pick one of the configured Ansible repositories in this field.

When you call the custom action in the VM page, you will not see any custom fields if none have been defined.

In response, the file is executed and the status message is displayed along with the logs and details being updated.

PlaybookThe playbook path is  jenkins/install.yml.

Custom Fields

Add optional custom fields to the custom action to enrich the action by getting specific inputs from users.

This is an example of configuring a specific set of commands by using the Custom Fields option so the user can select one of the commands and launch the action on an external Docker container – the configuration displays on the left and the resulting popup on the right:

   

Provide the following information for each custom field that you add for a custom action.

Custom FieldDescription
Display NameRequired. Enter the name that you wish to assign for this custom field. If made visible, this label is displayed to end users when they invoking this action.
Param Name

The parameter name that is available to the script execution as environment variables. If these parameters are provided as $parameterName or as %paramName% in the script parameters, the CloudCenter platform replaces this field with the passed value in the script.

Help TextProvide additional tips that you wish to provide for the end user to complete in this field. Try using a single, short sentence so your end users are not overwhelmed with too much text.
Type
 Click here to expand...

The Type dropdown enables you to determine your own value for a custom field:

 by selecting one of the following options from the Type dropdown list.

TypeDescription
string

Provide an alpha-numeric value (limited to 255 characters).

API Enumeration = string (valueConstraint)

number

Provide a range of numbers (limited to 255 characters).

API Enumeration = number

list

Provide a list of comma separated text values (limited to 255 characters).

API Enumeration = list (valueList)

webservice

WebService is a parameter type introduced in CloudCenter 4.4.

You can provide list of dynamic webservice parameters while deploying a job. From this list, users can select one parameter. The webservice parameter type is available in custom parameters, global parameters, and services. The output should be in the following format:

[{"name":"p1","displayName":"Param 1"},{"name":"p2","displayName":"Param 2"}]

If you configure this parameter type, you must provide the Protocol (HTTP or HTTPS), Web Service URL, and the credentials (Username and Password) for this webservice.

To use this parameter type, you must set the Content-Type to be returned by webservice as application/html.

API Enumeration = webservice (webserviceListParams)

password with confirmation

Provide an alpha-numeric value (limited to 255 characters).

The UI provides a confirmation textbox.

API Enumeration = password_input (valueConstraint )

password

Enter text with no constraints – for example, use this field for a password that just needs to be entered without validation or confirmation.

The UI does not provide a confirmation textbox.

API Enumeration = password

path

A URL for the download location at the time of orchestration.

Options for pathDescription
Repository

Different repositories supported by CloudCenter.

See Shared Artifact Repositories > CloudCenter Repository Types for a list of options.

Format: %REPO_ID_{id}%xyz.war

Example: %REPO_ID_2%xyz.war where 2 is the ID of the repository in CloudCenter

File in Package

Path of the ZIP file defined in the application package of the application profile parent tier.

Example: %PACKAGE_DIR%script.sh

Storage

Path for the mounted storage location.

Linux VM Example: /shared

URLURLs of type HTTP, HTTPS, and FTP

API Enumeration = path (text that encodes a URL)

textarea

You can add any free form text in this area – for example, use this field for to define a parameter with values as file contents, or to define a private key, or to define a script, and so forth.

API Enumeration = textarea (text of any length (long))

Default ValueAssign the default value to be used by the custom field – should the end user not specify any values.
Required FieldIdentify if the end user must enter information in this field in order for the action to complete.

Failure Behavior

If any action fails when being called, the CloudCenter platform displays the failure in the History page (next to the event as highlighted in the following image). Additionally, if the failure reason is too long, you see a View Details link that provides the entire context of the error.