// removed jquery ui css and js

Deployment Workflow Callout Scripts

Overview

At various stages in the deployment lifecycle of VMs, The CloudCenter platform supports the ability to control the behavior of the provisioning process. The different lifecycle points where the behavior can be controlled are called topics. The behavior is controlled by scripts via callouts that are assigned to topics. A common use case for callouts is to query an IPAM tool during the IP Address Management (IPAM) topic to get an IP address and during the IP shutdown topic (ipamDealloc) to de-allocate the IP address. See the Infoblox integration page for an example of implementing this use-case.

Callouts are configured on a per-CCO basis and apply to each VM provisioned from that CCO. If different behaviors are required, use control logic (if/then/case) from inside the callout script.

Each callout script:

  • Uses the same parameters and incoming variables.

  • Exposes a different variable and is mutually exclusive – you can execute any script when required.

  • Has access (when executed from the CloudCenter platform) to a wide variety of environment variables, including cloud type, deployment environment, and so forth.

    A full list is available in the callout script log at /usr/local/osmosix/callout/<name>/logs/<timestamp>

  • Consists of two key parts – a configuration file (callout.conf) and the script to be executed. Place these files in the /usr/local/osmosix/callout/<script topic>/<files> path on the CCO. The name of the sub-folder that you use is arbitrary, but a best-practice is to use the name of the topic for that callout. For example:
    /usr/local/osmosix/callout/ipam/<files>

Permissions

As part of the security hardening implementation, all callout scripts are executed as cliqruser.

Existing callout scripts continue to work without any change – if you encounter a failure, be sure to verify the items that the following table describes.

Callout AccessDependency
Workspace permissionchown –R cliqruser:cliqruser /usr/local/osmosix/callout
Scripts shebang line
  • Bash:
    #!/bin/bash
  • Python:
    #!/usr/bin/python2.7
cliqruser privilege
  • Ability to read/write to files/directories used within the scripts

  • Ability to issue any command used within the scripts

Supported Callout Topics

Each of these scripts are explained in the sections below.

Use the table of contents above to link directly to each script explanation.

The following table describes the scripts.

Script TopicFolderCallout Script File LocationDescriptionSupported Clouds
vmNaming/usr/local/osmosix/callout/vmnaming/

/usr/local/osmosix/callout/vmnaming/callout.conf

Called before each node is launched.

This script is provided (injected into the script) all the name variables (name of application, name of tier, image selected) for each job.

  • OpenStack, VMware, AWS, Google, and Alibaba
  • VMware vCD
  • AzureRM, Azure Stack, and IBM cloud
  • Dimension Data

See VM (Node) Name Config for additional details on the supported callouts for the supported clouds.

 VMware Nuances

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).
 Amazon Nuances

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 for both Windows and Linux.

 Alibaba Nuances

You cannot use the hyphen character anywhere in the string for both Windows and Linux instances.

ipam/usr/local/osmosix/callout/ipam/

/usr/local/osmosix/callout/ipam/callout.conf

Network and OS-specific configuration

OpenStack, VMware, Google, and AWS.

 VMware Nuances

The osHostname setting:

  • Is not mandatory for IPAM callouts.
  • Only works for Windows.
  • The Linux setting is overwritten by the vmNaming setting.
 Amazon Nuances

CloudCenter uses the IP address, network, and mask to set the DHCP scope in the specified subnet.

ipamDealloc/usr/local/osmosix/callout/ipamDealloc/

/usr/local/osmosix/callout/ipamDealloc/callout.conf

Called just before a node is destroyed

OpenStack, VMware, and AWS.

Supported Attributes for callout.conf files

