Details about payload

Non-Windows OS Installation Workflow Payload

All parameters descriptions of OS installation workflow payload are listed below, they are fit for use with all supported OSes except for CoreOS (see note below).

NOTE: The CoreOS installer is pretty basic, and only supports certain parameters shown below. Configurations not directly supported by RackHD may still be made via a custom Ignition template. Typical parameters for CoreOS include: version, repo, and installScriptUri*|*ignitionScriptUri and optionally vaultToken and grubLinuxAppend.

Parameters Type Flags Description
version String required The version number of target OS that needs to install. NOTE: For Ubuntu, version should be the codename, not numbers, for example, it should be “trusty”, not “14.04”
repo String required The OS repository address, currently only supports HTTP. Some examples of free OS distributions for reference. For CentOS, http://mirror.centos.org/centos/7/os/x86_64/. For Ubuntu, http://us.archive.ubuntu.com/ubuntu/. For openSUSE, http://download.opensuse.org/distribution/leap/42.1/repo/oss/. For ESXi, RHEL, SLES and PhotonOS, the repository is the directory of mounted DVD ISO image, and http service is provided for this directory.
osName String required (Debian/Ubuntu only) The OS name, the default value is debian for ubuntu installation use ubuntu.
rootPassword String optional The password for the OS root account, it could be clear text, RackHD will do encryption before store it into OS installer’s config file. default rootPassword is “RackHDRocks!”. Some OS distributions’ password requirements must be satisfied. For ESXi 5.5, ESXi 5 Password Requirements. For ESXi 6.0, ESXi 6 Password Requirements.
hostname String optional The hostname for target OS, default hostname is “localhost”
domain String optional The domain for target OS
timezone String optional (Debian/Ubuntu only) The Timezone based on $TZ. Please refer to https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
ntp String optional (Debian/Ubuntu only) The NTP server address.
users Array optional If specified, this contains an array of objects, each object contains the user account information that will be created after OS installation. 0, 1, or multiple users could be specified. If users is omitted, null or empty, no user will be created. See users for more details.
dnsServers Array optional If specified, this contains an array of string, each element is the Domain Name Server, the first one will be primary, others are alternative.
ntpServers Array optional If specified, this contains an array of string, each element is the Network Time Protocol Server.
networkDevices Array optional The static IP setting for network devices after OS installation. If it is omitted, null or empty, RackHD will not touch any network devices setting, so all network devices remain at the default state (usually default is DHCP).If there is multiple setting for same device, RackHD will choose the last one as the final setting, both ipv4 and ipv6 are supported here. (ESXi only, RackHD will choose the first one in networkDevices as the boot network interface.) See networkDevices for more details.
rootSshKey String optional The public SSH key that will be appended to target OS.
installDisk String/Number optional installDisk is to specify the target disk which the OS will be installed on. It can be a string or a number. For string, it is a disk path that the OS can recongize, its format varies with OS. For example, “/dev/sda” or “/dev/disk/by-id/scsi-36001636121940cc01df404d80c1e761e” for CentOS/RHEL, “t10.ATA_____SATADOM2DSV_3SE__________________________20130522AA0990120088” or “naa.6001636101840bb01df404d80c2d76fe” or “mpx.vmhba1:C0:T1:L0” or “vml.0000000000766d686261313a313a30” for ESXi. For number, it is a RackHD generated disk identifier (it could be obtained from “driveId” catalog). If installDisk is omitted, RackHD will assign the default disk by order: SATADOM -> first disk in “driveId” catalog -> “sda” for Linux OS. NOTE: Users need to make sure the installDisk (either specified by user or by default) is the first bootable drive from BIOS and raid controller setup. PhotonOS only supports ‘/dev/sd*’ format currently.
installPartitions Array optional installPartitions is to specify the installDisk’s partitions when OS installer’s default auto partitioning is not wanted. (Only support CentOS at present, Other Linux OS will be supported). See installPartitions for more details.
kvm Boolean optional The value is true or false to indicates to install kvm or not, default is false. (ESXi, PhotonOS doesn’t support this parameter)
switchDevices Array optional (ESXi only) If specified, this contains an array of objects with switchName, uplinks (optional), and failoverPolicy (optional) parameters. If uplinks is omitted, null or empty, the vswitch will be created with no uplinks. If failoverPolicy is omitted, null or empty, the default ESXi policy will be used. See switchDevices for more details.
postInstallCommands Array optional (ESXi only) If specified, this contains an array of string commands that will be run at the end of the post installation step. This can be used by the customer to tweak final system configuration.
installType String optional (PhotonOS only) The value is minimal or full to indicate the type of installed OS, defualt installType is minimal
installScriptUri String optional The download URI for a custom kickstart/preseed/autoyast/cloud-config template to be used for automatic installation/configuration.
ignitionScriptUri String optional (CoreOS only) The download URI for a custom Ignition template used for post-install system configurations for CoreOS Container Linux
vaultToken String optional (CoreOS only) The token used for unwrapping a wrapped Vault response – currently only an Ignition template (ignitionScriptUri) or cloud-config userdata (installScriptUri) payload is supported.
grubLinuxAppend String optional

(CoreOS only) Extra (persistent) kernel boot parameters

