Reservation host APIs

Edit online

Reservation host APIs enable reservation of hypervisor host operations.

Adding hosts to the default reservation group

This operation adds hosts to the reservation host group so users can select the required hosts for dedicated host reservations. You can add a host to the default reservation group in two instances.
  • At the time of registration.
  • When changing the host group post registration.

Adding hosts at the time of registration

The table lists API options for adding hosts at the time of registration.
Table 1. API options for adding a host at the time of registration
Method URI Description
POST https://<<powervc_ip/hostname>>:8774/v2.1/{tenant_id}/os-hosts Compute API that is used to add hypervisor to the reservation host group.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Bad Request (400), Server Error (500)
Response parameters
Table 2. Parameters in the request for adding a host to reservation host group in Blazar
Name Style Type Description
access_ip body string IP address of the NovaLink host.
user_id body string User ID that is configured for the NovaLink host.
host_type body string Specifies the type of the hypervisor, which is generally “powervm”.
asynchronous body string Specifies if the registration configuration must be handled as a separate thread. The default value is "True".
host_display_name body string Displays the name of the host that must be configured for the host.
password body string Password to connect to the NovaLink host.
force_unmanage body string Specifies where to unmanage the host from a previous PowerVC before adding it to the current PowerVC.
auto_add_host_key body string Verifies the host key before adding the host toPowerVC.
force_switch body string Verifies if the host is managed by HMC or NovaLink.
host_group body string Specifies the host group to which the host must be added post registration. This is an optional parameter.

Example of request body

                      { 
    "host": { 
        "registration": { 
            "access_ip": "<IP>", 
            "user_id": "<USER_ID>", 
            "host_type": "powervm", 
            "asynchronous": "True", 
            "host_display_name": "<NAME>", 
            "password": "<PASSWORD>", 
            "force_unmanage": "False", 
            "auto_add_host_key": "True", 
            "force_switch": "False", 
            "host_group": "Default Reservation Group" [optional]
        } 
    } 
}

For detailed response body examples, see the Compute API section.

Adding hosts to the default reservation group post registration

The table lists API options for adding hosts to the default reservation group post registration.

Table 3. API options for adding hosts to the default reservation group post registration
Method URI Description
POST https://<<powervc_ip/hostname>>:9450/v1/os-hosts Adds hosts to the default reservation group post registration.
Response codes
  • Normal response code: OK (201)
  • Error response codes: Bad Request (400), Forbidden (403), Not Found (404), Unauthorized (401), Conflict (409)

Request parameters

Table 4. Parameters in the request for adding hosts to the Default Reservation Group post registration
Name Style Type Description
hypervisor_hostname body string Specifies the hypervisor machine type machine serial (MTMS) name that must be added to the Blazar reservation host group.
Request body example
{
  "hypervisor_hostname": "<HOST_MTMS_NAME>"
}

Retrieving the list of all hypervisor hosts from the reservation group

This API fetches the list of all hypervisor hosts (reservation candidates) from the default reservation host group that are not yet reserved and are available for reservation. This API does not take any request body. If the conf option to return the host that is in standby mode is enabled as a reservation candidate by the Ops team, then the response includes host details as well.

Table 5. API options to retrieve the list of all hypervisor hosts from the reservation group
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/os-hosts Retrieves the list of all hypervisor hosts from the reservation host group.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Retrieving the detailed view of all hypervisor hosts from the reservation host list

This operation fetches a detailed list of attributes that are related to hypervisors from the reservation host group that are not yet reserved. This API does not take any request body.

Table 6. API options for retrieving the detailed view of all hypervisor hosts from the reservation host list
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/os-hosts/<HYPERVISOR_ID(or)MTMS/ID/UUID> Provides a detailed view of all attributes that are associated with a host in the reservation host group.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Updating user_hostname for hypervisor in the reservation host group

This operation updates the user_hostname for the hypervisor in the reservation host group. This API takes the user_hostname in the request body and returns the updated hypervisor details from the reservation host group.

Table 7. API options for updating user_hostname for hypervisor in the reservation host group
Method URI Description
PUT https://<<powervc_ip/hostname>>:9450/v1/os-hosts/<HYPERVISOR_ID> Updates the user_hostname for the hypervisor.
Response codes
  • Normal response code: OK (201)
  • Error response codes: Bad Request (400), Forbidden (403), Not Found (404), Unauthorized (401), Conflict (409)
Table 8. Parameters in the request for updating user_hostname for hypervisor in the reservation host group
Name Style Type Description
user_hostname body string Specifies the user_hostname that must be updated for the hypervisor.
Request body example
{
  "user_hostname": "<USER_SPECIFIED_NAME>"
}

