Step 2: Creating and editing the XML configuration file

If a Linux® deployment host is used, the IBM Spectrum Accelerate software deployment requires an XML configuration file that contains a list of essential parameters that define the ESXi cluster environment.

1. Issue the following command:

   ./xiv_sds_deployment_kit.bash -e

   The sample XML configuration file is extracted to the directory in which the deployment utility is located.

   Searching embedded archive for example files... Please wait.
   SDS_Deploy/deploy/sds_machine_template.xml

2. Open the extracted sds_machine_template.xml file in a text editor.
   The following example shows an XML template file that has no pre-entered values.

   Note: Because the XML template parameters are explained on the next step (see step 3), the following XML template example does not contain some explanatory notes that appear in the actual XML template file.

   <!-- This is a template for defining the software-defined storage (SDS)
   machine and server parameters for the deployment script (deploy_sds.py).
   Replace the uppercase strings with values that match your environment. -->
   
   <sds_machine
    name="UNIQUE_NAME_FOR_THE_MACHINE"
    interconnect_mtu="A_NUMBER_1500_TO_9000
    vm_gateway="GATEWAY_FOR_MGMNT_NETWORK"
    vm_netmask="NETMASK_FOR_MGMENT_NETWORK"
    data_disks="NUMBER_OF_RDM_DATA_DISKS"
    ssd_disks="NUMBER_OF_RDM_SSD_DISKS"
    data_disks_size_gb="WANTED_DISK_SIZE_IN_GB"
    ssd_disks_size_gb="WANTED_SSD_SIZE_IN_GB"
    memory_gb="MEMORY_FOR_VM_IN_GB"
    num_cores="NUMBER_OF_CORES"
    icn="SEVEN_DIGIT_IBM_CUSTOMER_NUMBER"
    off_premise="False"
    enable_diagnostic_mode="YES_OR_NO"
   
    <vcenter_host
     name="VCENTER_HOSTNAME_OR_IP"
     username="VCENTER_ADMIN_USERNAME"
     password="VCENTER_ADMIN_PASSWORD"
     datacenter="NAME_OF_EXISTING_DATACENTER_ON_VCENTER"
     </vcenter_host>
   
     <esx_servers
      <server
      hostname="NAME_OR_IP_OF_ESX_SERVER"
      username="root"
      password="ESX_ROOT_PASSWORD"
      datastore="DATASTORE_NAME_ON_SERVER"
      mgmt_network="NAME_OF_INTERFACE_TO_BE_USED_AS_MGMT_NETWORK"
      interconnect_network="NAME_OF_INTERFACE_TO_BE_USED_AS_INTERCONNECT_NETWORK"
      iscsi_network="NAME_OF_INTERFACE_TO_BE_USED_AS_ISCSI_NETWORK"
      vm_mgmt_ip_address="IP_ADDRESS_TO_BE_GIVEN_TO_THE_MGMT_NETWORK"
      interconnect_ip_address="IP ADDRESS" 
      interconnect_ip_netmask="IP NETMASK">
   
     <!-- Optional server element <disk> may appear 6-12 times or not at all. -->
       <disk
        identifier="DISK_IDENTIFIER_FROM_ESX_DEVICE_LIST"
        index="DISK_INDEX_FROM_1_TO_12">
       </disk>
   
       <ssd
        identifier="SSD_IDENTIFIER_FROM_ESX_DEVICE_LIST"
       </ssd>
      
     </server>
   
     <!-- You can add additional server entries here (at least 3 are required).
     Make sure that the VM IP address and datacenter names are unique. -->
     
     </esx_servers>
   </sds_machine>

