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.
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. If the management server is not license compliant, the compliance response code is set to 0.
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": ""
      }
   }]
}
Parent topic: /hostPlatforms