- 29 Apr 2024
-
DarkLight
-
PDF
Lifecycle Manager Resources
- Updated on 29 Apr 2024
-
DarkLight
-
PDF
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:
- Click the Create Resource + button. The Create Resource modal appears.
Figure 1: Create Resource Button
- Enter a name and, optionally, a description for the resource into the relevant fields.
- 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:
- Select the Resources header in the side navigation menu. An accordion menu that displays a list of existing resources will expand.
- Select a resource from the list. The resource will open in your active browser tab.
Figure 3: Select Resource
You can use the Search bar at the top of the accordion menu to filter the list of resources by name. Alternatively, you can search for resources using the Collections view of Lifecycle Manager by selecting the Search đ icon from the toolbar at the top of the side navigation menu.
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.
Tab | Function |
---|---|
Schema | Default tab. Defines the resource model in JSON Schema format. |
Instances | Creates new instances of a resource and executes actions against existing instances. |
Actions | Creates the actions used to manage instance properties. |
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.
Label | Element | Function |
---|---|---|
1 | Menu Button | Opens a menu to edit resource metadata, export the resource in JSON format, or delete the resource. Available from every tab. |
2 | Save Button | Saves any changes made to the resource model. |
3 | JSON Schema Editor | Defines the resource model. A toolbar is located at the top of the editor, allowing you to: - Search for text within the editor. - Copy the contents of the editor to your system clipboard. - Enable or disable dark mode for the editor. |
Figure 5: Schema Tab
Resource Model Syntax
When a resource is first created, a resource model template is populated in the JSON Schema Editor.
The value of the $id
keyword reflects the name that is provided when creating the resource.
Resource Model Template
{
"$id": "docs-demo",
"description": "Schema defining the possible values within instances of resource model 'demo'",
"type": "object",
"required": [],
"additionalProperties": true,
"properties": {}
}
Keyword | Description |
---|---|
$id |
The name of the resource model. |
description |
A description of the resource model. |
type |
The data type of the resource model; this will always be object . |
required |
The properties required to be included in the resource model. |
additionalProperties |
Designates whether or not the resource model allows properties not defined in the properties keyword. |
properties |
Defines the manageable properties that instances of this resource will have. |
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:
-
Add the
hostname
,ipv4
, andvendor
properties to the resource model as keys of theproperties
keyword."properties": { "hostname": { "type": "string" }, "ipv4": { "type": "string", "format": "ipv4" }, "vendor": { "type": "string" } }
-
Because they should be mandatory, also add the
hostname
andipv4
properties to the resource model as array values of therequired
keyword."required": [ "hostname", "ipv4" ],
-
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.
Label | Element | Function |
---|---|---|
1 | Menu Button | Opens a menu to edit resource metadata, export the resource in JSON format, or delete the resource. Available from every tab. |
2 | Toolbar | Actions (from left to right) to create, import, and export an instance. |
3 | Filter Bar | Filters an instance by name. |
4 | Instance Table | View all instances of the current resource. Select an instance to view additional information on the Instance Side Panel. |
5 | Instance Side Panel | Select a tab to run Actions against the selected instance, view the Properties of the instance, or view the History of the instance. Additional functions are available within each respective tab. |
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:
- Click the + New Instance button. The New Instance window opens.
Figure 7: New Instance Button
- 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.
- 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).
- Enter initial property values into the relevant fields. Note that the
hostname
andipv4
properties are required, and thevendor
property is optional. Properties are required or optional according to how they are defined in the resource model. - 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.
- 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 sidebar, 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 9.
Label | Element | Function |
---|---|---|
1 | Menu Button | Opens a menu to edit resource metadata, export the resource in JSON format, or delete the resource. Available from every tab. |
2 | Toolbar | From left to right these are used to: create a new action (+), select all actions (â), and delete selected actions. |
3 | Filter Bar | Filter displayed actions by name. |
4 | Action Cards | Displays actions in card format, separated by action type. From an action card, you can: - Select the action by clicking the selection box. - Edit the action by clicking the edit button. - Delete the action by clicking the delete button. |
Figure 17: Actions Tab UI
Types of Action
Three types of action can be executed in Lifecycle Manager: create, update, and delete.
Action Type | Description |
---|---|
Create | Creates a new instance. It is not required to define workflow logic for a create action; any workflow logic you define should be dictated by the needs of your environment. For example, you may wish to attach a workflow that dynamically assigns initial property values. |
Update | Updates the properties of an instance. Advanced logic is provided by attaching a relevant workflow. For example, if you would like the action to open a firewall port, you need to attach a workflow that does so. More information on how to accomplish this is provided in the How Actions Work section of this guide. |
Delete | Deletes an instance. It is not required to define workflow logic for a delete action; any workflow logic you define should be dictated by the needs of your environment. For example, you may wish to attach a workflow that deletes a virtual machine associated with the instance. |
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:
- 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
. - Workflow tasks receive these properties by using
instance
as an incoming job variable. After the properties are manipulated, they are returned by usinginstance
as an outgoing job variable. - 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.
Instance properties can also be manipulated before they enter the workflow or after they exit the workflow by using pre and post-JSTs. This can be useful if you need to adapt existing workflows to be used with Lifecycle Manager actions. For more information about JSTs, refer to the JST Designer documentation.
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:
- Click the + New Action button. The New Action window opens.
Figure 18: New Action
- Enter a name for the action into the relevant field.
- Select Update from the Action Type dropdown menu.
- Click the Save ï button to save your changes before proceeding.
Figure 19: New Action in Progress
- Click the + Workflow button. A menu will display that allows you to select an existing workflow or create a new workflow.
- Click the + Create New button. Automation Studio will open in a new tab.
Figure 20: Create New Workflow
- 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.- The example provided below uses a
stub
task to simulate receiving a new IPv4 address from an external source, such as an Ansible playbook. - The
setObjectKey
task then uses this new address to update theipv4
key of theinstance
job variable. - When you are done, save the workflow by clicking the Save button and return to the New Action window on the Lifecycle Manager tab.
- The example provided below uses a
Figure 21: LCM Workflow Example
- 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
- Navigate to the Instances tab by clicking the tab name at the top of the Resource view.
- 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.
- 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
- 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:
- Click the Menu Button at the top-right corner of the Resource view; this button is available from every tab. A menu displays.
- Select Metadata from the menu. The metadata slider panel appears from the top of the window.
- Enter any desired metadata changes into the appropriate text input field.
- Click the Save button.
Figure 25: Metadata Panel