Removing hypervisor from the reservation host group

The operation removes the hypervisor host from the reservation host group. This API neither takes a request body nor returns a response body.

Table 9. API options for removing hypervisor from the reservation host group
Method URI Description
DELETE https://<<powervc_ip/hostname>>:9450/v1/os-hosts/<HYPERVISOR_ID> Removes the host from the reservation host group.
Response codes
  • Normal response code: No Content (204)
  • Error response codes: Unauthorized (401), Not Found (404), Forbidden (403)

Host reservation APIs

The host reservation APIs are associated with the CRUD operations on reservation of hypervisor host.

Host reservation API options

Table 10. Host reservation API options
Method URI Description
POST :9450/v1/leases Creates the lease.
GET :9450/v1/leases Retrieves the list of all leases.
GET :9450/v1/leases/{lease_id} Retrieves specific lease details.
PUT :9450/v1/leases/{lease_id} Updates the lease name and expiration_date.
GET :9450/v1/reservations Retrieves the list of all reservations.
GET :9450/v1/reservations?resource_type=host Retrieves the list of all host reservations.
GET :9450/v1/reservations/{reservation_id} Retrieves specific reservation details.
PUT :9450/v1/reservations/{reservation_id} Adds or removes hosts to or from the reservation.
DELETE :9450/v1/leases/{lease_id} Deletes the lease.

Creating a lease with reservation of reservation hosts

This operation creates a lease with reservation of the dedicated hosts.

Table 11. API options for creating a lease with reservation of the dedicated hosts
Method URL Description
POST https://<<powervc_ip/hostname>>:9450/v1/leases Creates the lease.
Response codes
  • Normal response code: OK (201)
  • Error response codes: Bad Request (400), Unauthorized (401), Forbidden (403), Conflict (409), Internal Server Error (500)

Request parameters

The table lists the parameters in the request for create reservation.

Table 12. Parameters in the request body for create reservation
Name Style Type Description

name

body

string

The name of the lease.
reservations body array

A list of reservation objects.
resource_type

body

string

 For dedicated host reservation, this parameter must be"physical:host"
hosts body array Specifies the list of host machine type machine serial (MTMS) name to be reserved as part of this lease request. Optionally, user_hostname can also be mentioned to set the display_name for the host.
Request body example 1
{
    "name": "Test_Lease",
    "reservations":
    [
        {
            "resource_type": "physical:host",
            "hosts":
            [
                {
                "host":"828642A_21C1B7V", 
                "user_hostname": "P10_B7V" 
                }
             ]
        }
    ]
}
Request body example 2
{
    "name": "Test_Lease",
    "reservations":
    [
       {
         "resource_type": "physical:host",
          "hosts":
          [
            { "user_display_name": "<<host_display_name>>",(optional)
               "host": "828642A_21C1B7V" 
            }, 
            { "user_display_name": "<<host_display_name>>", 
              "host": "828642A_21C1B5V"
            }
           ]
        }
    ]
}

Retrieving the list of all leases

This operation fetches a list of all leases that is created within the user context project. This API does not take any request body. The response body contains details of leases.

Table 13. API options for retrieving the list of all leases
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/leases Retrieves the list of all leases.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Retrieving specific lease details

This operation fetches specific lease details created within the user context project. This API does not take any request body. The response body contains details of lease.

Table 14. API options for retrieving specific lease details
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/leases/<LEASE_ID> Retrieves specific lease details.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Retrieving the list of all reservations

This operation fetches a list of all reservations created within the user context project. This API does not take any request body. The response body contains all reservation details. This API can be used to fetch the reservation host groups associated with the particular user. This API also returns the list of host(s) that are part of the reservation host group.

Table 15. API options for retrieving the list of all reservations
Method URI Description
GET /<HYPERVISOR_ID(or)MTMS> Fetches the details about the host(s) resource.
GET https://<<powervc_ip/hostname>>:8774/v2.1/<PROJECT_ID>/shared-proc-pools?host=<HOST_MTMS> Fetches the details about the SPPs associated with a host.
GET https://<<powervc_ip/hostname>>:9450/v1/reservations Retrieves the list of all reservations.
GET https://<<powervc_ip/hostname>>:9450/v1/reservations?resource_type=physical:host Retrieves the list of all dedicated host related reservations.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Retrieving specific reservation details

This operation fetches a specific reservation detail that is created within user context project. This API does not take any request body. The response body contains reservation details.

