Compute host registration

Edit online

The Compute Host Registration APIs provide the capability to specify hosts that must be managed by the PowerVC Management System. These capabilities include adding hosts, removing hosts, updating the registration information for existing hosts, or retrieving the information about the hosts that are currently managed. Register the Hardware Management Console before you register the host.

Compute host registration API options

Table 1. Options for compute host registration API
Method	URI	Description
POST	`/v2.1/{tenant_id}/os-hosts`	Registers or adds a new compute host.
GET	`/v2.1/{tenant_id}/os-hosts/{host_name}`	Shows the details of a managed compute host.
DELETE	`/v2.1/{tenant_id}/os-hosts/{host_name}`	Unregisters or removes a managed compute host.
PUT	`/v2.1/{tenant_id}/os-hosts/{host_name}/update-registration`	Updates or edits a managed compute host.
PUT	`/v2.1/{tenant_id}/os-hosts/{host_name}/recall-vm`	Recalls all virtual machines that were moved from this host during host maintenance mode or automated remote restart.
GET	`/v2.1/{tenant_id}/os-hosts/{host_name}/all-servers`	Lists existing virtual machines on the host.
POST	`/v2.1/{tenant_id}/os-hosts/{host_name}/onboard`	Starts the process of managing an existing virtual machine.
POST	`/v2.1/{tenant_id}/os-hosts/{host_name}/unmanage`	Unmanages virtual machines that are currently managed by PowerVC.

Register or add a compute host

This operation registers or adds a host to the list that is managed by PowerVC. This API takes the IP address and credentials for the HMC in the request body as input, and registers the host with PowerVC.

Response codes

Normal response code: OK (200)
Error response code: Bad Request (400®), Server Error (500)

Request parameters

