vRealize Operations® Management Pack Builder™ is a stand-alone appliance that enables the creation of custom management packs for use in vRealize Operations. This is a no-code solution for bringing in data from an external API and either creating new resources or extending your VMware and third party resources with new Data, Relationships, and Events.
From version 1.1 onward, this product is known as VMware Aria Operations Management Pack Builder. If you're seeking a user guide for a version 1.1 or later, please visit VMware Aria Operations Management Pack Builder documentation.
For help with Management Pack Builder, contact the Community Page.
Installing VMware vRealize Operations Management Pack Builder
vRealize Operations Management Pack Builder consists of a single appliance. To create the appliance, you use the vSphere client to download and deploy the vRealize Operations Management Pack Builder virtual machine.
Prerequisites
Verify that you have permissions to deploy OVF template to the inventory.
Reserve a static IP address for the virtual machine, and know the associated domain name, domain search path, domain name servers, default gateway, and network mask values.
Plan to keep the IP address because it is difficult to change the address after installation.
Plan your domain and machine naming so that the deployed virtual machine name begins and ends with an alphabet (a–z) or digit (0–9) characters, and will only contain alphabet, digit, or hyphen (-) characters. The underscore character (_) must not appear in the host name or anywhere in the fully qualified domain name (FQDN).
Plan to keep the name because it is difficult to change the name after installation.
For more information, review the host name specifications from the Internet Engineering Task Force. See www.ietf.org.
Download the vRealize Operations Management Pack Builder .ova file to a location that is accessible to the vSphere client.
If you download the virtual machine and the file extension is .tar, change the file extension to .ova.
Verify that you are connected to a vCenter Server system with a vSphere client, and log in to the vSphere client.
At this time, Management Pack Builder does not support VMware Aria Operations SaaS
Procedure
Select the vSphere Deploy OVF Template option.
Enter the path to the vRealize Operations .ova file.
Follow the prompts until you are asked to enter a name for the node.
Enter a node name. Examples might include Ops1, Ops2 Ops-A, Ops-B. (Do not include nonstandard characters such as underscores (_) in node names.)
Follow the prompts until you are asked to select the disk format:
Thick Provision Lazy Zeroed Creates a virtual disk in a default thick format.
Thick Provision Eager Zeroed Creates a type of thick virtual disk that supports clustering features such as Fault Tolerance. This format can improve performance depending on the underlying storage subsystem. Select the thick provisioned eager-zero option when possible.
Thin Provision Creates a disk in thin format. Use this format to save storage space.
Click Next.
From the drop-down menu, select a Destination Network, for example, Network 1 = TEST, and click Next.
Under Networking Properties, in case of a static IP, specify the associated Default Gateway, Domain Name, Domain Search Path, Domain Name Servers, Network 1 IP Address, and Network 1 Netmask values.
Under the Application section • initial root password o password o confirm password
Click Next.
Review the settings and click Finish.
What to do Next
Once installation is complete, point a web browser to the product's interface at the following URL: https://FDQN-or-IP-Address
Your initial log in will be with the user admin and password admin. You will be required to change the password on your first connection. Password requirements are more than 8 characters and must include a number and a special character: !@#$%^&*
Before you Start A Design
What you will need
Before starting you should make sure you have access to the following things.
Reference environment: You will need to have access to a reference environment including hostname, user information, and firewall rules for access from your Management Pack Builder virtual machine.
API Documentation: You will need access to some from of documentation for the API
VMware Aria Operations connection(optional)
Planning your design
Before starting your new design, it is important to think about what you want to include in it. The main items to understand are objects, requests, and relationships.
Object: Objects are the core item that we will be adding or updating in vRealize Operations. You should think of them as the nouns of your technology. An example would be a network switch. Your nouns for a switch could be the switch, ports, CPUs, and fans. These would all become objects in your design. If that is too granular and all you wanted to monitor is the switch itself, then that would be your object. For every object you will provide the metrics and properties by adding one or more requests. vRealize Operations manages metrics by the objects and has limits based on number of objects and metrics. Please review the sizing guide for the appropriate version of vRealize Operations when designing your objects.
You can also extend existing objects in your vRealize Operations environment such as VM’s, Host Systems, or third-party resources. By extending those objects you add metrics or properties to the existing object allowing custom information to be used as if it was part of the original resource.
Restriction:VMware Aria Operations manages metrics by objects and imposes limits based on the number of objects.
Requests: These are the API requests used to add metrics and properties. To understand what is available on these requests reference the API documentation. In our switch example, the requests would be to the interface endpoint that lists all the ports and the stats endpoint that show the performance of the port.
Relationships: Relating objects to each other in a parent to child relationship. This creates a topology for your objects allowing vRealize Operations to understand the connectivity between your objects. In our switch example, the switch would be the parent to the ports, CPU’s, and fans. You can also add relationship to vRealize Operations objects like hosts, vm’s, or third-party resources like data arrays.
Creating A Design
When creating a design, you will see the six sections to the left of the screen. Each section is based off the section above it apart from configuration so you should start at the top and work your way down the sections.
Setting up the Source
The source is used to pull data from the API to be used in configuring and testing the design. This should be a representative environment that is close to a production setup so that any design created off this will have useful information.
Standard Settings
This section is where we identify the necessary settings to connect and test the connection. These settings are only for the Management Pack Builder design process and not hardcoded into the pack.
Hostname: This is the host or your reference environment. It can be a single IP, a hostname, or a FDQN.
Port: The port used to communicate with the API.
SSL Configuration: Setting to determine if the connection does not use SSL, Uses SSL but does not verify the certification, or Uses SSL and verifies the certification.
Base API Path: This is prepended to every call that you make using this source and is designed to reduce the duplication of data in the Request section. This is optional and can be left blank. For example if every API call starts with 'api/v2' you set that here and do not have to include that in every Request resource path.
Authentication
The Management Pack Builder can use two different authentication source types: basic, and custom. What is setup here is used for every call, so you only need to set up authentication once.
Basic authentication
• Username: User setup on reference system that is authorized to query the intended API endpoint.
• Password: User’s password for authentication
Sessions
Session authentication is a method in which a session is created on login and stores information about the user including unique session ID, time of login and expirations, and more. It is created by the server and if you remain logged in, the session ID can be sent to the server upon subsequent requests to work as authentication.
Session authentication in Management Pack Builder is a wizard driven configuration of the session call. You will be walked through the wizard and asked for information regarding the API session creation.
Credentials: Session creation can either use basic authentication to the authentication endpoint or a custom setup. In the custom section you add any API specific parameters to be used in later in the configuration.
Session Configuration
Resource Path: This is the path to the session creation resource as defined by the API documentation.
Advanced settings: These settings are optional and only necessary it specifically required by the API of the target system.
Body: This allows you to create a body to be sent to the session creation resource. Some APIs require the body to contain information like user and password to be passed in the body. This is optional and only needs to be used if the API documentation indicates it.
Headers: This is used to pass data to the session creation resource in the request header. This only needs to be used if the API requires custom values in the header. If using basic credentials, the Authorization header is automatically added and thus does not need further configuration.
Query parameters: This section allows the user to add custom query prompts to the end of the URL request. This is optional and only necessary if the API documentation calls for it.
Get Data
Http Method: Based on the API requirements this will be either a Post, Get, Put
Preview: This shows the exact URL that will be used for the authentication request.
Variables: This gives you access to all the header and body responses to allow you to capture them into variables to be used in the Source setting. Specific responses you will likely use are either Tokens, Sessions IDs, or Set-Cookies responses. For specific details reference the API documentation.
Summary: This summarizes your settings used in the steps outlined above.
If the API defines a delete session resource the wizard for that can be run to create the release session request. This logs the session out, reduces session leaks, and improves security.
Release Session Configuration
Resource Path: This is the path to the session release resource as defined by the API documentation.
Advanced settings: These settings are optional and only necessary it specifically required by the API of the target system.
Body: This allows you to create a body to be sent to the session release resource. Some APIs require the body to contain information like session id. This is optional and only needs to be used if the API documentation indicates it.
Headers: This is used to pass data to the session release resource in the request header. This only needs to be used if the API requires custom values in the header.
Query parameters: This section allows the user to add custom query prompts to the end of the URL request. This is optional and only necessary if the API documentation calls for it.
Test Authentication
Http Method: Based on the API requirements this will be either a Post, Get, or Delete.
Custom
Custom authentication allows the user to add customer variables to be used in the advanced section of the source creation. This is generally used with permanent session tokens, or any variables sent with every request.
Global Request Settings (Optional)
Headers
This is used to pass data with every call in the request header. Session data should be put here so that every call includes the session id or token information and you do not have to define this for every unique request.
Advanced request settings
Body: If the test connection endpoint you choose requires a data in the body you can add that here. This will only be sent to the test connection endpoint.
Query Parameters: This section allows the user to add custom query prompts to the end of every request. This is optional and only necessary if the API documentation calls for it.
Test Connection
The test connection confirms that all the source data is setup correctly. If using basic authentication this will send one request including the basic authentication header. If using the session this will make up to three requests to create the session, make a call to the test endpoint, then the call to delete the session.
HTTP Method: This is the method for the request to the test endpoint. It will be either a Get, Put, Patch, or Post.
Connection Test Path: This is the path to an API endpoint that is used in the test connection in vRealize Operations.
URL preview: This will show the complied URL based off the settings done above and shows the final call that will be made.
Response
The response section will show the release response to the test connection endpoint. You can see the body and headers of the response as well as the logs generated by the request.
Requests
This section is where you can add all the API calls used by the design to provide data to the objects and alerts. You will need to reference your API documentation to determine the endpoint and setting necessary for this section. Each request can be named to indicate which data request you are configuring. This is done by clicking on the pencil icon at the top of the request card.
Resource Path
Define the endpoint to be used for the request.
The reference environment, source hostname, port, and base api path will be prepended to this path for the request URL.
Advanced (optional)
In this section you can add specific data to the requests body, headers, and query parameters. Your API documentation will determine if you can or should put anything in these sections.
This section also holds the ability to add Paging to your API call, you must make the request prior to configuring paging. MP Builder supports two main methods of pagination, offset and pages. Reference your API documentation for if paging is necessary and if so which method to use.
Paging Parameter: This is the parameter name to use to indicate which page we are requesting.
Limit Parameter: This is the parameter name for the number or records per page.
Limit Value: The number of records returned per page.
Get Data
After defining the request, you will have to test the call which is done in this section. The request button will perform the call to your source endpoint and retrieve the data. This is necessary when defining the objects and alerts.
HTTP Method: This is the method used for the request. It will be either a Get, Put, Patch, or Post.
Preview: This is the preview of the full path for this request.
Response
The response section will show the release response to the test connection endpoint. You can see the body and headers of the response as well as the logs generated by the request.
Chain from other API calls
In some API’s you have to chain calls together to get the data you are looking for. This will usually be done by adding an object id from the initial call to the resource path of the second call. For example, we make one call to the interface endpoint of a switch that returns all the ports associated with the switch then use the port id from that call to request the performance statistics for each port individually.
For the chained call you select the initial call you would like to pull the information for the secondary call. You can only select on data point from the initial call. The sample value will show you the value of the first entry in the initial request’s response. To use that variable, you add ${param}to resource path section of the request.
Objects
This section is where you define the objects that will be part of your custom management pack. These objects can be new objects or can use vRealize Operations objects to add new metrics or properties.
Add New Object
Each object should be named to indicate you are configuring. This is the resource type of the object in vRealize Operations and can be done by clicking on the pencil icon at the top of the request card. In this card you will select the metrics and properties for be added to the object, select what will be used at the object identifier, select the data for the name, and choose the icon that will be used in vRealize Operations.
Metrics and Properties from the API calls
From the list of Request calls you select one or more requests to pull into this object. You will then select all the data entries you want to add to your object from the list. You can search the list of metrics for a specific metric or scroll through the list.
Once selected the metrics will display in the review section. Here you will see the following information about the data.
vRealize Operations Label: The name of the metric or property visible in vRealize Operations
Unit: If applicable, this is where you can define the unit for the data point. This will allow auto scaling in dashboards and reports.
Data Type: Defines if the data is a string or a decimal. String metrics are not recommended since they can cause performance issues in the platform. If you select decimal and the data cannot be converted to a number, the data will be discarded.
Property: This toggle Indicates if the data is a property. If set to no, the data will be processed as a metric.
KPI: this toggle indicates if the data will be treated as a KPI. KPI’s are key metrics that are used in dashboards and resource detail pages. They should be metrics that are important to the status, performance, and health of the object.
Origin: This shows the call and data path that this metric is pulled from.
Example: shows the value of the first returned data point from the request.
Object Name, Identifier, and Icon
Select object instance name: This is the metric or property from the list above that is used as the objects name in vRealize Operations.
Select Object Identifiers: Define the metrics or properties to use to uniquely define the object. You should use the fewest number of metrics to be able to accurately identify a unique object.
You must select at least one identifier per object or only the first instance of the object will be created.
List identifier: Select a field that uniquely identifies the list member. When there are multiple lists, select the field that resolves to the same value for each to link the lists together. This is used to combine responses from multiple requests into a single object. For example, if there an object requires two or more requests to be made to return properties and metrics, you can use list identifiers to resolve them to the same object.
Object Icon: You can choose the icon that will be used for this object in vRealize Operations. There Is a predefined list of icons you can choose from.
Add Existing object
To extend an existing object you must connect to your vRealize Operations system and pull in the resource kind you want to extend. Start by choosing a predefined connection or creating a new connection to your vRealize Operations system. Once you hit connect the available resource kinds will be queried and show in the list of resource kinds. You can filter on the resource type or page though the list of available options.
Select APIs and variables
From the list of API calls you select one or more requests to add to this object and then select all the data you want to add to from the list on the right. You can search the list of metrics for a specific metric or scroll through the list.
Link API Calls to Object
This is a table of all the API calls selected in the first section. From the API call you select an attribute that has a matching property on the existing object. For example, VM host name in the backup software matches the vSphere VM hostname.
Review Metrics and Properties to Include
Once selected the metrics will display in the review section. Here you will see the following information about the data.
vRealize Operations Label: The name of the metric or property visible in vRealize Operations
Unit: If applicable, this is where you can define the unit for the data point. This will allow auto scaling in dashboards and reports.
Data Type: Defines if the data is a string or a decimal. String metrics are not recommended since they can cause performance issues in the platform. If you select decimal and the data cannot be converted to a number, the data will be discarded.
Property: This toggle Indicates if the data is a property. If set to no, the data will be processed as a metric.
KPI: this toggle indicates if the data will be treated as a KPI. KPI’s are key metrics that are used in dashboards and resource detail pages. They should be metrics that are important to the status, performance, and health of the object.
Origin: This shows the call and data path that this metric is pulled from.
Example: shows the value of the first returned data point from the request.
Relationships
Relationships are a Parent to child connection that is used in vRealize operations to define the interaction between interconnected resources. Parent to child relationships are the only supported type of relationships with the Management Pack Builder.
Parent and child object
In this section you define the objects used to create the relations. Parent objects are higher in the topology.
Use Existing vrealize operations resource
Select the target vRealize Operations system. You can either choose one you have already connected or connect a new system.
Press Connect, this pulls in all the resource kinds available on that system.
If you know the resource kind you are attempting to use, you can filter the list by adding the kind name to the Select Resource section.
Select the Resource Kind you are attempting to use.
Press the Use Resource Kind box.
Matching Properties
Relationships in Management Pack Builder are created by matching all resources with matching properties. For example, a switch has a switch ID as a property and the Port has a parent switch ID property, the Parent object properties will be the switch ID and the Child object properties. With multiple matching sets, both sets of properties must match for the relationship to be created.
Events
Events from API request
Request: This si the Request endpoint setup in the Requests section to use to create events.
Events: This shows the builder where in the response hierarchy the array of events is found. Reference your API documentation to understand where in the response the event list is found.
API Response Message Attribute: This is the event message that will show in vRealize Operations. Often in API’s this would be the event description. There are two methods to create this message.
Basic: You select a single field from the response, and it is used word for word.
Advanced: You can create the message using one or more fields from the response and type any static information as well. We also allow you to edit the value of the fields using regular expressions. See the section on regular expressions for further help on this.
Severity
Events in vRealize Operations are ranked with a severity from Debug to Immediate. Please reference your API documentation for a list of valid severities they support.
API Response Severity Attribute: There are two methods to define this attribute.
Basic: You select a single field from the response, and it is used word for word.
Advanced: You can use one or more fields from the response and type any static information as well. We also allow you to edit the value of the fields using regular expressions. See the section on regular expressions for further help on this.
Map vRealize Operations severities to API response values: In this grid you map the vlues returned by the API to the severities used in vRealize Operations. The values defined in vRealize Operations are already populated in the list so based off the values defined in your API documentation you just need to map them. You can map multiple values to a vRealize Operations severity for example, say the API severity is “Hardware – Warning” and “Application – Warning” you can add another Warning line for vRealize Operations and map both the above values to it. If any of the prepopulated lines are not used, you can remove them.
At the bottom of the grid, you can set a blanket value for any unmatched severities. This is used if your do not have a well-defined severity list from your API documentation or if there are severities that you do not wish to capture.
Related Objects
Events in vRealize Operations are associated with an object. By default, all events are associated with the adapter instance however if the event can be mapped to specific object types, we allow you to define that mapping.
Mode: Due to the nature of events, you may want to associate an event with more than one object, or strictly limit to only one matching object.
First matching object: When an event would relate to more than one object, only the first object will be related to the event.
All matching objects: When an event would relate to more than one object, the event will be attached to each object.
Map Objects to API response values: In this grid you map the Events to the Objects based on the values returned by the API.
Matching Object Attribute: Define what attributes of the object to use for the match.
Basic: use a single attribute for the match.
Advanced: You can use one or more attributes from the Object and type any static information as well. We also allow you to edit the value of the fields using regular expressions. See the section on regular expressions for further help on this.
Matching API Response Attribute
Basic: use a single attribute for the match.
Advanced: You can use one or more attributes from the API and type any static information as well. We also allow you to edit the value of the fields using regular expressions. See the section on regular expressions for further help on this.
The option at the bottom allows you to relate all unmatched events to the Adapter instance, default behavior, or if this is disabled any unmatched events will be discarded.
Alerts (Optional)
Events in vRealize Operations can be used to trigger Alerts. In Management Pack Builder we give you the ability to create a single alert in vRealize Operations that will trigger for every event. For more complex alert configurations, you may use use the built in alert creation system in vRealize Operations.
Type: Describes the type of alert to trigger, and helps you categorize the alerts so that you can assign certain types of alerts to specific system administrators.
Subtype: Describes additional information about the type of alert to trigger, and helps you categorize the alerts to a more detailed level than Type, so that you can assign certain types of alerts to specific system administrators
Impact
Efficiency helps you identify optimization opportunities in your systems
Health gives you an overview of the current operational state of an object
Risk indicates potential problems that might eventually degrade the performance of the system
Wait Cycle: The number of collection cycles during which an event must be present before creating the alert.
Cancel Cycle: The number of collection cycles during which an event must be absent before removing the alert.
Recommendation: Information presented to help resolve the alert.
Configuration
This is the section used to define information about the pack and the adapter configuration settings.
Basic Settings
This section is used to define information about the pack like the name, author, and description. This information will be present in the resulting MP when installed into a vRealize Operations system, and when importing the design into a Management Pack builder appliance
Adapter Configurations
This section is used to define settings presented to the user when configuring the adapter in vRealize Operations. You can edit the configuration names and default values to better match your needs.
Credentials
This section is used to show what credential values the user must provide as defined in the source section. The only thing that can be defined here is a description of what the setting is.
Building A Pack
Building the pack is done from the design screen so if building your own design or using an imported design you will need to open the design to build the pack. Before building the pack, you will need to save any changes to the design you have done since the last save.
Once you have saved the design you should see a green checkmark to the left of the save button. This indicates the design is valid. If the checkmark is not green, there is an error in the design, and you will need to solve that before you can build. To understand what is wrong, click on the Checkmark and resolve any errors listed there.
Build Wizard
Preview
This shows you the outcome of your design. Is shows the Objects, Relationships, and Events you configured.
Objects: lists all the defined objects, both new and those extended from vRealize Operations. You can see all the Identifiers, Properties, and Metrics defined on every object by select that object from the list.
Relationships: Shows a list of all relationships including the Parent and child objects
Events: shows you the details for any event you select from the list.
Sample Collection
This is an optional step that allows you to run a sample collection against your target system and a vRealize Operations system. This will show you the outcome of that collection including any Objects created, matching relationships, and events. It is important to know that the objects and metrics return as you expect before installing the management pack into a live vRealize Operations system. It may also be important to get an understanding of scale and potential performance impact by installing the management pack before deploying to a production environment.
It is important to know that the objects and metrics return as you expect before installing the management pack into a live vrealize operations system. It may also be important to get an understanding of scale and potential performance impact by installing the management pack before deploying to a production environment.
Create Management Pack:
This creates the pack file and provides some stats around the build and the link to download the pack.
Creating A Regular Expression
A regular expression (sometimes called a rational expression) is a sequence of characters that define a search pattern, mainly for use in pattern matching with strings, or string matching. When using a Regular Expression in Management Pack Builder you can enter in the expression in the Regex field. When test is pressed the Sample Value will be run through the expression and the result will be displayed in the Sample Output. Specific help on how to create a Regular Expression can be gotten online from several sites.
