Guidance for Callout Scripts


Call out scripts may be used for VM naming and for IPAM address allocation and deallocation for a particular VM-based cloud region. These as specified in the Strategy section of the cloud's Details tab or Region's tab

Callout scripts can be shell executable scripts or Python scripts; however, Python scripts must be embedded in a wrapper shell script. Scripts can refer to Workload Manager environmental variables as input. Scripts must also output their results in JSON format as a series of key-value pairs. Callout scripts must also include the wrapper utility named utils.sh and use the print_ext_service_result command which encloses the output in a Workload Manager accepted format, as shown in the examples below. Certain output variables are expected of VM naming scripts and IPAM address allocation scripts as explained below.

VM Naming Script

The VM naming script is called before each node is launched. It is provided (injected into the script) with all the name variables (name of application, name of tier, image selected) for each job. It must create a string of up to 15 characters and assign that string to the reserved Workload Manager output field: vmName. The allowed characters of the VM name are as specified the Node Name Config field above.

VM Naming Script Supported Clouds and Cloud nuances

VM naming scripts are support on all VM-based clouds. The following cloud nuances apply:

Cloud ProviderNuances
vCenter

The Hostname Callout option in the Instance Naming Strategy dropdown sets the osHostname and vmName inside the guest OS. These two settings are the same:

  • As the vCenter settings

  • For Linux (CentOS7)


AWSThe Hostname Callout option in the Instance Naming Strategy dropdown sets the osHostname and vmName inside the guest OS. These two settings are the same for both Windows and Linux.

Typical Workload Manager environment variables accessed

VariableSample value or type
eNV_JOB_IDinteger (application VM only)
eNV_launchUserIdinteger
eNV_launchUserNamestring


Sample VM naming callout script

run.sh
#!/bin/bash

. /utils.sh

# Install uuidgen
apk add --no-cache util-linux

# Creating custom vm name/hostname
custom_tag="ccqa-"
vmName="$custom_tag$(uuidgen | fold -w 8 | head -1 | tr '[:upper:]' '[:lower:]')"
#vmName="$custom_tag$(($RANDOM + ($RANDOM % 2) * 32768))"
content="{ 'vmName':  '$vmName'}"; 

# Print the results
print_ext_service_result "$content"

# Recording IPAM execution and env variables
curl -s -o /tmp/record_results.sh http://http.cliqrtech.com/auto/record_results.sh
chmod 755 /tmp/record_results.sh
source /tmp/record_results.sh callout-vmNaming $vmName > /dev/null 2>&1
rm -fr /tmp/record_results.sh


IPAM Callout Scripts

There two types of IPAM callout scripts: IPAM address allocation scripts, for assigning IP addresses to vNICs on a VM; and IPAM address deallocation scripts, for freeing up used IP addresses when a VM is terminated. 


IPAM Callout Script Supported Clouds and Cloud nuances

IPAM callout scripts are supported on all VM-based clouds except AzureRM. The following cloud nuances apply to the rest.


Cloud ProviderNuances
vCenter

The osHostname setting:

  • Is not mandatory for IPAM callouts.
  • Only works for Windows.
  • The Linux setting is overwritten by the vmNaming setting.
AWSWorkload Manager uses the IP address, network, and mask to set the DHCP scope in the specified subnet.


IPAM Address Allocation Callout Output Parameters

All IPAM address allocation scripts must output their data in JSON formatted key:value pairs where the key name corresponds to one of these well known key names in the following table.


Key

Description

Required?

osHostname

OS hostname


Yes.

Not supported for AWS and OpenStack.

DnsServerList

DNS server list (comma separated)


DnsSuffixList

DNS Suffix list (comma separated).


nicCount

The number of virtual NICs (vNICs). 


No.


nicIP_0

vNIC IP address

Yes

Set on a per-NIC basis.

A new IP address must be set for each vNIC.

nicNetmask_0

vNIC netmask

Yes

Set on a per-NIC basis.

A new netmask must be set for each vNIC.

nicGateway_0

vNIC gateway IP address

No

Set on a per-NIC basis.

nicDnsServerList_0

vNIC DNS server list (comma separated)

Yes
nicUseDhcp_0

Set to TRUE if DHCP should be used for assigning an IPv4 address to this vNIC

Yes, if using IPAM callout and the addressing is assigned to use DHCP.
nicIPv6_0IPv6 IP address

Yes

Set on a per-NIC basis.

A new netmask must be set for each NIC.

nicGatewayIPv6_0IPv6 gateway IP addressYes

Set on a per-NIC basis.

A new netmask must be set for each NIC.

nicNetmaskIPv6_0IPv6 netmask

Yes

Set on a per-NIC basis.

A new netmask must be set for each NIC.

nicUseDhcpIPv6_0

Set to TRUE if DHCP should be used for assigning an IPv6 address to this vNIC

If  nicUseDhcpIPv6_0 is set to true and static IP information is also provided, then DHCP takes precedence over STATIC allocation strategy.

Custom

Example key:value pair output: "


{<myCustomParam>:<myValue>}




Custom IPAM Callout variables do not get set in the userenv file on target deployment VMs 

If the VM configuration includes multiple NICs, then the CloudCenter platform makes one IPAM call per NIC. You can also assign multiple IPs to each NIC by using keys with _n  suffix as described earlier.


Sample IPAM Allocation Scripts
 Sample IPAM Callout Script for Single-NIC Scenarios

Sample IPAM Callout Script for Single-NIC Scenarios