This callout script supports standard Java property file format, using <key>=<value>, each on a separate line. See the following callout.conf file examples for all three topics:

  • topic=vmNaming

    [root@centos7-base ipam]# cat ../vmnaming/callout.conf
    name=vmNamingExample
    type=exec
    topic=vmNaming
    debug=true
    executable=run.sh
    reinject=true
    disabled=false


  • topic=ipam

    [root@centos7-base ipam]# cat callout.conf
    name=ipamExample
    type=exec
    topic=ipam
    debug=true
    executable=ipam.py
    reinject=true
    disabled=false


  • topic=ipamDealloc

    [root@centos7-base ipam]# cat ../ipamDealloc/callout.conf
    name=ipamDeallocExample
    type=exec
    topic=ipamDealloc
    debug=true
    executable=run.sh
    reinject=true
    disabled=false

Environment Variables for Callout Scripts

The Callout script accepts environment variables as input parameters. The list of variables depends on the node type. The following table provides a sample.

 Variable

 Sample Values or Type

eNV_osName

Linux, Windows

eNV_vmNaming

A string passed by the vmNaming module or auto-generated by the CloudCenter platform

eNV_JOB_ID

An integer to identify the application VM (only)

eNV_launchUserId

An integer to identify the User ID of the person launching the script/module

eNV_launchUserName

A string to identify the user name of the person launching the script/module

All job application settings for application VMs are also available as eNV variables. See CloudCenter-Defined Parameters  for additional context.

Best Practice

Turn on the debug level and check the debug logs (see Locate Log Files) to view a list of all available input variables.

Configure Each Callout Script

Configure each script separately in a callout.conf file.

You can configure the each of these callout scripts at the region level, not at the tenant level, on a per-CCO basis. The following example depicts the configuration procedure to add the vmNaming callout script.

Caution

If you Edit Cloud Settings on the Cloud Region page (CCM UI > Admin > Clouds > Configure Region), you must save the changes to the CCO by clicking Configure Orchestrator and then Save to ensure that these changes are also propagated to CCOs.

The callout scripts reside in the /usr/local/osmosix/callout/callout_name/ folder, where callout_name is the name of the corresponding callout.

To add a callout script, follow this process.

  1. Create the following directory on the CCO:

    /usr/local/osmosix/callout/vmnaming/ 
  2. Create the following file in this directory:

    /usr/local/osmosix/callout/vmnaming/callout.conf
  3. Create a file for the script:

    /usr/local/osmosix/callout/vmnaming/<script name>
  4. Ensure to execute permissions:

    chmod 777 <script>
  5. Reference this file in the callout.conf file.

The vmNaming Callout Script

The following table describes the supported environment variables for the vmNaming script.

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

The supported key for the vmNaming script:

CloudCenter-Required KeyDescription 
vmNameName of the VM

A sample VM naming callout script output:

run.sh
#!/bin/bash

echo "vmName='$(uuidgen | fold -w 8 | head -1)'"

The vmName should not exceed 15 characters for a Windows OS. This script allows you to change the name of the VM. See VM (Node) Name Config to rename the VM using one of the supported clouds (see table above).

The IPAM Callout Script

You will ALSO need to enable the region for the IPAM Naming Strategy as identified in the Region-Level Cloud Settings > Instance IPAM Strategy section.

As part of the integration, create a IPAM module and include the dynamically-invoked callout script when launching the CCO. The module can be dynamically loaded/reloaded (auto-load) or loaded at CCO start-up time. By default, auto-load is disabled.

The IPAM module's callout script includes (but is not restricted to) the following parameters:

  • DNS server list
  • DNS suffix list
  • Number of vNIC
  • Number of vNIC’s IP address
  • Numbers of vNIC’s netmask
  • VM name

Once the script is executed, all deployments for that cloud discover IP addresses managed by the IPAM module.

The IPAM callout script options are supported for VMware and OpenStack.

 Amazon Nuances

CloudCenter uses the IP address, network, and mask to set the DHCP scope in the specified subnet.

The callout script path is /usr/local/osmosix/callout, where each module is a sub-folder under the script path.

Example

