Adding and updating VM managers

Edit online

You use the PUT operation on the api/sam/vmmanagers element to add or update VM managers.

Permissions

To add or update VM managers, the following requirements must be met:
  • You must have the Manage VM Managers and Servers permission
  • The computer group to which you are assigned must contain the computer on which the VM Manager Tool is installed

Resource URL

https://server_url:server_port/api/sam/vmmanagers

Resource information

Table 1. Resource information
Operation details Description
Purpose Adds a new VM manager or changes an existing one.
HTTP method PUT
Resource URI https://server_url:server_port/api/sam/vmmanagers
Request Content-Type application/json
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Response Content-Type application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Normal HTTP response codes
  • 200 - OK
Error HTTP response codes
  • 9.2.39 207 – "Multi-Status" if at least one of the actions failed due to an incorrect value of a parameter. For example, if you added two VM managers and updated one VM manager, and any of the actions failed, the 207 response is returned with information about the status and details of each action.
  • 400 – "Bad Request" if a query parameter contains errors or is missing
  • 401 – "Unauthorized" if the user does not have the Manage VM Managers and Servers permission
  • 403 – "Forbidden" if no VM Manager Tool is defined in the License Metric Tool database. The code might also indicate an unknown problem that requires contacting IBM support.

Request attributes

Table 2. Request attributes
Attribute Description
login User name that is used to access the VM manager.
password Password that is used to access the VM manager. The password is encrypted after it is sent.
protocol Communication protocol used by the VM manager. The attribute is applicable only for Hyper-V and Azure Stack HCI.
  • 0 - WinRM
  • 1 - PowerShell
sharecredentials Indicates whether the VM manager shares credentials with other hosts in the same cluster. The attribute is applicable only for Hyper-V and Azure Stack HCI.
  • true - the VM manager shares the credentials and it is not necessary to specify them
  • false - the VM manager does not share the credentials
type Type of the VM manager.
  • 1 - Hyper-V or Azure Stack HCI
  • 2 - VMware vSphere or VMware ESX
  • 3 - RHV-M or Oracle Linux Virtualization Manager
  • 9.2.12 4 - XenServer (formerly Citrix Hypervisor)
  • 9.2.17 6 - Nutanix
url Web address of the VM manager. To add a VM manager, specify its full URL. The default URL differs depending on the virtualization type.
  • 9.2.37 Red Hat OpenShift: https://{manager-address}:6443
  • 9.2.12 XenServer (formerly Citrix Hypervisor): https://{manager-address}
  • Hyper-V or Azure Stack HCI: https://{manager-address}:5986/wsman

    In case of Azure Stack HCI, provide a connection to a host in the cluster. Then, share credentials to connect to other hosts. If it is not possible, configure a connection to each host in the cluster separately.

  • 9.2.17 Nutanix:
    • https://{manager-address}:9440/PrismGateway/services/rest/v2.0
    • 9.2.41 https://{manager-address}:9440/api/nutanix/v3

      If you provide only the host and port, /api/nutanix/v3 is automatically added.

  • 9.2.25 Oracle Linux Virtualization Manager: https://{manager-address}/ovirt-engine/api
  • RHV-M: https://{manager-address}/ovirt-engine/api
  • vCenter: https://{manager-address}/sdk/vimService.wsdl
vmmanagerid ID of the VM manager that you want to change. To obtain the ID, use REST API for the retrieval of VM managers.
9.2.22 vmmanagertooltype VM Manager Tool deployment type.
  • 1 - Central
  • 2 - Local
For more information, see: VM Manager Tool deployment types and flow of data.
vmmanagertoolid ID of the VM Manager Tool that collects data from the VM manager that you want to change. To obtain the ID, use REST API for the retrieval of VM managers.

Example HTTP conversation - adding a VM manager

To add a new VM manager, provide the following attributes:
  • login
  • password
  • url
  • type
Request
PUT https://server_url:server_port/api/sam/vmmanagers
Request header
Accept: application/json
Accept-Language: en-US
Token: <token>
Request body
[{
    "login":"user1",
    "password":"<password_1>",
    "url":"<URL_1>",
    "type":1
}]
Response header
200

Example HTTP conversation - adding a VM manager that failed

Request
PUT https://server_url:server_port/api/sam/vmmanagers
Request header
Accept: application/json
Accept-Language: en-US
Token: <token>
Request body
[{
    "login":"user1",
    "password":"<password_1>",
    "url":"<URL_1>",
    "type":1
}]
Response header
207
Response body
{
    "status": 
    [
        {
            "description":
            {
                "description":
                {
                    "type": 1,
                    "url": "<URL_1>"
                },
                "type": "VMMAN"
            },
            "id": 1,
            "actions":
            [
                {
                    "type": "ADD",
                                 "error": "Empty or not valid property: Login.",
                    "status": "FAILURE"
                }
            ]
        }
    ]
}

Example HTTP conversation - changing a VM manager

To change an existing VM manager, provide the following attributes:
  • vmmanagerid
  • login
  • password
  • url
  • type
Important: All attributes must be provided in the request regardless of how many of the attributes you want to change.
Request
PUT https://server_url:server_port/api/sam/vmmanagers
Request header
Accept: application/json
Accept-Language: en-US
Token: <token>
Request body
[{
    "vmmanagerid":1,
    "login":"user1",
    "password":"<password>",
    "url":"<URL>",
    "type":3
}]
Response
200 OK