VMware Aria Operations Management Pack Builder™ is a stand-alone appliance that enables the creation of custom management packs for use in VMware Aria 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.
For help with Management Pack Builder, contact the Community Page.
Installing VMware Aria Operations Management Pack Builder
Management Pack Builder 2.0 needs to be a fresh installation; "upgrade in place" is not supported from 1.x to 2.0. Please export any design from your 1.x version to import into 2.0 once installed.
VMware Aria Operations Management Pack Builder consists of a single appliance. To create the appliance, use the vSphere client to download and deploy the VMware Aria Operations Management Pack Builder virtual machine.
Verify that you have permission to deploy OVF templates to the inventory.
Reserve a static IP address for the virtual machine, and the associated domain name, domain search path, domain name servers, default gateway, and network mask values.
Plan your domain and machine naming so that the deployed virtual machine name begins and ends with 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).
Download the VMware Aria 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; only on-prem versions of VMware Aria Operations are supported.
Procedure
Select the vSphere Deploy OVF Template option.
Select an OVF template
Enter the path to the VMware Aria Operations .ova file.
Click Next.
Select a name and folder
Enter a Virtual Machine name. The name should start and end with an alphanumeric character, and it may not contain underscores.
Select a destination folder.
Click Next.
Select a compute resource
Select the destination compute resource for the MP Builder VM.
Click Next.
Review Details
Review that all the details look correct.
Click Next.
License agreements
Review the License Agreements.
Select “I accept all license agreements”.
Click Next.
Select storage
Select the destination storage for the MP Builder VM
Click Next.
Select networks
Select the destination network for the MP Builder VM
Select IPv4 or IPv6.
Note:Static IP address is the only supported configuration
Click Next.
Customize template
Application
Set the default MP Builder VM OS root password. NOTE: this is different from the application password used in the web application
Confirm the password
Networking Properties
Set the default gateway, domain name, domain search path, domain name servers, IP address, and netmask. NOTE: DHCP is not supported.
Click Next.
Ready to complete
Review the configuration again.
Click Finish.
After you click Finish, the OVA will deploy. After deployment is complete, power on the Virtual Machine.
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 adminand 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: !@#$%^&*
Importing designs into Management Pack Builder
Importing a design from a 1.x version of MP builder requires a JSON configuration file exported from the existing version and a reference environment available to run test connection against.
From the Designs page, select Create a new design, and from the option choose Import.
File Location
Browse for and select the JSON design file you want to import. The file will be verified as a valid design file and the Author and Description will be shown.
Configure
Here you will define the reference environment to test the design against.
Hostname: This is the host or your reference environment. It can be a single IP, a hostname, or a FQDN.
Credentials
Username: User on the reference environment that is authorized to query the intended API endpoint.
Password: User’s password for authentication
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 form 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 VMware Aria 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. For every object you will provide the metrics and properties by adding one or more requests. VMware Aria Operations manages metrics by the objects and has limits based on number of objects and metrics. Please review the sizing guide for the appropriate sizing of VMware Aria Operations when designing your objects.
You can also extend existing objects in your VMware Aria Operations environment such as VMs, 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 sizing limits based on the number of objects and metrics.
Requests: These are the API requests used to add metrics and properties. To understand what is available on these requests, refer to the API documentation. In our switch example, the requests would be defined for:
the interface endpoint that lists all the ports
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 VMware Aria Operations to understand the connectivity between your objects. In our switch example, the switch would be the parent to the ports, CPUs, and fans. You can also add relationships to VMware Aria Operations objects like hosts, VMs, or third-party resources like data arrays.
Creating A Design
To create a new design, click Create and then New on the homepage. Enter a Management Pack Name and Solution Description.
Setting up the Source
The source is used to pull data from the API to be used in configuring and testing the design; only one source at a time is supported in the designer. This should be a representative environment that is close to a production setup so the new management pack design can define a comprehensive model of the monitored technology.
Reference Environment Settings
In this section, define the necessary settings to connect to a reference environment which will be used while designing the new management pack. These settings are only for the Management Pack Builder design process; they are not hardcoded into the pack.
Hostname: This is the host of 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 whether the connection does not use SSL, Uses SSL but does not verify the certificate, or Uses SSL and verifies the certificate.
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: Basicand Custom. The configuration here is used for every subsequent call, so you only need to configure authentication once.
Basic authentication
• Username: User on reference system that is authorized to query the intended API endpoint.
• Password: User’s password for authentication
• Will session authentication be used? Select "yes" if you plan on using sessions for your collection.
Custom authentication
Custom authentication allows the user to add custom variables to be used in the advanced section of the source creation. This is generally used with permanent session tokens or any variable sent with every request.
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.
Get Session API Request
HTTP Method: Based on the API requirements this will be either a POST, GET, or PUT
API Path: This is the path to the session creation resource as defined by the API documentation.
Get Session Request Advanced (Optional)
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.
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.
Session Fields
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.
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.
Release Session Request
It is recommended to define a Release Session Request. This request will log out the session, reduce session leaks, and improve security.
HTTP Method: Based on the API requirements this will be either a POST, GET, or DELETE.
API Path: This is the path to the API endpoint you want to use as the test endpoint.
Test Connection Request
The test connection confirms that all the source data is set up 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 make a call to delete the session.
HTTP Method: Based on the API requirements this will be either a POST, GET, or PUT
API Path: This is the path to the session creation resource as defined by the API documentation.
Make Test Connection Request
The response section will show the 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.
If necessary to import a certificate, see the Importing an SSL Certificate section
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 settings necessary for this section.
Chain From Other API Calls
In some APIs you must 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.
Request: The initial request you are attempting to chain from.
API Response List: The list in the API response you are looking to pull the parameters from to use in this request.
Chaining Parameters
When adding a parameter, you select the part of the originating request data structure from the API Response List, the Attribute in the response list to use for the parameter value, and the parameter label. To use a parameter, click the copy button to get the ${requestParameters.[variable]} substitution string and paste it later in the API Path or Advanced sections.
API Path
Define the endpoint to be used for the request. Note: the source hostname, port, and base path will be prepended to this path for the request URL.
HTTP Method: This is the method used for the request. It will be either a GET, PUT, PATCH, or POST.
API Path: Endpoint that needs to be call to retrieve the data.
Request Name: Name for this request used in future settings in the design.
Advanced (optional)
In this section you can add specific data to the requests body, headers, and query parameters, as defined by the API documentation.
Paging
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 to determine whetherpaging 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 of records per page.
Limit Value: The number of records returned per page.
Objects
This section is where you define the objects that will be part of your custom management pack. You can define new objects or extend existing objects from VMware Aria Operations with new metrics and properties.
Add New Object
Each Object Type should be named to indicate what you are configuring. This is the resource type for the object in VMware Aria Operations. You can also choose the icon that will be used in VMware Aria Operations.
Attributes from the API calls
From the list of Requests, 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.
Properties and Metrics
Here you will see the following information about the data.
VMware Aria Operations Label: The name of the metric or property visible in VMware Aria 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 whether 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 whether the data is a property. If set to no, the data will be processed as a metric.
KPI: this toggle indicates whether the data will be treated as a KPI. KPIs 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.
Expanded row view:
Request: Shows the call and data path from which this metric is pulled.
List: List in the request response from which the data is pulled.
Attribute: Name in the response being pulled.
Example: Shows the value of the first returned data point from the request.
Object Name and Identifier
Select object instance name: This is the metric or property from the list above that is used as the objects name in VMware Aria Operations.
Select Object Identifiers: Define the properties using the smallest set of properties that will accurately and uniquely identify each object.
Attention:You must select at least one identifier per object or only the first instance of the object will be created.
Attribute Bindings
When combining data from multiple JSON arrays into a single object, it's necessary to establish a base array and select a corresponding attribute from each of the other arrays for mapping. You will only see this if it is required.
Add Existing Object
To extend an existing object you must connect to your VMware Aria 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 VMware Aria Operations system. Once you hit connect, the available resource kinds will be queried and shown in the list of resource kinds. You can filter by the resource type or page through the list of available options.
Select APIs and variables
From the list of API calls, select one or more requests to add to this object and then select all the data you want to add from the list on the right. You can search the list of metrics for a specific metric or scroll through the list.
Metrics and Properties
Once selected, the metrics will display in the review section. Here you will see the following information about the data:
VMware Aria Operations Label: The name of the metric or property visible in VMware Aria Operations
Data Type: Defines whether 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 whether the data is a property. If set to no, the data will be processed as a metric.
Expanded row view:
Request: Shows the call and data path from which this metric is pulled.
List: List in the request response from which the data is pulled.
Attribute: Name in the response being pulled.
Example: Shows the value of the first returned data point from the request.
Attribute Bindings
This is where you relate the data from the API call to the existing objects in Aria Operations.
API Attribute: The property or metric from the API request that identifies the data.
Object Property: The matching data value from the existing Aria Operations Object.
Relationships
Relationships are a Parent to Child connection that is used in VMware Aria 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 VMware Aria Operations Object
Select the target VMware Aria 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 property and the Port has a parent switch ID property. The Parent object properties and the properties of any relevant Child object(s) will always match, e.g. switch ID with parent switch ID. With multiple matching sets, both sets of properties must match for the relationship to be created. This can be either case-sensitive or insensitive and use basic or advanced matching.
Events
Events from API request
Request: This is 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 VMware Aria Operations. Often in APIs 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. You can also edit the value of the fields using regular expressions. See the section on regular expressions for further help on this.
Severity
Events in VMware Aria Operations are ranked with a severity from Info 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 VMware Aria Operations severities to API response values: In this grid you map the values returned by the API to the severities used in VMware Aria Operations. The values defined in VMware Aria 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 VMware Aria Operations severity. For example, say the API severity is “Hardware – Warning” and “Application – Warning”. You can add another Warning line for VMware Aria 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 you 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 VMware Aria 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, you candefine 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. You can also 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. You can also 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 define the default behavior for events that didn't map to any objects. They can either be associated with the adapter instance or discarded.
Alerts (Optional)
Events in VMware Aria Operations can be used to trigger Alerts. In Management Pack Builder, you have the ability to create a single alert in VMware Aria Operations that will trigger for every event. For more complex alert configurations, you may use the built in alert creation system in VMware Aria 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.
Content
In this section you can associate dashboards and supermetrics with your design.
Build, install, and configure your management pack in VMware Aria Operations. Create your dashboards and/or supermetrics.
Export your dashboard(s) or supermetric(s) from VMware Aria Operations. If necessary, unzip the dashboard(s) or supermetric(s). In Management Pack Builder, select Import and then Browse to select your dashboard or supermetric JSON file.
Any content associated with the design will be included in subsequent PAKs built from this design. It is up to you to ensure the dashboard(s) or supermetric(s) are compatible with the management pack.
Configuration
This is the section used to define information about the pack and the adapter configuration settings.
Basic Configuration
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 VMware Aria Operations system, and when importing the design into a Management Pack builder appliance.
You can add custom Basic Configuration parameters and use them in your Source and Requests definitions. To start, click Add. Specify the name, type, and description of your custom configuration parameter. If you choose the list type, specify the list options. Specify a “value” to be used when making requests in Management Pack Builder. Specify a default value which will show up in VMware Aria Operations during management pack configuration. To use your custom parameter, click the copy button under the Usage column and paste the ${configuration.[paramName]}substitution string in the Source or Request field where you would like to use it.
Advanced Configuration
This section is used to define settings presented to the user when configuring the adapter in VMware Aria Operations. You can edit the configuration names and default values to better match your needs.
You can add custom Advanced Configuration parameters and use them in your Source and Requests definitions. To start, click Add. Specify the name, type, and description of your custom configuration parameter. If you choose the list type, specify the list options. Specify a “value” to be used when making requests in Management Pack Builder. Specify a default value which will show up in VMware Aria Operations during management pack configuration. To use your custom parameter, click the copy button under the Usage column and paste the ${configuration.[paramName]}substitution string in the Source or Request field where you would like to use it.
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 The Management Pack
Perform Collection
This will run a full collection for your design. All the defined Requests will be run against the defined Source and the responses will be parsed into the defined Objects, Relationships, and Events.
Summary
This shows you the outcome of the collection, including whether the collection successfully completed, how long the collection took, and the counts of objects, metrics, properties, events, and relationships collected.
It is vital to pay attention to the counts of objects, metrics, etc.
Before installing your management pack, ensure that VMware Aria Operations is sized appropriately to handle the new data you’re creating.
Log
Shows the full log of the collection. The default Logging Level is INFO. You can set it to DEBUG to help debug any problems with collection or WARN to see only WARN-level logs and above. You can download the log for further troubleshooting.
Objects
Select an Object Type and Object to see the details of that object, including identifiers, properties, relationships, and events.
Events
This section shows the collected events, including their message, severity, and the associated object.
Build
Click Build to build your management pack. When the build is complete, you can download it immediately. You can also see the new build and any previous builds on the home page under the Builds column.
Creating A Regular Expression
A regular expression is a sequence of characters that define a search pattern, mainly for use in string matching. Management Pack Builder supports the Java 8 regular expression format. When using a Regular Expression in Management Pack Builder you can enter in the expression in the Regex field. When the test button is pressed the Sample Value will be run through the expression and the result will be displayed in the Sample Output.
Importing An SSL Certificate
Some API targets may require you to import a certificate into the Management Pack Builder truststore. The truststore is located at /opt/vmware/ssl/truststore. You can import certificates like this:
1. Retrieve the certificate from the target (replace hostname and https_port):
openssl s_client -showcerts -connect [hostname]:[https_port] </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem
2. Import the certificate (cert.pem) into the truststore
keytool -import -noprompt -alias host123 -file cert.pem -keystore /opt/vmware/ssl/truststore -storepass changeit
