Compute host registration

The compute host registration APIs provide the capability to specify hosts that must be managed by IBM® Cloud Infrastructure Center. These capabilities include adding hosts, removing hosts, and retrieving the information of the hosts that are currently managed.

Compute host registration API options

Table 1. Options for compute host registration API

Method URI Description
POST /v2.1/{project_id}/os-hosts Register or add a new compute host.
GET /v2.1/{project_id}/os-hosts/{host_name} Show the details of a managed compute host.
DELETE /v2.1/{project_id}/os-hosts/{host_name} Unregister or remove a managed compute host.

Register or add a compute host

In this operation, a host is registered or added into the list that is managed by IBM Cloud Infrastructure Center. This API takes the IP address and credentials for the compute host in the request body as input, and registers the host with IBM Cloud Infrastructure Center.

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
access_ip body string Internal DNS name or raw IP address that is used to connect to the host.
host_name body string Optional value. Internal name for the host that is returned from the command hostname.
user_id body string The username that is used to authenticate by SSH.
password body string The password that is used to authenticate by SSH.
host_type body string The type of the host that is being registered. The value can be 'zvm' for the host of z/VM or 'kvm' for the host of KVM on IBM Z.
asynchronous body Boolean Optional value. If true, the api returns after some basic checking and the adding process continues to run in background. If false, api returns when all operation done. Default value is false.
host_display_name body string Optional value. User-specified name to give to the host. Value must be unique for all compute nodes. The value defaults to the hostname of the compute host.
physical_network_mappings (z/VM only) body string The format of value is physical network:physical vswitch. For example, "icicvlan1:icicvsw1". Physical network is the logical provider network name, it must be same as the one configured in /opt/ibm/icic/config.properties on management node. More details at Set up the configuration file. And the physical vswitch is the real network vswitch you plan to use on the compute node. More details at Setting up z/VM® VSWITCH
auto_add_host_key body Boolean Optional value. Whether to auto-accept or add the SSH key fingerprint for the compute host. If the fingerprint is not yet trusted or is different from the previously trusted fingerprint, the key should be accepted or added before establishing the SSH connection. If the value is false and the key is in untrusted status, the operation fails with a 403 response code. Default value is true.
fcp_list (z/VM only) body string The string contains a list of the FCP devices. The string is divided into multiple paths by semicolons. Within each path, multiple ranges of the FCP devices are separated by commas. For example, a string contains the FCP devices that are divided into two paths: 5C01,5C06-5C0F;5D06-5D0F,5D12. If you specify some FCP devices as the value, a default FCP multipath template is created for the z/VM host. After adding the host, you can also create more FCP multipath templates if needed.
disk_pool (z/VM only) body string This value is required if you want to use z/VM dasd group as the root or data disks for the virtual machines. It has 2 parts separated by a colon(:). The first part is the type of disks in the dasd group. The disks in one dasd group must in the same type (ECKD or FBA). Possible values of the dasd group type is either ECKD or FBA. The second part is the volume group name defined in your directory manager on your z/VM® system, that is used for allocating disks for the new guest. Sample disk_pool values: ECKD:diskpo1 or FBA:testpool.
nic_name (KVM only) body string Network interface on the host that can be assigned to Open vSwitch bridge, e.g. eth0.
shared_storage_path (KVM only) body string Optional value. The value is a local path on the host that mounts to a remote share storage (such as IBM Storage Scale/NFS storage). If the path isn't mounted to a storage server, the local storage of the host will be used for the virtual machine. Refer to Planning share storge for more details.
secure_execution (KVM only) body Boolean Optional value. If true, as for the host which enables the IBM SE(Secure Execution) capability for Linux, the host is managed as one real SE host by the IBM® Cloud Infrastructure Center. You can deploy both of IBM SE guest and non-SE guest on it. Although, for the host which does not enable the IBM SE feature for Linux, adding host fails for The secure execution is not enabled on the host ***. Ensure it is enabled if you want to use this capability. If false, regardless of the host enables the IBM SE feature or not, the host is managed as one non-SE host and you can only deploy non-SE guest on it. The default value is false.
ovn_encap_ip (KVM only) body string Optional value. The IP address on compute node to be set as overlay Geneve network local endpoint IP address. If not specified, the IBM Cloud Infrastructure Center uses the value of access_ip(if the access_ip input is in hostname format, transfer it to IP address) to set to ovn_encap_ip. For more information, refer to OVN Encapsulation IP.

