Intersight Cloud Orchestrator - Breakdown of ICO Tasks

Last updated
Save as PDF

Breakdown of ICO Tasks

This article will get into the details of tasks within Intersight Cloud Orchestrator to give some details about their capabilities and usage.

Basics of Tasks

Tasks are the core component of all orchestration within Intersight. A single task is the most basic level of automation that can be used within a workflow; it uses any inputs provided by the user, performs a specific operation, and then produces output that may be used by another task within the workflow (or not).

Intersight provides a significant catalog of tasks within the platform itself (306 as of Oct 23), and these include tasks with these main categories:

Storage
Virtualization
Networking
Compute
Executors (external automation)

These system-defined tasks are built and provided by either Cisco or partners that have integrated their platforms with Intersight, such as Pure Storage has done. If there is not a system-defined task that will perform a function needed by an end-user, tasks can also be created through the Task Designer or from an OpenAPI 3.x Spec file.

NOTE: It is important to understand that manually created tasks can ONLY leverage Executors covered later in this document, and manually created tasks are the only type of tasks that can be exported from Intersight (meaning built-in system tasks cannot be exported).

Tasks (Input & Output)

Tasks all require some level of input/output to make them useful by themselves or within a workflow, and it is more easily explained with examples of how tasks use these values.

Simple Task

To understand a task and some of its input/output, let us look at using a simple built-in storage task - 'Add Host to Storage Host Group' - which should be self-explanatory.

First, we have three required inputs as shown below.

'Add Host to Storage Host Group' Inputs within the UI:

To explain these inputs in a little better detail, we'll give a short explanation of each:

Storage Device - This will be a selection of the storage array we are running the task against. NOTE: This must be a device already claimed into Intersight via the Intersight Assist virtual appliance.

Host Group - This input is a selection for the existing host group on the array, and the host groups will be listed once a user selects a storage array. The host group will be selected by clicking the radio button for a particular array within the list of existing host groups. (An example is shown below these input descriptions)

Host Name - This input is a string for the name of the host to be added to the host group.

Host Group Selection within the UI:

Complex Task

To understand a complex task and where we may need to do some mapping in the Workflow Designer for vendor-specific options, let us look at using a simple built-in storage task - creating a 'New Storage Volume'.

First, we have five required inputs as shown below.

'New Storage Volume' Inputs within the UI:

Similar to our explanation of the task above, we'll give a short explanation of each:

Storage Device - This will be a selection of the storage array we will run the task against. NOTE: This must be a device already claimed into Intersight via the Intersight Assist virtual appliance.

Storage Vendor Virtual Machine - This is used for storage arrays that use a storage virtual machine (SVM). NOTE: As this is not used for Pure Storage, this input can be hidden when working with a Pure array for this task.

Storage Vendor Aggregate - This input is more of a backend data field, as it will handle mapping some vendor platform details specific to the type of storage platform the task is being run against.

Storage Vendor Volume Options - This input will modify the subsequent selection of the options to be displayed for the volume capacity, which are specific to the type of storage platform the task is being run against.

Volume Capacity - Finally, we see our input for volume capacity, requiring volume size & unit. For a Pure Array, this will ask for an integer value for the unit, and give us the appropriate unit values, as seen below.

'Volume Capacity' Inputs within the UI:

Executors

Now that we have covered the basics of the system (built-in) tasks within Intersight, we can cover tasks that utilize executors. Executors are tasks for launching automation, which can be run externally to Intersight.

There are four executors within Intersight which can be leveraged for external automation, which are the following:

Invoke Ansible Playbook
Invoke PowerShell Script
Invoke SSH Commands
Invoke Web API Request

Infrastructure as Code Executors

For running the SSH commands, Ansible playbook, or PowerShell scripts, each of these options will be run on an external endpoint, which is a target (think of this as a jump box in an environment) that is previously claimed within Intersight for each specific executor use.

While a single host can perform the functions of one or more executors, you must configure an endpoint target with the appropriate details for each function. These connection details include options such as name, management address (IP address), port, and credentials (username/password, or username/SSH key).

API Executor

For running an API request from Intersight, this action can be taken against an API (either HTTP or HTTPS) on a natively supported endpoint that Intersight will invoke a request against or an HTTP endpoint specifically added to Intersight as a specific target.

