PUT /hostPlatforms

Use this method to deploy operating-system images to specific host platforms as a job (batch mode). You can specify configuration information such as network settings, license, user ID and password, and storage settings.

Important

When deploying an operating system on a Fibre Channel or iSCSI SAN target, you must call PUT /osdeployment/hostSettings to set the target before calling PUT /hostPlatforms to start the deployment.

Note

If you deploy a Microsoft Windows image, you can also specify Active Directory settings required to join an Active Directory domain after the image is installed.

Authentication

Authentication is required.

Request URL

PUT https://{management_server_IP}/hostPlatforms

Query parameters

None

Request body

Attributes		Required / Optional	Type	Description
adusername		Optional	String	(Windows only) User name for the Active Directory domain that is specified in the windowsDomain attribute Note This attribute is required if you want a Windows operating system to join an Active Directory domain.
adpassword		Optional	String	(Windows only) Password for the Active Directory user name Note This attribute is required if you want a Windows operating system to join an Active Directory domain.
configFileId		Required if selectedImage includes a custom configuration-settings file; otherwise ignored.	String	ID of the custom configuration-settings file to use for this OS deployment
licenseKey		Optional	String	License key to be used for Microsoft Windows or VMware ESXi. If you do not have a license key, you can set this attribute to null.
osCredentials		Optional	Object	OS credentials for the operating system
	name	Required	String	User name for the target operating system. This could be the following values. root. For Linux or ESXi
	password	Required	String	Hashed password for the target operating system
networkSettings		Required	Object	Information about network settings
	dns1	Optional	String	Preferred DNS server for the host server to be used after the operating system is deployed
	dns2	Optional	String	Alternative DNS server for the host server to be used after the operating system is deployed
	gateway	Required if using static IP addresses. Optional if using DHCP.	String	Gateway of the host server to be used after the operating system is deployed. This is used when the network setting is set to static in the Global OS deployment settings. Tip To determine the IP mode, use GET /osdeployment/globalSettings.
	hostname	Optional	String	Hostname for the host server. If a hostname is not specified, a default hostname is assigned.
	ipAddress	Required if using static IP addresses.	String	IP address of the host server to be used after the operating system is deployed. This is used when the network setting is set to static in the Global OS deployment settings.
	mtu	Optional	Long	Maximum transmission unit for the host to be used after the operating system is deployed
	prefixLength	Optional	String	Prefix length of the host IP address to be used after the operating system is deployed. This is used when the network setting is set to static IPv6 in the Global OS deployment settings.
	selectedMAC	Required	String	MAC address of the host server to which the IP address is to be bound The MAC address is set to AUTO by default. This setting automatically detects the Ethernet ports that can be configured and used for deployment. The first MAC address (port) that is detected is used by default. If connectivity is detected on a different MAC address, the XClarity Administrator host is automatically restarted to use the newly detected MAC address for deployment, and selectedMAC is set to the newly detected MAC address. VLAN mode is supported only for servers that have MAC addresses in their inventory. If AUTO is the only the MAC address that is available for a server, then VLANs cannot be used to deploy operating systems to that server. Tip To obtain the MAC address, use the macaddress attribute in GET /hostPlatforms.
	subnetMask	Required if using static IP addresses. Optional if using DHCP.	String	Subnet mask of the host server to be used after the operating system is deployed. This is used when the network setting is set to static in the Global OS deployment settings. Tip To determine the IP mode, use GET /osdeployment/globalSettings.
	vlanId	Optional	String	VLAN ID for operating-system VLAN tagging This attribute is valid only if in VLAN mode is enabled (see GET /osdeployment/globalSettings). Important Only specify a VLAN ID when a VLAN tag is required to function on the network. Using VLAN tags can affect the network routability between the host operating system and the Lenovo XClarity Administrator.