UserClusterName="cluster01" 
eNV_Cloud_Setting_UserDataCenterName="dc02" 
eNV_NumTasks="1" eNV_UseBatchTaskList="0" 
eNV_Cloud_Setting_UserResourcePoolName="resourcepool1" 
eNV_Cloud_Setting_UserClusterName="cluster01"

Supported IPAM Properties

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

Key

Description

Required?

osHostname

The 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)

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

The nicCount must be set to 1.

No.


nicIP_0

vNIC’s IP address

Yes

Set on a per-NIC basis.

A new IP address must be set for each vNIC.

nicNetmask_0

vNIC’s 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’s DNS server list (comma separated)

Yes
nicUseDhcp

As part of the IPAM script, provide dummy values for nicIP_0 and nicDnsServerList_0. However, these values are overwritten by the DHCP settings.

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 (CCO) 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

This value is overwritten by the DHCP settings.

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

ANY

This property is supported if the reinject setting is true

Example: 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.

OS-Specific Properties

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.

Windows-Specific Example

run.sh
#!/bin/bash
 
echo "setAdminPassword=abcd"
echo "timeZoneId=10 *"
echo "fullName=Enterprise ABCD"
echo "organization=ABCD"
echo "productKey=..."
echo "changeSid=true"

VMware Customization Spec

VMware's  OS customization Spec feature allows you to configure network settings in vSphere (the VMware console). The CloudCenter platform allows you to specify the name of the Customization Spec (already created on the VMware vShpere console), in the IPAM callout script. To specify this spec, select IPAM Callout in the Instance IPAM Strategy field.

If you set the VMware IPAM strategy as IPAM Callout, you have multiple options.

  • Use it to indicate the IPAM Callout in the table above and the CloudCenter platform completes the Static or Dynamic IP configuration.
  • Specify the Name of the Customization Spec in the Callout script.
    • If the CloudCenter platform detects the value in the custSpec key, then it ignores all other settings.
    • To specify the Name of the Customization Spec in the Callout script, ensure that the IPAM Callout script contains the following key-value pair:
      custSpec=CustSpec101

      custSpec=<name of the os customization spec>
      # This value must already be present on VMware vShpere. 
      # This value must already be accessible to the CloudCenter administrator.

Alternate Windows Guest OS Customization

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

In prior CloudCenter releases, running SysPrep to customize Windows slowed 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.

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

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

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
 
echo "DnsServerList=8.8.8.8,10.0.0.100"
echo "nicCount=1"  # This is a mandatory parameter and is always set to 1
echo "nicIP_0=10.0.0.100"
echo "nicDnsServerList_0=1.2.3.4,5.6.7.8"
echo "nicGateway_0=10.0.0.1"
echo "nicNetmask_0=255.255.255.0"

echo "domainName=test.org"
echo "hwClockUTC=true"
echo "timeZone=Canada/Eastern"
echo "osHostname=testhost1"

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 CloudCenter 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 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.

Multi-NIC Script
#!/bin/bash
 
echo "DnsServerList=8.8.8.8,10.0.0.100"
 
echo "nicCount=1"  # This is a mandatory parameter and is always set to 1
echo "nicIP_0=10.0.0.100"
echo "nicDnsServerList_0=1.2.3.4,5.6.7.8"
echo "nicGateway_0=10.0.0.1"
echo "nicNetmask_0=255.255.255.0"

echo "domainName=test.org"
echo "hwClockUTC=true"
echo "timeZone=Canada/Eastern"
echo "osHostname=testhost1"

The ipamDealloc Callout Script

The ipamDealloc script allows you to cleanup your environment and only works with custom property supported by reinject setting.

ipamDealloc Example:

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

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

Sample Callout Workflow Using Infoblox Integration

This script can also be used as an example for multi-NIC scenarios. 

The implementation of the special handling of a default gateway depends on the IPAM Callout vendor and/or environment.

Sample IPAM Callout
#!/usr/local/bin/python2.7
import infoblox, sys, requests, os, random
requests.packages.urllib3.disable_warnings()