Table 16. API options for retrieving specific reservation details
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/reservations/<UUID> Retrieves specific reservation details.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)

Updating the lease

This operation allows the user to update the name and expiration of lease.

Table 17. API options for updating the lease
Method URI Description
PUT https://<<powervc_ip/hostname>>:9450/v1/leases/<LEASE_ID> Updates the lease.
Response codes
  • Normal response code: Accepted (200)
  • Error response codes: Bad Request (400), Unauthorized (401), Forbidden (403), Conflict (409), Internal Server Error (500)
Table 18. Parameters in the request for updating the lease
Name Style Type Description
name body string The name of the lease.
end_date body string The lease expiration date, which is only for the Ops team.
Request body example
{
    "name": "New_Lease",
    "end_date": "2023-11-25 12:00
}

Adding or removing the host to or from the reservation

This operation allows users to add or remove specific host to or from reservation created within the user context project. The response body contains the reservation details.

Table 19. API options for adding or removing the host to or from reservation
Method URI Description
PUT https://<<powervc_ip/hostname>>:9450/v1/reservations/ <reservation_id> Adding or removing the host to or from reservation.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Unauthorized (401), Forbidden (403)
Table 20. Parameters in the request for updating the lease
Name Style Type Description
add_hosts body array The list of hypervisor host names that must be added to an existing reservation. Optionally, you can also specify the user_hostname.
remove_hosts body array The list of hypervisor host names that must be removed from a reservation.
Request body example to add hosts to an existing reservation
{
    "add_hosts":
    [
        {
         "host": "824742L_2120FEA",
         "user_hostname": "P10-FEA"
        }
    ]
}
Request body example to remove hosts from an existing reservation
{
    "remove_hosts":
    [
        "824742L_2120FEA"
    ]
}
Note:
  • Hosts will be deleted from the reservation only if there are no virtual machines (VMs) that are deployed on the host. VMs, if any must be deleted or cleaned up. If you want to retain the VMs, make sure that you work with the Support team to migrate the VMs based on the business need, and then retry the operation.
  • After the host is removed from the current reservation, the host moves back to the default reservation group.
  • Only an admin user of the project can add or remove hosts from a dedicated host group.

Deleting a lease

The operation removes a hypervisor host from the list of reservation host list. This API neither takes a request body nor returns a response body.

Table 21. API options for deleting a lease
Method URI Description
DELETE https://<<powervc_ip/hostname>>:9450/v1/leases/ <lease_id> Deletes a lease.
Deleting the lease can be initiated in two instances.
  • Delete the entire lease or reservation.
  • Delete the reservation but keep the VMs intact.
Request body example
{
  "task_id": "d319d674-a567-48c7-ac38-19adaee2a3d5"
}

The response body contains a task id that is associated with the delete lease call.

To obtain the status of the delete request status, you can use a GET call by using the task id.

Table 22. API options to obtain the status of the delete request by using the GET method
Method URI Description
GET https://<<powervc_ip/hostname>>:9450/v1/leases/ progress?task_id=d319d674-a567-48c7-ac38-19adaee2a3d5 Fetches the status of the delete request status by using the task id.

Deploying VMs to the reservation host group

This operation deploys VMs to the dedicated host group.

Table 23. API options for deploying VMs to the dedicated host group
Method URI Description
POST https://<<powervc_ip/hostname>>:8774/v2.1/{tenant_id}/servers Creates servers.
Response codes
  • Normal response code: Accepted (202)
  • Error response codes: Bad Request (400), Forbidden (403), Not Found (404), Unauthorized (401), Conflict (409), Item Not Found (404)
Request body example (untargeted deploy)

 {   
  "server": { 
        "name": "Test", 
        "description": "", 
        "imageRef": "a2c5782b-2c5a-42b0-a780-d41ecf8010c2", 
        "availability_zone": "8a209e43-56bb-4676-9450-dc4c214426c1", 
        "block_device_mapping_v2": [], 
        "flavor": { 
            "ram": 4096, 
            "vcpus": 1, 
            "disk": 30, 
            "extra_specs": { 
                "powervm:availability_priority": "127", 
                "powervm:dedicated_proc": "false", 
                "powervm:max_mem": "6144", 
                "powervm:max_proc_units": "1", 
                "powervm:max_vcpu": "1", 
                "powervm:min_mem": "2048", 
                "powervm:min_proc_units": "0.1", 
                "powervm:min_vcpu": "1", 
                "powervm:proc_units": "0.5", 
                "powervm:shared_weight": "128", 
                "powervm:uncapped": "true", 
                "powervm:storage_connectivity_group":
                    "5b31ea7b-fd5f-4ff7-8e02-33d06a8b02ed" 
            } 
        }, 
        "max_count": 1, 
        "config_drive": true, 
        "networks": [ 
            { 
                "uuid": "125c04b7-0cea-45aa-b208-6cc29bde0601" 
            } 
        ], 
        "metadata": { 
            "primary_network": "125c04b7-0cea-45aa-b208-6cc29bde0601" 
        } 
    }, 
    "os:scheduler_hints": { 
        "group": "17e31978-f78d-4be1-b0f3-96d3643a3b1d",
        "reservation": "8a209e43-56bb-4676-9450-dc4c214426c1" 
    } 
}
Note: The existing “availability_zone” attribute contains the value of the reservation id, which must be specified.