NOTE: There are RackHD specific commands within all default install templates that should be copied into any custom install templates. The built-in templates support the above options, and any additional install logic is best added by copying the default templates and modifying from there. The default install scripts can be found in https://github.com/RackHD/on-http/tree/master/data/templates, and the filename is specified by the installScript field in the various OS installer task definitions (e.g. https://github.com/RackHD/on-tasks/blob/master/lib/task-data/tasks/install-centos.js)

remoteLogging Boolean optional If set to true, OS installation logs will be sent to RackHD server from nodes if installer supports remote logging. Note you must configure rsyslog on RackHD server if you want to receive those logs. Please refer to https://github.com/RackHD/RackHD/blob/master/example/config/rsyslog_rackhd.cfg.example as how to enable rsyslog service on RackHD server. Currently only CentOS installation supports this feature, we are still working on other OS installation workflows to enable this feature.
bonds Array optional (RHEL/CentOS only) Bonded interface configuration. Bonded interfaces will be created after OS installation. If it is omitted, null or empty, RackHD will not create any bond interface.
packages Array optional (RHEL/CentOS only) List of packages, package groups, package environments that needs to be installed along with base RPMs. If it is omitted, null or empty, RackHD will just install packages in base package group.
enableServices Array optional (RHEL/CentOS only) List of services that needs to be enabled explicitly after OS installation is completed.
disableServices Array optional (RHEL/CentOS only) List of services that needs to be disabled explicitly after OS installation is completed. If it is omitted, null or empty, RackHD will not not disable any installed service.

For users in payload:

Parameters Type Flags Description
name String required The name of user. it should start with a letter or digit or underline and the length of it should larger than 1(>=1).
password String required The password of user, it could be clear text, RackHD will do encryption before store it into OS installer’s config file. The length of password should larger than 4(>=5). Some OS distributions’ password requirements must be satisfied. For ESXi 5.5, ESXi 5 Password Requirements. For ESXi 6.0, ESXi 6 Password Requirements.
uid Number optional The unique identifier of user. It should be between 500 and 65535.(Not support for ESXi OS)
sshKey String optional The public SSH key that will be appended into target OS.

For networkDevices in payload, both ipv4 and ipv6 are supported

Parameters Type Flags Description
device String required Network device name (ESXi only, or MAC address) in target OS (ex. “eth0”, “enp0s1” for Linux, “vmnic0” or “2c:60:0c:ad:d5:ba” for ESXi)
ipv4 Object optional See ipv4 or ipv6 more details.
ipv6 Object optional See ipv4 or ipv6 more details.
esxSwitchName String optional (ESXi only) The vswitch to attach the vmk device to. vSwitch0 is used by default if no esxSwitchName is specified.

For installPartitions in payload:

Parameters Type Flags Description
mountPoint String required Mount point, it could be “/boot”, “/”, “swap”, etc. just like the mount point input when manually installing OS.
size String required Partition size, it could be a number string or “auto”, For number, default unit is MB. For “auto”, all available free disk space will be used.
fsType String optional File system supported by OS, it could be “ext3”, “xfs”, “swap”, etc. If mountPoint is “swap”, the fsType must be “swap”.
  • Debian/Ubuntu installation requires boot, root and swap partitions, make sure your auto sized partition must be the last partition.

For ipv4 or ipv6 configurations:

Parameters Type Flags Description
ipAddr String required The assigned static IP address
gateway String required The gateway.
netmask String required The subnet mask.
vlanIds Array optional The VLAN ID. This is an array of integers (0-4095). In the case of Windows OS, the vlan is an array of one parameter only
mtu Number optional Size of the largest network layer protocol data unit

For switchDevices (ESXi only) in payload:

Parameters Type Flags Description
switchName String required The name of the vswitch
uplinks String optional The array of vmnic# devices or MAC address to set as the uplinks.(Ex: uplinks: [“vmnic0”, “2c:60:0c:ad:d5:ba”]). If an uplink is attached to a vSwitch, it will be removed from the old vSwitch before being added to the vSwitch named by ‘switchName’.
failoverPolicy String optional This can be one of the following options: explicit: Always use the highest order uplink from the list of active adapters which pass failover criteria. iphash: Route based on hashing the src and destination IP addresses mac: Route based on the MAC address of the packet source. portid: Route based on the originating virtual port ID.

For bonds (RHEL/CentOS only) in payload:

Parameters Type Flags Description
name String required The name of the bond. Example ‘bond0’
nics Array optional The array of server NICs that needs to be included in the bond.
bondvlaninterfaces Array optional List of tagged sub-interfaces to be created associated with the bond interface

For bondvlaninterfaces in payload, both ipv4 and ipv6 are supported

Parameters Type Flags Description
vlanid Number required VLAN ID to be associated with the tagged sub interface
ipv4 Object optional See ipv4 or ipv6 more details.
ipv6 Object optional See ipv4 or ipv6 more details.

Windows OS Installation Workflow Payload

Parameters Type Flags Description
productkey String required Windows License
domain String optional Windows domain
hostname String optional Windows hostname to be giving to the node after installation
smbUser String required Smb user for the share to which Windows’ iso is mounted
smbPassword String required Smb password
repo String required The share to to which Windows’ iso is mounted

Example of minimum payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_windows_payload_minimal.json

Example of full payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_windows_payload_full.json