Lifecycle Manager Resources

Resources

In Lifecycle Manager, entities are represented as resources. A resource can model any type of entity that Itential Automation Platform (IAP) can manage, such as a networking device, cloud computing instance, code repository, etc.

Resources are managed from the Resources view of Lifecycle Manager, from which you can:

• Define the model of a resource.
• Create instances of a resource.
• Create and execute resource actions.
• Edit resource metadata.

This page documents the features of the Resource view and provides guidance on how to perform common tasks within it.

Prerequisite Readings

Before using Resources in Lifecycle Manager, you should have a complete understanding of the concepts that are accessible from these pages:

• Foundational concepts of entities represented as resources are introduced in Lifecycle Manager Overview. It is recommended to read that page before proceeding.
• Resource models are JSON Schemas. As such, familiarity with basic JSON Schema concepts is recommended before proceeding.
• Actions are the interface that Lifecycle Manager uses to interact with workflows. Therefore, prior knowledge of workflows is recommended.

Creating a Resource

To create a resource from the Lifecycle Manager home page:

1. Click the Create Resource + button. The Create Resource modal appears.

   Figure 1: Create Resource Button
   

2. Enter a name and, optionally, a description for the resource into the relevant fields.

3. Click the Create button. The new resource will open in your active browser tab.

Figure 2: Create Resource Modal

Opening an Existing Resource

To open an existing resource from the Lifecycle Manager home page:

1. Select the Resources header in the side navigation menu. An accordion menu that displays a list of existing resources will expand.
2. Select a resource from the list. The resource will open in your active browser tab.

Figure 3: Select Resource

Resource View Tabs

After creating a new resource or selecting an existing resource from the side navigation menu, you are redirected to the Resource view. The user interface (UI) of the Resource view is divided by function into the following tabs as presented in the table below.

Regardless of which tab is currently open, all available tabs are displayed at the top of the Resource view. Click the names of the tabs to navigate between them.

Figure 4: Resource View Tabs (Model Tab Selected)

Defining Resource Models

When creating a new resource, you must first define its resource model. A resource model is a JSON Schema that defines the manageable properties of a resource. Any instances of a created resource will have these properties, and the actions that run against an instance will be able to interact with these properties.

Model Tab

Resource models are defined on the Model tab. The UI of the Model tab is comprised of the following elements (labeled in Figure 5).

Figure 5: Model Tab

Resource Model Syntax

When a resource is first created, a resource model template is populated in the JSON Schema Editor.

Resource Model Template

{
    "$id": "org-switch",
    "description": "Schema defining the possible values within instances of resource model 'org-switch'",
    "type": "object",
    "required": [],
    "additionalProperties": true,
    "properties": {}
}

Properties the resource should have available for management are added to the resource model as keys of the properties keyword. Any properties that should be required are also added to the resource model as array values of the required keyword. An example is provided in the next section.

Example - Defining a Resource Model for a Switch

You are working for an organization that wants to manage all of its network switches using Lifecycle Manager. To this end, you have created a resource named org-switch. You must now define its resource model.

You have decided that each instance of org-switch should have the following manageable properties:

• hostname, a required string representing the hostname of the switch.
• ipv4, a required string in IPv4 address format representing the IPv4 address of the switch.
• vendor, an optional string representing the vendor of the switch.

To accomplish this:

1. Add the hostname, ipv4, and vendor properties to the resource model as keys of the properties keyword.

   "properties": {
       "hostname": {
           "type": "string"
       },
       "ipv4": {
           "type": "string",
           "format": "ipv4"
       },
       "vendor": {
           "type": "string"
       }
   }
   
   

2. Because they should be mandatory, also add the hostname and ipv4 properties to the resource model as array values of the required keyword.

   "required": [
       "hostname",
       "ipv4"
   ],
   

3. After these steps are taken, the resource model of org-switch is defined as follows.

   {
       "$id": "org-switch",
       "description": "Schema defining the possible values within instances of resource model 'org-switch'",
       "type": "object",
       "required": [
           "hostname",
           "ipv4"
       ],
       "additionalProperties": true,
       "properties": {
           "hostname": {
               "type": "string"
           },
           "ipv4": {
               "type": "string",
               "format": "ipv4"
           },
           "vendor": {
               "type": "string"
           }
       }
   }
   

Creating New Instances

After a resource model is defined, you can begin creating instances of a resource. An instance is a discrete occurrence of a resource. For example, if your resource model describes a service desk ticket, each instance of the resource would represent an individual ticket.