Sharing reservations with a secondary project

This operation creates a new lease in the secondary project by mapping the reservation from the parent project.

Table 24. API options for sharing reservations with a secondary project
Method URI Description
POST https://<<powervc_ip/hostname>>:9450/v1/leases/<parent_lease_id>/action Creates a lease.
Response codes
  • Normal response code: OK (201)
  • Error response codes: Bad Request (400), Unauthorized (401), Forbidden (403), Conflict (409), Internal Server Error (500)
Table 25. Parameters in the request for creating a lease
Name Style Type Description
name body string The name of the lease. If the name of the lease is not provided, the shared lease uses the name of primary lease. This is an optional parameter.
project_id body array Specifies the UUID of project with whom the lease can be shared with. This is a mandatory parameter.
reservation_ids body array List of reservation_ids that can be shared with the project for partial sharing of reservation. This is an optional parameter.
Request body example
{
    "share":
    [
        {
            "name": "my_share_lease_1”,
            "project_id": "4b9c3a64df7944338d46cda09164a902",
            
        },
        {
            "name": "my_share_lease_2”,
            "project_id": "67afe757c3041e292b82058579f6d8f",
            
        }
    ],
}

Retrieving the list of all shared leases for a specific lease from the primary project

This operation returns the list of leases shared with other projects for a specific lease.

Table 26. API options for retrieving the list of all shared leases for a specific lease
Method URI Description
GET /v1/leases/{lease_id} Retrieves lease details and shared leases for specific lease. The response property containsShared = true/falsevalue.
GET /v1/leases/{lease_id}?include_shared=true Lists a detailed view of the shared lease with the lease_id.
GET /v1/leases?shared=true Returns all the shared leases.
Response codes
  • Normal response code: OK (200)
  • Error response codes: Bad Request (400), Unauthorized (401)
Request body example
GET  https://<powervc_ip>:9450/v1/leases/75de2b9b-8ccb-472b-
b450-311de53f2e73?include_shared=true

GET  https://<powervc_ip>:9450/v1/leases?shared=true

After the lease is shared with the secondary project, the secondary project cannot share the shared lease with another project, and the sharing fails.

Request body example for sharing a lease with the Internal Server Error (500) error code
{
    "error_code": 500,
    "error_message": "The requested lease cannot be shared.",
    "error_name": 500
}

Removing or unsharing the shared lease

This operation removes the lease that is shared with other projects.

Table 27. API options for removing or unsharing the shared lease
Method URI Description
POST https://<<powervc_ip/hostname>>:9450/v1/leases/<lease_id>/action Deletes the shared lease.
Response codes
  • Normal response code: Accepted (202)
  • Error response codes: Bad Request (400), Unauthorized (401), Forbidden (403), Conflict (409), Internal Server Error (500)
Table 28. Parameters in the request for removing or unsharing the shared lease
Name Style Type Description
project_id body array Specifies the UUID of the project with whom the lease can be shared with.
force body string Specifies whether to unshare a lease forcefully. This is an optional parameter.
Request body example
{
   "unshare":
   {
     "project_id": "a53746a4632140ccb9607359ae776c50",
     "force": "true",
   }
}

Planned and unplanned maintenance in a dedicated host group

A new maintenance_host_in_reservation_host_group flag is added in the response of the GET os-hypervisor call.

For the newly added host, project admins can set the maintenance_host_in_reservation_host_group flag in ibm_compute_node_metadata as False by using this API.

Table 29. API options for setting the maintenance_host_in_reservation_host_group flag
Method URI Description
POST https://<<powervc_ip/hostname>>:8774/v2.1/{tenant_id}/os-hosts/{host-mtms}/update-registration An existing nova API that is used to update host registration in PowerVC.
Example of request body
{"maintenance_host_in_reservation_host_group": "false"}