CliQr is now part of Cisco Learn More About Cisco

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 Allocation (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.

    Icon

    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

Effective CloudCenter 4.7.0, all callout scripts are executed as cliqruser as part of the security hardening implementation.

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

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.

Icon

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

Script TopicFolderCallout Script fileDescriptionSupported 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.

AzureRM, OpenStack, VMware, and AWS.

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.

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

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

Network and OS-specific configuration

OpenStack, VMware, 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


  • topic=ipam


  • topic=ipamDealloc


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

Icon

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

Best Practice

Icon

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.

Icon

If you make changes to the callouts or attributes for a Cloud Region, you must restart the CCO for the changes to take effect.

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

This script allows you to change the name of the VM. See VM (Node) Name Config to rename the VM using the CCM UI for Azure, OpenStack, VMware, and AWS clouds.

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 
vmNamingName of the VM

A sample vmNaming callout script output:

run.sh

The IPAM Callout Script

Supported Clouds: AWS, VMware, and OpenStack.

Icon

You will ALSO need to enable the region for the IPAM Naming Strategy as identified in the VM Name Config > 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 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 Properties

The multiple key-value pair that is output for each callout script. 

Key

Description

Required?

osHostname

The OS hostname

 

Yes.

Not supported for Amazon and OpenStack.

DnsServerList

DNS  server list (comma separated)

 

DnsSuffixList

DNS Suffix list (comma separated)

 

nicCount

The number of virtual NICs (vNICs)

Yes

The nicCount parameter only allows one NIC to be used at any time.

nicIP_n

Nth vNIC’s IP address

Yes

nicNetmask_n

Nth vNIC’s netmask

Yes

nicGateway_n

Nth vNIC’s gateway (CCO) IP address

Yes

nicDnsServerList_n

Nth vNIC’s DNS server list (comma separated)

Yes

nicUseDhcp_0

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

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

ANY

This property is supported if the reinject setting is true

Example: myCustomParam=myValue

 
Icon

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 IPAM Properties

The multiple key-value pair that is output for each callout script.

 IPAM Properties

Linux

Windows

Required?

timezoneSupported for VMware.

Not supported for Amazon and OpenStack.

Not usedYes

timeZoneId

Not used

The Windows Index ID for this time zone.

Icon

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.

Amazon: 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

custSpecThe Guest Customization Specification name in VMwareThe Guest Customization Specification name in VMwareNo
hwClockUTC

Not supported for VMware and OpenStack.

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

Not supported for VMware and OpenStack.

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

Yes

domainName

Linux domain name

Icon

If you do not specify the domainName, the CloudCenter platform sets it to the  default value, mydomain.

Be sure to provide this value if you do not want to use the default mydomain value.

Not supported for Amazon and OpenStack.

Used to automatically join a domain

Yes

 

 

 


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

Sample IPAM Callout Script

run.sh

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

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

Sample Callout Workflow

Sample IPAM Callout