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 opens 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 (Schema 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.

Schema Tab

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

Figure 5: Schema 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": "docs-demo",
    "description": "Schema defining the possible values within instances of resource model 'demo'",
    "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 as labeled in Figure 6. An example detailing how to create instances is provided in the next section.

Figure 6: Instances Tab

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 Files

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 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.

1. 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)

2. From the instance Properties sidebar, the “Export” icon button is located to the right of the “Edit” button.

Figure 15: Export from Properties (Option 2)

3. 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 9.

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. When an 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.

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 Step 2 of 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. The setObjectKey task then uses this new address to update the ipv4 key of 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: LCM Workflow Example

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

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 25: Metadata Panel