selectedImage		Required	String	Profile ID of the operating-system image to be deployed Tip To obtain the operating-system image values, use the availableImages attribute in GET /hostPlatforms method.
storageSettings		Required	Object	Preferred storage location on which you want to deploy operating-system images
	targetDevice	Required	String	Target device. This can be one of the following values. localdisk. Local disk drive. The first enumerated local disk drive in the managed server is used. M.2drive. M.2 drive. The first enumerated M.2 drive in the managed server is used. usbdisk. Embedded USB Hypervisor. This location is applicable only when a VMware ESXi image is being deployed to managed servers. If two hypervisor keys are installed on the managed server, the VMware installer selects the first enumerated key for deployment. lunpluswwn=`LUN`@`WWN`. FC SAN storage (for example, lunpluswwn=2@50:05:07:68:05:0c:09:bb). lunplusiqn=`LUN`@`IQN`. iSCSI SAN Storage (for example, lunplusiqn=0@iqn.1990-01.com.lenovo:tgt1). Specifying the `IQN` is optional if only one iSCSI target is configured If the `IQN` is not specified, the first detected iSCSI target is selected for OSDN. If specified, and exact match is made. Note For ThinkServer servers, this value is always localdisk.
unattendFileId		Required if selectedImage includes custom unattend files; otherwise ignored.	String	ID of the unattend file to use for this OS deployment
uuid		Required	String	UUID of the host server to which the operating system is to be deployed
windowsDomain		Optional	String	(Windows only) Active Directory domain that the Windows operating system is to join after the operating system is deployed successfully. If an OU is present, specify the string using the format `domain`/`ou`. If the operating system will not join a domain, you can set this attribute to null. Note To join an Active Directory domain, you must specify either the windowsDomain or windowsDomainBlob attribute. If both are specified, the windowsDomainBlob attribute is used. Use the adusername and adpassword attributes to specify the user name and password for the domain.
windowsDomainBlob		Optional	String	(Windows only) Active Directory Computer Account Metadata (in Base-64 encoded blob format) that can be used to join the Active Directory domain. For instructions for generating a file that contains the metadata blob data, see Integrating with Windows Active Directory. Note To join an Active Directory domain, you must specify either the windowsDomain or windowsDomainBlob attribute. If both are specified, the windowsDomainBlob attribute is used. You can use metadata blob data when deploying any Windows operating system. However, this method must be used for Windows Nano Server. Specifying a domain in global settings is not supported for Windows Nano Server.

The following example deploys an operating-system to specific host platform.

[{
   "networkSettings": {
      "dns1": "192.0.2.255", 
      "dns2": "192.0.2.254", 
      "gateway": "192.0.2.200", 
      "ipAddress": "192.0.2.0", 
       "mtu": 1500, 
      "prefixLength": 64, 
     "selectedMAC": "78:9A:BC:12:34:56", 
      "subnetMask": "255.255.255.0"
   },
   "selectedImage": "rhels6.4-x86_64-install-Minimal", 
   "storageSettings": {
      "targetDevice": "lunpluswwn=2@50:05:07:68:05:0c:09:bb"
   },
   "uuid": "2D16B4422AC011E38A06000AF72567B0",
   "windowsDomain": null
}]

Response codes

Code	Description	Comments
202	Accepted	The request has been accepted for processing, but the processing has not yet completed. The request might or might not be acted upon, depending on the results of the processing.
403	Forbidden	The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request. For XClarity Administrator advanced functions, ensure that you have active licenses for each managed server that supports the advanced functions.
409	Conflict	There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500	Internal Server Error	An internal error occurred. A descriptive error message is returned in the response body.

Response body

Attributes	Type	Description
jobID	String	ID of the deployment job in job management module
result	String	Result of the request. This can be one of the following values. success. The request was successful. failed. The request failed.
messages	Array	Message list showing to which host systems the operating system to be deployed

The following example is returned if the request is successful. Use the GET /tasks/{job_list} resource to monitor the progress of the deployment.

{
   "jobId": "123",
   "result": "success",
   "messages": [{
      "explanation": "It might take a few minutes to deploy the images. You can monitor progress
                  from the Jobs list.", 
      "id": "FQXHMFC0120I", 
      "text": "OS deployment to compute nodes (\"NODE1:DH49AC8012DEF,node2:DX4D01A8C1F0E5A\") 
             has been started", 
      "recovery": {
         "text": "",
         "URL": "",
      }
   }]
}

The following example is returned if the request is not successful.

{
   "result": "failed",
   "messages": [{
      "explanation": "", 
      "id": "FQXHMFC0004M", 
      "text": "An internal error occurred.", 
      "recovery": {
         "text": "Attempt to perform the operation again. If the problem persists, contact 
                Support.",
         "URL": ""
      }
   }]
}

Give documentation feedback

PUT /hostPlatforms

Authentication​

Request URL​

Query parameters​

Request body​

Response codes​

Response body​