The natively supported API endpoints for Intersight to invoke a request against include options for Cisco UCS Director, Pure Storage FlashArray, VMware vCenter Server, Terraform Cloud, and Cisco Application Policy Infrastructure Controller (APIC). NOTE: Being a natively supported API endpoint within Intersight means they are tested and verified for functionality with Intersight.

If a user needs to run API requests against another API, whether publicly accessible or on the customer premises, you must configure an endpoint target with the appropriate details for the HTTP(S) endpoint. These connection details include options such as if Intersight Assist is used for the connection (for an API on customer premises) name, hostname/IP address, port, any authentication required (username/password, or bearer token), and whether the connection to the target should be established using HTTPS.

Creating a Custom Task

When the built-in system tasks do not perform a specific action that you need to complete, you are able to build a custom task that will utilize one of the four Executors to perform a custom action. To create a custom task, you must define some basic details, define task inputs and outputs to be passed to the Executors, and define some overall task-level inputs & outputs that can be used.

When creating a custom task, the general properties that can be set are the following:

Organization - Name of the Intersight organization that the task will be created in

Task Name - User-friendly name of the task

Description - A description of the task

Retry Count - The number of times to try a task before being marked as failed

Retry Delay - The delay (in seconds) before trying a task again

Timeout - The timeout value (in seconds) that a task is considered as timed out

Set Tags - Set a tag for the task within Intersight (key:value pair)

Enable Rollback Task - Enable to rollback a task and choose an appropriate task from the drop-down list (requires workflow inputs and mappings)

Executor Inputs

For each Executor to be used within a task, these are the available inputs per Executor type:

Ansible Playbook - Playbook Path, Host Inventory, Command Timeout, Command Line Arguments

PowerShell Script - Script, Timeout, and Response Parser

SSH Command - SSH Command, Command Timeout, Expected Exit Codes, and Response Parser

API Request - Method, URL, Headers, Cookies, Response Type, Body, and Response Parser

Executor Outputs

For each Executor to be used within a task, these are the available outputs per Executor type:

Ansible Playbook - Exit Code, Execution Summary, Execution Log Path, and Outcomes (custom execution status and status message)

PowerShell Script - Exit Code, Execution Summary, Execution Log Path, and Outcomes (custom execution status and status message)

SSH Command - Exit Code, Command Output, Command Execution Error, Extracted Parameters, and Outcomes (custom execution status and status message)

API Request - Headers, Cookies, Status Code, Status Message, Parameters, and Outcomes (custom execution status and status message)

Executor Outcomes

When any Executor is used within a workflow, we also have the ability to define an “Outcome”. An outcome is the combination of a condition and task status. It is possible to use extracted values from the API response to determine the task status, then set the status with an appropriate message, when the conditions match.

One or more outcomes can be specified, and the outcomes are then evaluated in the specified order. When the first outcome condition that matches is evaluated, that outcome sets the task status and message. If none of the outcome conditions match, the task shall be marked as successful.

The possible outcomes of a task are as follows:

Success—Marks the API execution as Success if the condition matches
Skip to Success—Stops further API executions of the task and marks the task as successful when the condition matches
Status—Retains a task as work in progress, only updating the status
Error—Marks the API execution as Failed if the condition matches. Task retry will be attempted if the task has any retries left
Terminal error—Marks the API execution as Failed if the condition matches. This marks a non-recoverable error and no retries are attempted (NOTE: If the task status is Terminal Error, there are no retries for that task.)
Skip Task Execution—Skips execution of task if the condition matches in the API. This will skip execution of all the subsequent APIs in the task

Task Level Input

Within a custom task, there are many values that can be set for the input at the task level:

Display Name - User-friendly name of the task used in the task list

Reference Name - Used for referring to this task input for reuse

Description - Detailed description of the input

Value Restrictions - Sets the input as Required or Collection/Multiple values

Type - The data type for a primitive data type. For example, this could be string, integers, enumerations, JSON, specific target devices, and more complex data types.

Depending on the data type, additional options can be set for this task input, including Enum Lists, minimum and maximum range, Regex match for string values, Object Selector (radio button), Intersight API Reference, selector attribute (for filtering), and if the value is secure (values of these properties are encrypted and stored in Cisco Intersight).