Instances Tab

Instances are managed on the Instances tab. The UI of the Instances tab is comprised of the following elements (labeled in Figure 6).

Figure 6: Instances Tab

An example detailing how to create instances is provided in the following section.

Example - Creating a New Switch Instance

After defining a resource model in the previous example, you are now ready to begin creating instances of the org-switch resource. To do this:

1. Click the + New Instance button. The New Instance window opens.

Figure 7: New Instance Button

2. Optionally, enter a name and description for the instance into the relevant fields. If you do not provide a name, one will be automatically generated when the instance is created.
3. Select an action to create the instance. Create actions are discussed in the Types of Action section of this guide. For now, use the default selection (Create).
4. Enter initial property values into the relevant fields. Note that the hostname and ipv4 properties are required, and the vendor property is optional. Properties are required or optional according to how they are defined in the resource model.
5. Click the Save  button. The new instance is created and listed in the Instances Table.

Figure 8: New Instance Window

Importing Instances

Instances can be imported into any model as long as:

• The instance data of the imported instances conforms to the schema of the Resource Model.
• The names of the imported instances are unique to the Resource Model (not counting deleted instances).

To import instances into a model, navigate to the model’s Instances tab, then click the Import icon button to the right of the + New Instance button.

Figure 9: Import

The Import Instances dialog will appear. Users can browse and select one or multiple exported instance JSON files to import. After selecting the file, click the Import button at the bottom-left corner of the dialog.

Figure 10: Import Instances

Each instance will be validated individually and a notification toast will alert the user to the result of the import operation (Figure 11).

Figure 11: Validation

Upon successful import, the Last Action field for each instance in the Instances Table, as well as the History sub-tab for each instance, will show an “Import” action (Figure 12).

Figure 12: Last Action

Exporting Instances

Instances can be exported from one Resource Model to be imported into the same or other Resource Models. When instances are exported, the instance _id, modelId, and actionHistory fields are excluded from the exported file.

Export Multiple Instances

Multiple instances can be exported from the Instances tab of a resource model.

To export multiple instances, select at least one row from the Instances Table, then click the Export icon button in the toolbar above the table.

When exporting multiple instances, a single JSON file containing all instances will be downloaded. The filename will be based on the name of the Resource Model and suffixed with _exportedInstances.json.

Figure 13: Exporting an Instance

Export Single Instance

Individual instances can be exported in a number of ways. When exporting individual instances, the filename will be based on the instance name.

Locate the instance in the Instances Table, and hover on the vertical dot icon button on the right side to find the Export option.

Figure 14: Export from Instances Table (Option 1)

From the instance properties side panel, the Export icon button is located to the right of the “Edit ✏” button.

Figure 15: Export from Properties (Option 2)

From the Edit Instance Details page, the Export icon button is located at the top of the page to the right of the Save  and Revert Changes buttons.

Figure 16: Export from Edit Instance Details (Option 3)

Creating and Using Actions

To manage the properties of an instance, you must create and use actions. For example, an instance representing a virtual machine may have a property that represents its power state. To manage this property, you could create an action that shuts off or turns on the virtual machine and updates the property accordingly.

Actions Tab

Actions are created on the Actions tab. The UI of the Actions tab is comprised of the following elements (labeled in Figure 17).

Figure 17: Actions Tab UI

Types of Action

Three types of action can be executed in Lifecycle Manager: create, update, and delete.

How Actions Work

Actions rely on workflows to effect changes on the entity they are managing. The exact process used to do this varies, with nuances existing between each action type.

When an update or delete action with an attached workflow is executed against an instance, the following generalized steps occur:

1. Lifecycle Manager makes the defined properties of the current instance available to the workflow. To do this, it sends the properties to the workflow in a job variable named instance.
2. Workflow tasks receive these properties by using instance as an incoming job variable. After the properties are manipulated, they are returned by using instance as an outgoing job variable.
3. At the end of workflow execution, any changes made to instance are returned to Lifecycle Manager and applied to the current instance.

Create actions work similarly, with one major caveat: they do not receive instance as an incoming job variable, as at the start of execution, the related instance does not yet exist. If a workflow is attached to a create action, it must create and output the instance job variable itself in compliance with the defined resource model.

An example of how to create an action that uses workflow logic is provided in the next section.

Example - Changing Switch IPv4 Address with an Update Action

After creating an instance of org-switch in the previous example, you are now ready to create actions to manage your new instance. You have decided to create an action that changes the IPv4 address of the instance. To do this:

1. Click the + New Action button. The New Action window opens.

   Figure 18: New Action
   

2. Enter a name for the action into the relevant field.

3. Select Update from the Action Type dropdown menu.

4. Click the Save  button to save your changes before proceeding.

   Figure 19: New Action in Progress
   

5. Click the + Workflow button. A menu will display that allows you to select an existing workflow or create a new workflow.

6. Click the + Create New button. Automation Studio will open in a new tab.

   Figure 20: Create New Workflow
   

7. Design a workflow that changes the IPv4 address of the switch and, in turn, updates the instance job variable. Ensure that workflow tasks are configured in accordance with the steps provided in How Actions Work.

   1. The example provided below uses a stub task to simulate receiving a new IPv4 address from an external source, such as an Ansible playbook.
   2. This address (encapsulated in a task variable) and the instance job variable are provided as inputs to the setObjectKey task. setObjectKey uses this new address to update the ipv4 key of instance. The results of the task are then output back to the instance job variable.
   3. When you are done, save the workflow by clicking the Save  button and return to the New Action window on the Lifecycle Manager tab.

   Figure 21: Example LCM Workflow
   

8. Click the Save  button to retain your changes to the action. The new action displays on the Actions tab as a card.

   Figure 22: New Action Card
   

9. Navigate to the Instances tab by clicking the tab name at the top of the Resource view.

10. Select the instance you would like to update from the Instances Table. The Instance Side Panel will open for that instance, displaying several sub-tabs. Be sure you are on the Actions sub-tab.

11. Click the Run ► button of the new action (e.g., change_ipv4). A success toast will display and the action will be set to Running status.

    Figure 23: Run Action
    

12. When the action is complete, it will transition to a Completed status. Any changes made to resource properties by the action will be reflected on the Properties sub-tab.

Figure 24: Resource Properties

Running Actions Against Instance Groups

You may encounter situations in which an action must be executed against a number of instances simultaneously. Though you can perform such bulk executions ad hoc by selecting multiple instances at once, it is often easier to create and target instance groups, especially if you expect these situations to reoccur. For example, if you regularly have to execute an action against all instances that are part of a certain testing environment, it may be prudent to create an instance group for that environment. This way, you do not have to search the instance table manually for each relevant instance every time the action must be executed.

Instance Groups Tab

Instance groups are created on the Instance Groups tab. The UI of the Instance Groups tab is comprised of the following elements (labeled in Figure 25).

Figure 25: Instance Groups Tab

Types of Instance Group

Instance groups can be organized in one of two ways: manually or dynamically.

Example - Creating and Executing Against an Instance Group

You have created several more switch instances since your first, and managing them individually has become unwieldy. Because switches in your environment tend to receive actions based on geographic location, you have decided to group them accordingly. To do this:

1. Click the + New Instance Group button. The New Instance Group window will open.

   Figure 26: New Instance Group
   

2. Enter the group name and, optionally, a description of the group into the relevant fields.

3. Designate whether the group should be manual or dynamic via the Dynamic Group checkbox. If this box is left unchecked, the group will be manual. In this example, your organization's naming scheme requires that each instance is prefixed by a region code: "ec" for East Coast and "wc" for West Coast. This provides strong filtering criteria; as such, click the checkbox to make this a dynamic group. The Group Filter controls appear.

4. Enter "ec" into the Name filter. Only instances with a name beginning in "ec" will match this filter.

5. Click Apply Filter.

6. Click Save  to confirm your changes to the group and return to the Instance Groups tab. The new group will be displayed on the instance groups table.

Figure 27: Create Instance Group

To run an action against your new group:

1. Navigate to the Actions sub-tab on the instance group side panel. A list of available actions will display.

2. Click the Run ► button of the relevant action. The Run Group Action modal will appear.

   Figure 28: Available Actions
   

3. Define any required input properties. If applicable, these will be automatically populated in the JSON editor. Otherwise, continue to the next step.

4. Click the Run ► button at the bottom-left of the modal.

Figure 29: Run Group Action

Editing Resource Metadata

Resources have several editable metadata values, including name and description. To edit resource metadata:

1. Click the Menu Button at the top-right corner of the Resource view; this button is available from every tab. A menu displays.
2. Select Metadata from the menu. The metadata slider panel appears from the top of the window.
3. Enter any desired metadata changes into the appropriate text input field.
4. Click the Save button.

Figure 30: Metadata Panel