OpenManage Integration for VMware vCenter Version 5.2 API Guide October 2020 Rev.
Notes, cautions, and warnings NOTE: A NOTE indicates important information that helps you make better use of your product. CAUTION: A CAUTION indicates either potential damage to hardware or loss of data and tells you how to avoid the problem. WARNING: A WARNING indicates a potential for property damage, personal injury, or death. © 2010 - 2020 Dell Inc. or its subsidiaries. All rights reserved. Dell, EMC, and other trademarks are trademarks of Dell Inc. or its subsidiaries.
Contents Chapter 1: Overview...................................................................................................................... 5 Supported APIs.................................................................................................................................................................... 5 Prerequisites.........................................................................................................................................................................
Create cluster level firmware update jobs.................................................................................................................. 28 Get list of firmware update jobs (Host and Cluster)................................................................................................ 29 Get firmware update job details (Host or Cluster)................................................................................................... 30 Chapter 10: System profile management.............
1 Overview OpenManage Integration for VMware vCenter (OMIVV) provides RESTful APIs to enable automation. The support for RESTful API is available from version 5.2.0. The APIs are compliant with OpenAPI Specification (OAS) 3.0.0. This document is intended for a vCenter Administrator. It is assumed that the reader is familiar with REST APIs and programmatic interaction with REST APIs. Any programming language can be used to create applications that interface with these APIs.
NOTE: All the URIs and query parameters are case-sensitive. Request headers The request header represents headers in the client HTTPS request that are used to communicate client preferences to the service end-point. The bearer token is the request header. Sequence of API for firmware update To perform the firmware update, run the following APIs in the given order: 1. AuthenticationService/login—Start an OMIVV session using OMIVV credentials. You will receive an access token.
2 Security The authentication and authorization flows are prerequisites to any API invocation. The request is forwarded to the CXF server defined for the REST API after the invocation. If there is authorization and authentication failure, an appropriate error code with message is sent to the API client. On success, the request is forwarded to the appropriate REST service endpoint (API) defined on the CXF servlet.
vCenter authorization Authorization flow validates the following: ● Session token ● vCenter user credentials for the required permissions to run the API Validate session token OMIVV validates the token that is received from the API client against the following: ● Tampering ● Session validity Validate vCenter user credentials APIs are authorized against the vCenter user credentials, when required. Set an operational context which indicates the vCenter and the associated user credentials.
3 Session management Topics: • • Start an OMIVV session End an OMIVV session Start an OMIVV session Description: Starts an OMIVV session for the given OMIVV IP. The OMIVV session is valid for 60 minutes. Only the admin user is allowed to successfully log in as an API user. The bearer token received from this API must be used for other APIs as a header parameter.
End an OMIVV session Description: Logs out from the OMIVV session. This API internally invalidate the bearer token. Command or URL: /Services/AuthenticationService/logoff Method: POST Authorization: Bearer authentication Parameters: None vCenter privileges required: None HTTP response code: Table 2.
4 Console management Topics: • • • • • Get list of registered vCenters Get vCenter tree view of data center Set vCenter context Get cluster details Get cluster health Get list of registered vCenters Description: Gets the list of all the registered vCenters for the given OMIVV. Command or URL: /Services/ConsoleService/Consoles Method: GET Parameters: None Authorization: Bearer authentication vCenter privileges required: None HTTP response code: Table 3.
All Dell EMC and OEM managed or unmanaged hosts are listed. Command or URL: /Services/ConsoleService/Consoles/{id} Method: GET Authorization: Bearer authentication Parameters: Table 4. Parameters Parameter Value Description Default value Parameter type Data type id (required) Resource ID. Use the vCenter ID received from the Get list of registered vCenters API. For more information, see Get list of registered vCenters on page 11.
{ , "id": "{Host ID}", "href": "", "objectType": "Host", "hostip": "{Host IP}", "hostName": "{Hostname or FQDN}", "managementIP": "{iDRAC IP}", "serviceTag": "{Host Service Tag}", "model": "{Server Model Name}", "systemId": "{System ID}" } ] } For more information, see Response body on page 39. Set vCenter context Description: Sets the vCenter context on which user want to perform any operation. Enter the vCenter ID received from /Services/ConsoleService/Consoles API.
Get cluster details Description: Gets the cluster details of the given cluster ID. You can view all the hosts belong to the cluster. The vSAN and vSphere cluster details are displayed. Command or URL: /Services/ConsoleService/Clusters/{cluster-id} Method: GET Authorization: Bearer authentication Parameters: Table 7. Parameters Parameter Value Description Default value Parameter type Data type id (required) Resource ID. Use the cluster ID received from the Get vCenter tree view of datacenter API.
Get cluster health Description: Gets the health (DRS and vSAN cluster health) of the given cluster ID. The health data is used for assessing the firmware update. The data that is displayed here is real-time health information. Command or URL: /Services/ConsoleService/Clusters/{cluster_id}/Details Method: GET Authorization: Bearer authentication Parameters: Table 9. Parameters Parameter Value Description Default value Parameter type Data type id (required) Resource ID.
5 Repository profile management Topics: • • Get list of repository profiles Get repository profile details Get list of repository profiles Description: Gets the list of all repository profiles that are created in OMIVV UI. Command or URL: /Services/PluginProfileService/RepositoryProfiles Method: GET Authorization: Bearer authentication Parameters: None vCenter privileges required: Dell.Inventory.Configure Inventory HTTP response code: Table 11.
Command or URL: /Services/PluginProfileService/RepositoryProfiles/{id} Method: GET Authorization: Bearer authentication Parameters: Table 12. Parameters Parameter Value Description Default value Parameter type Data type id (required) Resource ID. Use the repository profile ID received from the Get list of repository profiles API. For more information, see Get list of repository profiles on page 16 N/A Path String vCenter privileges required: Dell.Inventory.
6 Cluster profile management Topics: • • Get list of cluster profiles Get details of cluster profiles Get list of cluster profiles Description: Gets the list of all cluster profiles that are created in OMIVV UI. Command or URL: /Services/PluginProfileService/ClusterProfiles Method: GET Authorization: Bearer authentication Parameters: None vCenter privileges required: Dell.Inventory.Configure Inventory HTTP response code: Table 14.
Method: GET Authorization: Bearer authentication Parameters: Table 15. Parameters Parameter Value Description Default value Parameter type Data type id (required) Resource ID. Use the cluster profile ID received from the Get list of cluster profiles API. For more information, see Get list of cluster profiles on page 18 N/A Path String vCenter Privileges required: Dell.Inventory.Configure Inventory HTTP response code: Table 16.
} } } "objectType": "BaseProfileMetadata", "profileName": "{System profile name}", "description": "{System profile description}" For more information, see Response body on page 39.
7 Firmware repository inventory management Topics: • Get firmware repository inventory details Get firmware repository inventory details Description: Gets the details of firmware repository inventory. Ensure that the repository is successfully downloaded. The driver repository inventory is not supported. You can view the details like bundle ID, list of components of the particular bundle ID for the specific server model.
Table 18. HTTP response code (continued) Code Description 429 Too many requests 500 Internal Server error / timeout For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
8 Firmware inventory management Topics: • • Create host level firmware inventory report Create cluster level firmware inventory report Create host level firmware inventory report Description: Creates the host level firmware inventory report. You can view the host component details that is associated to the given bundle ID before performing firmware update. Ensure that the host is managed by OMIVV and management complaint.
Table 19. HTTP response code (continued) Code Description 500 Internal Server error / timeout For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
}, { } } "bundleID":"{Bundle ID}" "systemId":"{System ID}", "bundleID":"{Bundle ID}" ], "repoProfileID":"{Repository profile ID}" For more information about request body parameters, see Request body on page 36. Parameters: None vCenter privileges required: Dell.Configuration.Firmware Update HTTP response code: Table 20.
] } } ] }, "rebootRequired": {Host reboot required}, "releaseDate": "{Component release date and month}" }, "hostReport": null For more information, see Response body on page 39.
9 Firmware update management Topics: • • • • Create host level firmware update jobs Create cluster level firmware update jobs Get list of firmware update jobs (Host and Cluster) Get firmware update job details (Host or Cluster) Create host level firmware update jobs Description: Creates the firmware update job for a host managed by OMIVV. You can update both vSAN and vSphere host. Driver update is not supported. Chassis and single DUP firmware updates are not supported.
HTTP response code: Table 21. HTTP response code Code Description 202 OK 400 Operational Context not set 401 Authorization failure 403 VCenter permission denied 429 Too many requests 500 Internal Server error / timeout For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
"resetIDracAndDeleteJobs":{true or false}, "enterMaintenanceModetimeout":60, “enterMaintenanceModeOption”: “{enter maintenance mode option}” } } For more information about request body parameters, see Request body on page 36. Authorization: Bearer authentication Parameters: None vCenter privileges required: Dell.Configuration.Firmware Update HTTP response code: Table 22.
Table 23. HTTP response code (continued) Code Description 401 Authorization failure 403 VCenter permission denied 429 Too many requests 500 Internal Server error / timeout For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
10 System profile management Topics: • • Get list of system profiles Get system profile details Get list of system profiles Description: Gets the list of all system profiles that are created in OMIVV UI. Command or URL: /Services/PluginProfileService/SystemProfiles Method: GET Authorization: Bearer authentication Parameters: None vCenter privileges required: None HTTP response code: Table 26.
Command or URL: /Services/PluginProfileService/SystemProfiles Method: GET Authorization: Bearer authentication Parameters: None vCenter privileges required: None HTTP response code: Table 27. HTTP response code Code Description 200 OK 400 Operation context is not set 401 Authorization failure 403 vCenter permission denied 429 Too many requests 500 Internal Server error / timeout For OMIVV-Specific error codes, see OMIVV-Specific error codes on page 47.
11 Drift management Topics: • Get firmware drift report Get firmware drift report Description: Gets the firmware drift report for specific cluster. This API helps you to get the drifted components details before running firmware update. Command or URL: /Services/DriftDetectionService/DriftReport/{id}/FwDriftDetails Method: GET Authorization: Bearer authentication Parameters: Table 28. Parameters Parameter Value Description Default value id (required) Resource ID.
"overallSummary": { "compliantStatus": "{Compliance Status}", "nonCompliantType": "{Non-compliant Type}", "noncompliantTypeDescription": "{Firmware version is different for N number of component (s)}" }, "componentDriftList": [ { "componentDetails": { "componentID": "{Component ID}", "packageID": "{Package ID}", "bundleID": "{Bundle ID}", "instanceID": "{Instance ID}", "componentName": "{Component Name}", "componentType": "{Component Type}", "componentTypeDisplay": "{Component Type Display}", "upgrade": "Co
A Request body Start an OMIVV session Table 30. Start an OMIVV session API Parameter Description username OMIVV username. Only admin user is allowed to login to API. password OMIVV password Set vCenter context Table 31. Set vCenter context API Parameter Description consoleId vCenter ID username vCenter username domain vCenter domain password vCenter password Create host or cluster level firmware inventory report Table 32.
Table 33. Cluster or host level firmware update job (continued) Parameter Description The value for update type is case-sensitive. Enter the value in upper case. OMIVV supports only FIRMWARE update type. updateTartgetType Update Target Type (host or cluster).
Table 33. Cluster or host level firmware update job (continued) Parameter Description clusterId Cluster ID. To get the cluster ID, run /Services/ ConsoleService/Consoles/{id}. bundleId Bundle ID. To get the bundle ID, run /Services/ RepositoryManagementService/RepositoryData? bundleId={bundleId} packageIDs package ID. To get the package ID, run /Services/ UpdateService/FWReport. Package ID of the up-to-date components are not supported and firmware update job fails.
B Response body This topic describes each parameter in the example response. Start an OMIVV session Table 34. Response body Field Type Description accessToken String Token ID tokenType String Token type expiresAt Integer and string Expiry date and time for token ID. Get list of registered vCenters Table 35. Response body Field Type Description id String vCenter ID hostname String vCenter Hostname or FQDN ip String vCenter IP Get vCenter tree view of datacenter Table 36.
Get cluster details Table 37.
Table 40. Response body (continued) Field Type Description name String Cluster name repoType String Repository profile type (Driver or Firmware) Get list of repository profiles Table 41. Response body Field Type Description id String vCenter ID profileName String Repository profile name Get repository profile details Table 42.
Table 43. Response body (continued) Field Type Description targetOS String Target host OS name. Windows target OS used for firmware update using iDRAC.
Create cluster level firmware inventory report Table 45.
Get host or cluster firmware update job details Table 48.
Table 48. Response body (continued) Field Type Description migratePoweredOffAndSuspendedVMs Boolean Move powered-off and suspended virtual machines to other hosts in cluster. Disabling this option disconnects VM until the host device is online. resetiDracAndDeleteJobs Boolean Clears all the iDRAC jobs present in the Job Queue followed by iDRAC reset before updating firmware on the host.
Table 49. Get firmware drift report (continued) Field Type Description COMPONENT MISSING/ATTRIBUTE_MISMATCH NOT_APPLICABLE nonCompliantType String Reason for non-compliance noncompliantTypeDescription String Detailed description for non-compliance componentID String Component ID packageID String Package ID bundleID String Bundle ID instanceID String FQDD componentName String Component Name componentType String Component Type componentTypeDisplay String Component Type Display.
C OMIVV-Specific error codes Table 50. OMIVV-specific error codes Code Description 11501 Number of active sessions limit exceeded. 11502 Number of active client limit exceeded. 11503 Input user data is not valid to process the login request. 11504 Exception occurred in token generation. 11505 User is not authorized to process the login request. 11506 Not a valid API Action specified. 11507 Account is locked. 11508 Request limit per minute exceeded. 11509 Empty Action request.
Table 50. OMIVV-specific error codes (continued) Code Description 10401 The requestinfo is null or request does not contain serverIP details. 10402 Unable to find the cluster details because cluster is not part of the selected vCenter: {0} 10601 Repository profile does not exist. 10901 Cluster profile is not created. 11001 Cluster profile does not exist. 10701 Invalid repository profile {0}. 10702 The repository {0} is not downloaded or refreshed.
Table 50. OMIVV-specific error codes (continued) Code Description 11302 enterMaintenanceModeOption, exitMaintenanceMode, migratePoweredOffAndSuspendedVMs, and enterMaintenanceModetimeout are not applicable for rebootOptions with values FORCEREBOOT or NEXTREBOOT. 11303 firmwareUpdateTargets cannot be null or empty. 11304 More than one firmwareUpdateTargets is not supported for HOST firmware update. 11305 Invalid job schedule. 11306 Invalid jobSpecificCustomConfiguration details : {0}.
Table 50. OMIVV-specific error codes (continued) Code Description 11332 Do not enter true or false or null values for both the runNow and runLater job schedules at a time. 11333 Schedule the job at least 30 minutes after the UTC current time: {0}. 11334 The dateTime values for job schedular should not be null or empty. 11335 The dateTime used for job schedular is invalid. 11336 The dateTime format for job schedular should be : yyyy-MMdd'T'HH:mm:ssZ. 11337 Host {0} is not part of the cluster.
Table 50. OMIVV-specific error codes (continued) Code Description 12504 Invalid Parameters. 12505 vCenter for which the Operational Context was set got unregistered with the appliance. 12506 Could not find the request header information. 12507 Could not find the Bearer Authorization token. 12508 Invalid Server Context. 12509 Error in connecting to vCenter. 12510 vCenter User is not authorized to access this URI. 12511 URI not supported by OMIVV.
