Compute host registration

Compute host registration API options

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. Starting PowerVC 2.2.0, you can registers or add a host directly into the standby mode.

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_standby	body	Boolean	If True after host registration is complete, the host is placed into standby mode. Default value is False.

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

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_standby	body	Boolean	If True after host registration is complete, the host is placed into standby mode. Default value is False.

{ "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"
     "host_standby": False
  }
 }
}

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-..."]
      "host_standby": False
    }
  }]
}

Note: After registration is complete, the host will be in standby mode. If an error occurs when placing the host in standby mode, the host is added as a normal host. In such cases, you can manually place the host in standby mode from the Host lists page in the user interface.

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.

You can use the force option when a host is unreachable or is not in working condition, but is managed in PowerVC.

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

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

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)