#Assign command line arguments to named variables
hostname = os.environ['vmNaming']
domain = "vm.cloudcenter.com"
fqdn = hostname + "." + domain
network = "10.49.18.0/23" #sys.argv[2]
netmask = "255.255.254.0"
gateway = "10.49.19.254"
dns_server = "10.48.112.33,10.52.112.19"

#Setup connection object for Infoblox
iba_api = infoblox.Infoblox('10.49.9.163', 'admin', 'infoblox', '1.4', 
iba_dns_view='VM-view', iba_network_view='default', iba_verify_ssl=False)

try:
	#Create new host record with supplied network and fqdn arguments
	ip = iba_api.create_host_record(network, fqdn)
	print "DnsServerList="+dns_server
	print "nicCount=1"
	print "nicIP_0=" + ip
	print "nicDnsServerList_0="+dns_server
	print "nicGateway_0="+gateway
	print "nicNetmask_0="+netmask
	print "domainName="+domain
	print "HWClockUTC=true"
	print "timeZone=Canada/Eastern"
	print "osHostname="+hostname
	print "infobloxFQDN="+fqdn
except Exception as e:
	print e

Sample IPAM Scripts which Returns IPV6 IP Address

When you assign IPv6 addresses, the CloudCenter platform 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
COUNTER_FILE="/usr/local/osmosix/callout/ipam/cnt"
count=`cat $COUNTER_FILE`
echo $count

echo "DnsServerList=8.8.8.8,10.0.0.100"
echo "nicCount=1"
echo "nicIP_0=###.###.###.###.$count"
echo "nicIPv6_0=2600:1f14:5aa:2f00:524a:fbf5:3377:a$count"
echo "nicDnsServerList_0=1.2.3.4,5.6.7.8"
echo "nicGateway_0=###.###.###.###"
echo "nicNetmask_0=255.255.0.0"
echo "nicUseDhcp=true"

((count++))
echo $count > $COUNTER_FILE


Sample IPv6 Static IP Allocation
#!/bin/bash
  
subnet1="subnet-18d85234"

cntfile="/usr/local/osmosix/callout/ipam/cnt"
cnt=`cat $cntfile`
echo "custSpec=ipam220"

cnt=$(($cnt+1))

networkId=$networkId
if [ $networkId == $subnet1 ]; then

ip0="10.0.0.$cnt"
ipv60="2600:1f18:658b:ab00:524a:fbf5:3377:a$cnt"

cnt=$(($cnt+1))
ip1="10.0.0.$cnt"
ipv61="2600:1f18:658b:ab00:524a:fbf5:3377:b$cnt"

echo "DnsServerList=###.163.128.140,8.8.8.8"
echo "nicCount=2"
echo "nicIP_0=$ip0"
echo "nicIP_1=$ip1"
echo "nicDnsServerList_0=###.163.128.140,8.8.8.8"
echo "nicGateway_0=###.###.###.###"
echo "nicNetmask_0=255.255.255.0"
echo "nicIPv6_0=$ipv60"
echo "nicIPv6_1=$ipv61"

else

ip0="10.0.0.$cnt"
ipv60="2600:1f18:658b:ab00:524a:fbf5:3377:a$cnt"
cnt=$(($cnt+1))
ip1="10.0.0.$cnt"
ipv61="2600:1f18:658b:ab00:524a:fbf5:3377:b$cnt"

echo "DnsServerList=###.163.128.140,8.8.8.8"
echo "nicCount=2"
echo "nicIP_0=$ip0"
echo "nicIP_1=$ip1"
echo "nicDnsServerList_0=###.163.128.140,8.8.8.8"
echo "nicGateway_0=###.###.###.###"
echo "nicNetmask_0=255.255.255.0"
echo "nicIPv6_0=$ipv60"
echo "nicIPv6_1=$ipv61"

fi

echo $cnt > $cntfile



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