A single-NIC script is executed once and the nicIP_0 (for example) value is set to the first interface of the VM.

The IPAM script is executed once for every NIC. If the VM has n NICs, the same IPAM script is triggered n times.

Some parameters contain the  _0 suffix in the parameter name – the same suffix ( _0) must be used in the response for each iteration of the IPAM callout script.

This requirement is due to an underlying architectural implementation.


Single NIC Script
#!/bin/bash

. /utils.sh
content="{ 'DnsServerList' : '8.8.8.8,10.0.0.100', 'nicIP_0' : '10.0.0.100','nicDnsServerList_0' : '1.2.3.4,5.6.7.8','nicCount': '1', 'nicGateway_0':'10.0.0.1','nicNetmask_0':'255.255.255.0','domainName':'test.org','hwClockUTC':'true','timeZone':'Canada/Eastern','osHostname':'testhost1'}"

print_ext_service_result "$content"
 Sample IPAM Callout Script for Multi-NIC Scenarios

Sample IPAM Callout Script for Multi-NIC Scenarios


A multi-NIC script (similar to the single-NIC script) is executed for each NIC in your VM.

For a multi-NIC scenario, the single-NIC script is called multiple times corresponding to the number of NICs defined in your Workload Manager deployment.


For each execution of this multi-NIC script, a new nicIP_0 value is set to the corresponding interface of your VM. 

Other than changing the nicIP_0 value, you can also change the values for all other parameters – other than nicCount (which is always set to 1)

The IPAM script is executed once for every NIC. If the VM has n NICs, the same IPAM script is triggered n times.

Some parameters contain the  _0 suffix in the parameter name. The number after the hyphen must be incremented by one for each iteration of the IPAM callout script.


Multi-NIC Script
 



 Sample IPAM Scripts which Returns IPV6 IP Address

Sample IPAM Script which Returns IPV6 IP Address

When you assign IPv6 addresses, the Workload Manager validates the security rule source before accepting the IPv6 address. See IP Allocation Mode > Cloud-Specific Nuances > IPv6 Note.


Working Script for IPv6 Allocation
#!/bin/bash

. /utils.sh
count=1 
#have you logic for maintaining the count
content="{ 'DnsServerList' : '8.8.8.8,10.0.0.100', 'nicIP_0' : '###.###.###.###.$count','nicDnsServerList_0' : '1.2.3.4,5.6.7.8','nicCount': '1', 'nicGateway_0':'###.###.###.###','nicNetmask_0':'255.255.255.0','nicUseDhcp':'true','nicIPv6_0':'2600:1f14:5aa:2f00:524a:fbf5:3377:a$count'}"

print_ext_service_result "$content"






Sample IPAM Deallocation Script

The Workload Manager does not look for any output from this script as it is just a notification.


run.sh
 #!/bin/bash
  
./delete_record_by_ip.sh $IP



Callout Script OS-Specific Output Parameters

The following table shows the multiple key-value pair that is output for each callout script. 

 OS Properties

Linux

Windows

Required?

timezoneSupported for VMware.

Not supported for AWS and OpenStack.

Not usedYes

timeZoneId

Not used

The Windows Index ID for this time zone.

For Windows-specific VMware IPAM config scripts, be aware that you may only see the changes in effect after the deployment has been completed for an undetermined period of time.

AWS: No effect as instance timing is internally managed.

Yes

fullName

Not required

The name of the Admin user

Yes

organization

Not required

The name of the organization (string)

Yes

productKey

Not required 

The Windows product key

Yes

setAdminPassword

Not required

The Admin password

Yes

changeSid

Not used

A true or false value for the Microsoft SID

You must set the changeSid option to true.

Yes

deleteAccounts

Not used

A true or false value. 

Yes

dynamicPropertyName

Not used

Reserved name holder for arbitrary property

Yes

dynamicPropertyValue

Not used

Reserved value holder for arbitrary property

Yes

custSpec (see the VMware Customization Spec section below)The Guest Customization Specification name in VMwareThe Guest Customization Specification name in VMwareNo
hwClockUTC

Not supported for VMware and OpenStack.

AWS: No effect, as the clock is internally managed.

Not supported for VMware and OpenStack.

AWS: No effect, as the clock is internally managed.

Yes

domainName

Used for FQDN resolution of Linux VMs as it is visible when using hostname -f or cat /etc/hosts

Used to automatically join a domain – Only supported for VMware.

Not supported for AWS and OpenStack.

No





domainAdminName

Not used

Used to automatically joining a domain

domainAdminPassword

Not used

Used to automatically joining a domain

workgroup

Not used

The workgroup in which to place the VM.

If any of the 3 domain values are missing, the workgroup key is required.

If all three domain values are present, the workgroup is not required.




Alternate Windows Guest OS Customization (vCenter only)

Windows IPAM optimization allows you to skip the SysPrep execution for Windows deployments. SysPrep is a tool that is executed to customize Windows deployments.

Running SysPrep to customize Windows may slow down deployments. You can bypass the SysPrep by providing only IPAM properties in the corresponding callout. 

The SysPrep process will be triggered even if one of the properties in the following table are returned by the callout script.

The following table lists OS-Specific IPAM Properties for alternate Windows guest OS customization.

OS-Specific IPAM Properties*
changeSid
deleteAccounts
fullName
organization
timezone
setAdminPassword
domainName
domainAdminName
domainAdminPassword
workgroup


* Each of these properties is described in the OS-Specific Parameters section that is listed earlier in this section

  • No labels
© 2017-2019 Cisco Systems, Inc. All rights reserved