Table 2. Parameters in the request for compute host registration
Name	Style	Type	Description
`host`	body	string	Internally generated name that is used to look up the host.
`host_name`	body	string	Internal name for the host that is returned from the `ibm-hmcs/hosts` API.
`hmc_uuids`	body	list of strings	List of UUIDs of the HMCs to manage the host. Only one is supported.
`host_type`	body	string	The type of the host that is being registered. Only `powervm` is supported.
`host_display_name`	body	string	Optional value. User-specified name to give to the host. The value defaults to the name on the HMC.
`auto_add_certificate`	body	Boolean	Optional value. Whether to auto-accept or add the X.509 Certificate for the HMC (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is `True`.

{"host": { 
   "registration": { 
     "host_name": "8246L2D_1234567", 
     "hmc_uuids": ["34ab41180-..."], 
     "host_type": "powervm",  
     "host_display_name": "My Host 1" 
  }
 }
}

Response body

Table 3. Parameters in the response for compute host registration
Name	Style	Type	Description
`host`	body	string	Internally generated name that is used to look up the host.
`host_name`	body	string	Internal name for the host that is returned from the `ibm-hmcs/hosts` API.
`hmc_uuids`	body	list of strings	List of UUIDs of the HMCs to manage the host. Only one is supported.
`host_type`	body	string	The type of the host that is being registered. Only `powervm` is supported.
`host_display_name`	body	string	Optional value. User-specified name to give to the host. The value defaults to the name on the HMC.
`registered_at`	body	string	The date and time when the host is registered in PowerVC.
`host_proc_level_type`	body	string	The latest compatible processor type that is supported by the host.
`auto_add_certificate`	body	Boolean	Optional value. Whether to auto-accept or add the X.509 Certificate for the HMC (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is `True`.

{ "host": { 
   "registration": { 
     "host_name": "8246L2D_1234567",
     "hmc_uuids": ["34ab41180-..."],
     "host_type": "powervm", 
     "host_display_name": "My Host 1", 
     "registered_at": "2013-10-19T16:06:53Z",
     "host_proc_level_type": "POWER7"
  }
 }
}

View details of a managed compute host

This operation shows detailed information about one of the hosts that is managed by PowerVC. The API takes the host name in the URI as input and contains request body, and returns the IP address and credential information about the host in the response body. This API also returns a PowerVC specific parameter called registration in the response body.

Response codes

Normal response code: OK (200)
Error response code: Not Found (404), Server Error (500)

Response body

Table 4. Parameters in request and response for compute host registration
Name	Style	Type	Description
`host`	body	string	Internally generated name that is used to look up the host.
`host_name`	body	string	Internal name for the host that is returned from the `ibm-hmcs/hosts` API.
`hmc_uuids`	body	list of strings	List of UUIDs of the HMCs managing the host in the order of registration.
`primary_hmc_uuid`	body	string	Primary HMC UUID of the host.
`secondary_hmc_uuids`	body	list of strings	List of UUIDs of the secondary HMCs managing the host. Only one is supported for failover, based on the order of registration.
`host_type`	body	string	The type of the host that is being registered. Only `powervm` is supported.
`host_display_name`	body	string	Optional value. User-specified name to give to the host. The value defaults to the name on the HMC.
`registered_at`	body	string	The date and time when the host was registered in PowerVC.
`host_proc_level_type`	body	string	The latest compatible processor type that is supported by the host.
`access_state`	body	string	Shows the overall connectivity state to the VIOS and whether PowerVC can access it.

{
  "host": [{
    "resource": { "project": "(total)", "host": "host1", "cpu": 16,
     "memory_mb": 65536, "disk_gb": 279},
      "registration": {
      "host_display_name": "My_Host",
      "access_state": "ok",
      "vios_clusters": [],
      "host_type": "powervm",
      "primary_hmc_uuid": "30f23783-ed4d-...",
      "hmc_uuids": ["30f23783-ed4d-...", "29aba615-c036-..."],
      "registered_at": "2019-02-13T06:00:10Z",
      "manager_type": "hmc",
      "host_name": "824742L_212139A",
      "secondary_hmc_uuids": ["29aba615-c036-..."]
    }
  }]
}

Unregister or remove a managed compute host

This operation unregisters or removes a managed host so that it is no longer managed by PowerVC. This API takes the host name in the URI as input and does not take any request body and does not return any response body.

Update or edit a managed compute host

This operation updates or edits the registration information for a host that is managed by PowerVC. This API takes the host name in the URI and in the body the attributes that you want to change as input. The response body contains the attributes that are updated by the request.

Response codes

Normal response code: OK (200)
Error response code: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

Table 5. Parameters in the request for compute host registration
Name	Style	Type	Description
`arr_enabled`	body	string	Optional value. When utilizing remote restart, use this attribute to enable or disable automated remote restart for hosts. The default value is `True`.
`dro_enabled`	body	string	Optional value. Use this attribute to enable or disable DRO for hosts. The default value is `True`.
`hmc_uuids`	body	list of strings	List of UUIDs of the HMCs to manage the host. Only one is supported. When using Redundant HMCs to change which HMC is used by PowerVC to manage the given host, use this attribute to specify the UUID of the HMC you want to change to.
`host_display_name`	body	string	Optional value. User-specified name to give to the host. The value defaults to the name on the HMC.
`auto_add_certificate`	body	Boolean	Optional value. Whether to auto-accept or add the X.509 Certificate for the HMC (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is `True`.

{"registration": { 
   "hmc_uuids": ["34ab41180-..."],
   "host_display_name": "My Host 1"
 },
"dro_enabled":"true",
"arr_enabled":"true"
}

Response body

Table 6. Parameters in the response for compute host registration
Name	Style	Type	Description
`host`	body	string	Internally generated name that is used to look up the host.
`hmc_uuids`	body	list of strings	List of UUIDs of the HMCs to manage the host. Only one is supported.
`host_display_name`	body	string	Optional value. User-specified name to give to the host. The value defaults to the name on the HMC.
`auto_add_certificate`	body	Boolean	Optional value. Whether to auto-accept or add the X.509 Certificate for the HMC (if the fingerprint is not yet trusted or is different from the previously trusted fingerprint) or to fail with a 403 response code so that the certificate can be verified. Default value is `True`.

{"host": "8246L2D_1234567",
   "registration": { 
     "hmc_uuids": ["34ab41180-..."], 
     "host_display_name": "My Host 1"
 }
}

List existing virtual machines

The operation lists all the virtual machines that exist on the host independent of whether PowerVC is managing them. This API takes the name of the host in the URI as input and takes no request body. The API returns the list of virtual machines on the host in the response body. The list includes the names, status, whether the virtual machines are currently managed by PowerVC, and whether the virtual machines are supported to be managed by PowerVC.

Response codes

Normal response code: OK (200)
Error Response Codes: Not Found (404), Server Error (500)

Response body

Table 7. Parameters in the response for viewing existing virtual machines
Name	Style	Type	Description
`id`	body	string	Internally generated identifier that is used to look up the task results of the manage action.
`name`	body	string	Name the storage provider.

Example:

{"servers": [ 
 {"id": "2c6da352-...", 
  "name": "My Volume 1",
  "status": "active",
  "managed": False,
  "support": { "status": "supported" } 
 },
 {"id": "1b87d2dc-...", 
  "support": { "status": "not_supported", "reasons": [ "A reason", 
    "Another reason" ] } ....

Managing existing virtual machines

The operation asks PowerVC to start managing specific virtual machines that exist on the host. This API takes the name of the host in the URI and the list of UUIDs of the virtual machines in the body as input. The API then returns the URI of the task that can be used to look up results for the asynchronous operation in the response body.

Note: The special keyword *all can be used instead of the UUID to specify that all virtual machines should be managed.

Response codes

Normal response code: OK (200)
Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

Table 8. Parameters in the request for managing existing virtual machines
Name	Style	Type	Description
`servers`	body	list of strings	Each string contains data about a virtual machine to manage or prepare for management.

Example:

{"servers": [ "2c6da352-...", "1b87d2dc-..."] }

Unmanage virtual machines

The operation asks PowerVC to stop managing specific virtual machines that exist on the host. This API takes the name of the host in the URI and the list of UUIDs of the virtual machines in the body as input and removes the virtual machines from the PowerVC database. The API does not return any response body, if successful.

Note: The special keyword *all can be used instead of the UUID to specify that all virtual machines should be unmanaged.

Response codes

Normal response code: No Content (204)
Error Response Codes: Bad Request (400), Not Found (404), Server Error (500)

Request parameters

{"servers": [ "2c6da352-...", "1b87d2dc-..."] }

Recall virtual machines

The operation asks PowerVC to recall virtual machines, which were moved from the host during host maintenance mode or automated remote restart, to the host.

Response codes

Normal response code: No Content (204)
Error Response Codes: Bad Request (400), Not Found (404), Too many requests(429), Pre-condition failed (412), Server Error (500)