z/VM Example:

{
  "host": {
    "registration": {
      "access_ip": "1.2.3.4",
      "host_type": "zvm",
      "fcp_list": "",
      "disk_pool": "ECKD:diskpo1",
      "user_id": "deployer",
      "asynchronous": true,
      "password": "********",
      "physical_network_mappings": "icicvlan1:vswitch_name",
      "auto_add_host_key": true
    }
  }
}

KVM Example:

{
	"host": {
		"registration": {
			"access_ip": "xxxx.xxxx.xxx.xxx",
			"user_id": "test",
			"host_type": "kvm",
			"asynchronous": true,
			"nic_name": "enc1080",
                        "secure_execution": true,
			"host_display_name": "95555",
			"password": "passw0rd",
			"auto_add_host_key": false,
			"shared_storage_path": "/mnt/remote_nfs",
			"ovn_encap_ip": "1.2.3.4"
		}
	}
}

Response body

Table 3. Parameters in the response for compute host registration

Name Style Type Description
access_ip body string Internal DNS name or Raw IP address that is used to connect to the host.
host_name body string Internal name for the host that is returned from the command "hostname".
user_id body string The username that is used to authenticate by SSH.
passwd body string The password that is used to authenticate by SSH.
host_type body string The type of the host that is being registered. The value is 'powervm' for the host of z/VM or 'kvm' for the host of KVM on IBM Z.
asynchronous body Boolean If true, the api returns after some basic checking and the adding process continues to run in background. If false, api returns when all operation done. Default value is false.
host_display_name body string User-specified name to give to the host. The value defaults to the hostname of the compute host.
zvm_hyp_hostname (z/VM only) body string The hypervisor hostname of the z/VM host.
fcp_list (z/VM only) body string The string contains a list of the FCP devices. The string is divided into multiple paths by semicolons. Within each path, multiple ranges of the FCP devices are separated by commas. For example, a string contains the FCP devices that are divided into two paths: 5C01,5C06-5C0F;5D06-5D0F,5D12. If you specify some FCP devices as the value, an default FCP multipath template is created for the z/VM host. After adding the host, you can also create more FCP multipath templates if needed.
disk_pool (z/VM only) body string A z/VM DIRMAINT dasd group with the format ECKD:diskpo1 or FBA:testpool that is used for the root or the data disks for the virtual machines.
host_display_name body string The hostname of the z/VM on which the host runs.
physical_network_mappings (z/VM only) body string The format of value is physical network:physical vswitch. For example, "icicvlan1:icicvsw1". Physical network is the logical provider network name, the one configured in /opt/ibm/icic/config.properties on management node. And the physical vswitch is the real network vswitch you use on the compute node.
auto_add_host_key body Boolean Whether to auto-accept or add the SSH key fingerprint for the compute host. If the fingerprint is not yet trusted or is different from the previously trusted fingerprint, the key should be accepted or added before establishing the SSH connection. If the value is false and the key is in untrusted status, the operation fails with a 403 response code. Default value is true.
nic_name (KVM only) body string Network Interface on the host that can be assigned to Open vSwitch bridge, e.g. enc1.
shared_storage_path (KVM only) body string The value is a local path on the host that mounts to a remote share storage (such as IBM Storage Scale/NFS storage).
secure_execution (KVM only) body Boolean If true, as for the host which enables the IBM SE capability for Linux, the host is managed as one real SE host by the IBM® Cloud Infrastructure Center. You can deploy both of IBM SE guest and non-SE guest on it, as for the host which does not enable the IBM SE feature for Linux, adding host fails for The secure execution is not enabled on the host. Ensure it is enabled if you want to use this capability. If false, regardless of the host enables the IBM SE feature or not, the host is managed as one non-SE host and you can only deploy non-SE guest on it. The default value is false.
ovn_encap_ip (KVM only) body string The IP address on compute node to be set as overlay Geneve network local endpoint IP address.