3. For each parameter, replace the uppercase description string with a real value as detailed in the following tables, and then save the modified XML file.

   Table 1. XML parameters for Spectrum Accelerate storage system (sds_machine)

   Parameter	Purpose	Possible value
   name	Name (alias) of the Spectrum Accelerate storage system. Important: If you are deploying Spectrum Accelerate on an existing ESXi cluster that contains other virtual machines, the name of the Spectrum Accelerate storage system must match the name of the cluster, which must also be identical to the name of the vSphere folder that contains the cluster. For example:	Alphanumerical string
   interconnect_mtu	Maximum transmission unit (MTU) setting of the interconnect network, in bytes. Jumbo frames are required for performance purposes.	9000 or any value that is higher than or equal to the MTU of the iSCSI network (including, for example, 8500, 8700, or any applicable value)
   vm_gateway	Gateway address for the management IP address.	IP address
   vm_netmask	Netmask address of the Spectrum Accelerate storage system.	IPv4 netmask
   data_disks	Total number of data disks, or hard disk drives (HDDs), per ESXi host machine (storage system module). Note: You can assign a unique ID to each disk, as described in Table 4.	Integer from 6 to 12
   ssd_disks	Total number of solid-state drives (SSDs) per ESXi host machine. Note: If a solid-state drive is used, you can assign a unique ID to it, as described in Table 5.	0 or 1
   data_disks_size_gb	Capacity in Gigabytes (GB) of the data disks that are to be used by IBM Spectrum Accelerate. This parameter is used for the automatic selection of disks. The parameter value is expected to be in 1GB=2^30 bytes, also sometimes referred to as GiB. Many hardware manufacturers report disk size in metric GB (1GB=10^9 bytes). For example, for a 2TB disk, the value of data_disks_size_gb should be 1907GB, for a 4TB disk - 3810GB, and so on. Important: All data disks much have the same capacity and must be identical to the actual disk size on all target ESXi host machines.	Integer from 1000 to 4000
   ssd_disks_size_gb	Capacity in Gigabytes (GB) of the SSD cache disk (if used) for IBM Spectrum Accelerate on each ESXi host machine.	Integer from 500 to 800
   memory_gb	Total memory (RAM) that should be allocated for the Spectrum Accelerate virtual machine on each ESXi host machine, in Gigabytes. Important: The specified memory size for the Spectrum Accelerate virtual machine must be at least 4 GB less than the total size of the physical memory on each ESXi host machine.	Integer from 24 to 128
   num_cores	Number of physical CPU cores (not counting on Hyper-Threading) that should be dedicated for the Spectrum Accelerate virtual machine on the ESXi host machine.	Integer from 4 to one core less than the total number of available physical CPU cores on the ESXi host machine
   icn	IBM customer number (ICN). Contact IBM to obtain your ICN. If you already obtained an ICN in the past and you have a working IBM Spectrum Accelerate system, you can retrieve your ICN as described in Retrieving your IBM Customer Number (ICN).	A valid 7-digit number
   off_premise	Indicates whether the Spectrum Accelerate storage system is deployed on local ESXi servers at the customer premises, or off-premise on cloud-based servers.	Yes (off-premise system) No (local system)
   enable_diagnostic_mode	When enabled (with a value of Yes), diagnostic mode provides a boot sequence in which the network environment and disk performance are analyzed prior to the deployment. During this analysis, relevant warnings or errors are issued. Warnings allow the deployment to continue, while any detected error stops the deployment. However, warnings should be evaluated carefully before starting to use the storage system. After a successful diagnostic run (without errors), the storage system reboots and then the Spectrum Accelerate processes are prepared to be turned on but not started. Important: As a best practice, always deploy with diagnostic mode enabled, unless your environment has been tested and you are sure that no diagnostic is needed.	Yes (default) No

   Table 2. Optional XML parameters for a vCenter server (vcenter_host)

   Parameter	Purpose	Possible value
   name	Hostname or IP address of the vCenter server that is used to monitor and control the ESXi hosts.	Hostname or IP address
   username	Username for accessing the vCenter server.	A valid username
   password	Password for accessing the vCenter server. Attention: Since the password is saved in the XML file as cleartext, you can avoid exposing the password in the file by omitting the password parameter altogether. If you omit the password parameter, you will be prompted for the password during the deployment process (after issuing the deployment command). The password is masked when it is entered during the deployment process.	A valid password
   datacenter	Name of an existing datacenter entity (vCenter entity) in which the Spectrum Accelerate storage system should be defined.	Alphanumerical string

   Important: If a vCenter server is not used, delete the vcenter_host parameters (the entire section) from the XML file.

   Table 3. XML parameters for a single ESXi host (server; storage system module)

   Parameter	Purpose	Required value
   hostname	Hostname or IP address (management IP address) of the ESXi host that should be used as a storage system module.	Hostname or IP address
   username	Username for accessing the ESXi host.	A valid username
   password	Password for accessing the ESXi host. Attention: Since the password is saved in the XML file as cleartext, you can avoid exposing the password in the file by omitting the password parameter altogether. If you omit the password parameter, you will be prompted for the password during the deployment process (after issuing the deployment command). The password is masked when it is entered during the deployment process.	A valid password
   datastore	Name of the pre-configured datastore (requires 250 GB of free space; see Required VMware ESXi host machines) in which the image of the Spectrum Accelerate virtual appliance should be stored.	Alphanumerical string
   mgmt_network	Name of the management network on the ESXi host. For more information, see Required VMware ESXi host machines.	Alphanumerical string
   interconnect_network	Name of the network that the ESXi host uses for port group mapping and interconnecting with the other ESXi hosts. For more information, see Required vSwitch, network, and deployment host.	Alphanumerical string
   iscsi_network	Name of the iSCSI network that the ESXi host makes available for storage provisioning. For more information, see Required VMware ESXi host machines.	Alphanumerical string
   vm_mgmt_ip_address	IP address that should be assigned to the Spectrum Accelerate virtual machine (VM) on the management network.	IP address
   interconnect_ip_address	Static IP address that is used for interconnecting the storage system module with the other modules. Important: All interconnect IP addresses must reside in the same subnet.	A valid IP address
   interconnect_ip_netmask	Netmask IP address of the interconnect network.	A valid IP address

   Important: The server set of parameters must be repeated in the XML file for each ESXi host that is to be used as a Spectrum Accelerate module. Add a separate set of server parameters in the XML file for each ESXi host, within the esx_servers section. At least 3 servers are required.

   Table 4. Optional XML parameters for server HDDs (disk)

   Parameter	Purpose	Possible value
   identifier	Unique ID for the hard disk drive (HDD), as recognized by the ESXi server. The ID of a certain disk is embedded to it during manufacturing, and can be viewed on the relevant ESXi server Disks panel in VMware vSphere Client (see Collecting individual disk IDs). Example: identifier=naa.50934983 Attention: Specifying disk IDs is optional. However, if you specify the ID of a certain disk, you must specify the ID of all HDDs that are used by the ESXi host machine.	Alphanumerical string
   index	Sequential number of the hard disk drive.	Integer from 1 to 12

   Important: The disk parameters must be repeated in the XML file for each disk that is used by the ESXi host machine. Add a separate section of disk parameters within the relevant server section. At least 6 disks are required per server (ESXi host machine).

   Table 5. Optional XML parameter for server SSD (ssd; if used)

   Parameter	Purpose	Possible value
   identifier	Unique ID for the solid-state drive (SSD), as recognized by the ESXi server. The ID of the SSD is embedded to it during manufacturing, and can be viewed on the relevant ESXi server Disks panel in VMware vSphere Client (see Collecting individual disk IDs).	Alphanumerical string