z/VM Example:

{
  "host": {
    "registration": {
      "passwd": "********",
      "asynchronous": true,
      "auto_add_host_key": true,
      "host_display_name": "host001.ibm.com",
      "access_ip": "1.2.3.4",
      "host_type": "powervm", # the host_type of `powervm` actually means the host_type of `zvm`
      "user_id": "root",
      "zvm_hyp_hostname": "ZVM001",
      "fcp_list": "",
      "disk_pool": "ECKD:diskpo1",
      "physical_network_mappings": "icicvlan1:vswitch_name",
      "ip": "1.2.3.4",
      "user": "root",
      "host_name": "host001"
    }
  }
}

KVM Example:

{
	"host": {
		"registration": {
			"access_ip": "xxxx.xxxx.xxx.xxx",
			"user_id": "test",
			"host_type": "kvm",
			"asynchronous": true,
			"nic_name": "enc1080",
                        "secure_execution": true,
			"host_display_name": "174",
			"auto_add_host_key": false,
			"shared_storage_path": "/mnt/remote_nfs",
			"host_name": "174",
			"ovn_encap_ip": "1.2.3.4"
		}
	}
}

Show the details of a managed compute host

This operation shows the detailed information of the host that is managed by IBM Cloud Infrastructure Center. The API takes the hostname 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 IBM Cloud Infrastructure Center specific parameter that is 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 command hostname.
host_type body string The type of the host that is being registered.
host_display_name body string Optional value. User-specified name to give to the host. The value defaults to the hostname of the compute host.
physical_network_mappings (z/VM only) body string The format of value is physical network:physical vswitch. For example, "icicvlan1:icicvsw1". Physical network is the logical provider network name, the one configured in /opt/ibm/icic/config.properties on management node. And the physical vswitch is the real network vswitch you use on the compute node.
registered_at body string The date and time when the host was registered in IBM Cloud Infrastructure Center.
access_state body string Shows the overall connectivity state to the host.
access_ip body string Internal DNS name or raw IP address that is used to connect to the host.
user_id body string The username that is used to authenticate by SSH.
fcp_list (z/VM only) body string The string contains a list of the FCP devices. The string is divided into multiple paths by semicolons. Within each path, multiple ranges of the FCP devices are separated by commas. For example, a string contains the FCP devices that are divided into two paths: 5C01,5C06-5C0F;5D06-5D0F,5D12. If you specify some FCP devices as the value, an default FCP multipath template is created for the z/VM host. After adding the host, you can also create more FCP multipath templates if needed.
disk_pool (z/VM only) body string A z/VM® DIRMAINT dasd group with the format ECKD:diskpo1 or FBA:testpool that is used for the root or the data disks for the virtual machines.
zvm_hyp_hostname body string The hostname of the z/VM on which the host runs.
unique_id body string The unique ID identifies the host as a label.
nic_name (KVM only) body string Network interface on the host that can be assigned to Open vSwitch bridge, e.g. enc1.
shared_storage_path (KVM only) body string The value is a local path on the host that mounts to a remote share storage (such as IBM Storage Scale/NFS storage).
secure_execution (KVM only) body Boolean The value true is used to enable the IBM SE for Linux in the host to deploy IBM SE guest.
ovn_encap_ip (KVM only) body string The IP address on compute node to be set as overlay Geneve network local endpoint IP address.

z/VM Example:

{
        "hypervisors": [{
		"id": 1,
		"hypervisor_hostname": "ZVM001",
		"state": "up",
		"status": "enabled",
		"vcpus": 12,
		"memory_mb": 524288,
		"local_gb": 1156,
		"vcpus_used": 0,
		"memory_mb_used": 0,
		"local_gb_used": 0,
		"hypervisor_type": "zvm",
		"hypervisor_version": 710,
		"free_ram_mb": 524288,
		"free_disk_gb": 1156,
		"current_workload": 0,
		"running_vms": 0,
		"disk_available_least": 255,
		"host_ip": "1.2.3.4",
		"service": {
			"id": 1,
			"host": "ZVM001",
			"disabled_reason": null,
			"host_display_name": "host001.ibm.com",
			"access_ip": "1.2.3.4",
			"host_type": "powervm", # the host_type of `powervm` actually means the host_type of `zvm`
			"manager_type": "pvm",
			"vios_clusters": [],
			"host_intention": "deploy",
			"physical_network_mappings": "icicvlan1:vswitch_name",
			"disk_pool": "ECKD:diskpol",
			"host_storage_type": "SAN"
		},
		"cpu_info": "{\"architecture\": \"s390x\", \"cec_model\": \"2964\"}",
		"cpu_allocation_ratio": 16.0,
		"ram_allocation_ratio": 3.0,
		"disk_allocation_ratio": 1.0,
		"proc_units_reserved": null,
		"proc_units_used": null,
		"proc_units": null,
		"disk_available": null,
		"disk_total": null,
		"disk_used": null,
		"usable_local_mb": null,
		"cpu_utilization": null,
		"memory_utilization": null,
		"vnic_capable": 0,
		"maintenance_status": "ok",
		"maintenance_migrate_action": "-",
		"ha_status": "ok",
		"dro_enabled": 1,
		"arr_enabled": 1,
		"cod_enabled": 0,
		"health_status": {
			"id": "1",
			"health_value": "OK",
			"updated_at": "2022-02-09T05:14:46.028901",
			"value_reason": []
		},
		"dro_violated": 0,
		"dro_consecutive_alert_times": 0,
		"hypervisor_state": "operating",
		"latest_mgmt_version": null,
		"current_mgmt_version": "1.1.5.0",
		"memory_allocation_ratio": 3.0,
		"host_in_SSI": "No",
		"id_SSI": ""
	}]
}

KVM Example:

{
	"publisher_id": "icic-health",
	"event_type": "icic-health.INFO.Compute.Hypervisor.Health",
	"indication_type": "ALERT",
	"priority": "INFO",
	"resource_type": "Hypervisor",
	"resource_id": 1,
	"health": {
		"id": 1,
		"health_value": "OK",
		"updated_at": "2020-09-17T06:15:43.397486",
		"value_reason": ""
	},
	"message": "hypervisor health status msg",
	"timestamp": "2020-09-17 06:15:43.397590",
	"hypervisor": {
		"id": 1,
		"hypervisor_hostname": "xxxx",
		"state": "up",
		"status": "enabled",
		"vcpus": 4,
		"memory_mb": 15915,
		"local_gb": 36,
		"vcpus_used": 0,
		"memory_mb_used": 0,
		"local_gb_used": 0,
		"hypervisor_type": "QEMU",
		"hypervisor_version": 2012000,
		"free_ram_mb": 15915,
		"free_disk_gb": 36,
		"current_workload": 0,
		"running_vms": 0,
		"disk_available_least": 25,
		"host_ip": "192.168.1.1",
		"service": {
			"id": 5,
			"host": "174",
			"disabled_reason": null,
			"host_display_name": "174",
			"access_ip": "xxxx.xxxx.xxx.xxx",
			"host_type": "kvm",
			"vios_clusters": [],
			"nic_name": "enc1080",
			"shared_storage_path": "/mnt/remote_nfs",
			"secure_execution": "True",
			"ovn_encap_ip": "1.2.3.4",
			"host_storage_type": "SAN"
		},
		"cpu_info": "{\"arch\": \"s390x\", \"model\": null, \"vendor\": null, \"topology\": {\"cells\": 1, \"sockets\": 1, \"cores\": 4, \"threads\": 1}, \"features\": []}",
		"health_status": {
			"id": "1",
			"health_value": "OK",
			"updated_at": "2020-09-17T06:15:43.458185",
			"value_reason": []
		},
		"dro_violated": 0,
		"dro_consecutive_alert_times": 0,
		"hypervisor_state": "operating",
		"latest_mgmt_version": null,
		"current_mgmt_version": "1.1.3.0",
		"cpu_allocation_ratio": 10.0,
		"memory_allocation_ratio": 2.0,
		"disk_allocation_ratio": 1.0
	}
}

Unregister or remove a managed compute host

This operation unregisters or removes a managed host so that is expected to be no longer managed by the IBM Cloud Infrastructure. This API takes the hostname in the URI as input and does not take any request body and does not return any response body.