Specify Deployment Parameters for Services

A deployment parameter is a configuration setting applied to a VM component at deployment time.

Deployment parameter values can be set for service requests:

Specify deployment parameters through substitution variables

When expressed through substitution variables, deployment parameters are key-value pairs with a syntax read as instructions for how to configure a VM. Deployment parameter keys are case-sensitive and must be in uppercase. Invalid values like a spelling mistake in a datastore name will cause deployment failures.

You can use multiple deployment parameters in a request, but all values must make sense together. Also, only the last occurrence of a deployment parameter is used.

Access:

Service Request Approval page (accessed from approval email)

OR

Request Details dialog > Add Comment

Available to:

Approvers set up in the Approval Workflow

Administrator, Operator, Operator with Approval Access Rights

Deployment Parameters

Parameter Syntax

Purpose

$DATASTORE=
<datastore_name>$

Example:

$DATASTORE=My Datastore$

Specify the datastore for the VM. Every disk of all VMs in a request will be deployed to the specified datastore.

Supported for vCenter and SCVMM only.

$DESTINATION=
<destination_name>$

Example:

$DESTINATION=Development Lab$

Specify the deployment destination (see Configure Automated Deployment for Approved Service Requests). Valid values are destination names for the targeted cloud account. The requester must have access to the specified deployment destination.

$IP<x>=<ip_address>$

$NETMASK<x>=
<netmask>$

$GATEWAY<x>=
<gateway>$

$DNS<x>=<dns>$

Example:

$IP1=1.1.1.1$ $NETMASK1=255.255.255.0$

$GATEWAY1=1.1.1.1$ $DNS1=1.1.1.10$

Specify multiple sets of these properties by changing the number in the string. For example:

$IP1=1.1.1.1$, $IP2=2.2.2.2$

If you use multiple sets, they will be applied during the deployment process in the order in which they are specified. For example, $IP1=1.1.1.1$ is applied to Network adapter 1 and $IP2=2.2.2.2$ is applied to Network adapter 2.

You can also specify an alternate DNS server for an adapter as shown in this example for the first adapter:

$DNS1=10.10.10.21;10.10.10.22$

Example of alternate DNS servers for the second adapter:

$DNS2=10.10.10.21;10.10.10.22$

Specify the IP address, Netmask, Gateway and DNS name for the VM. All four properties must be configured for successful deployment.

Substitute <x> in the syntax with a number (1, 2, 3 and so on), as shown in the examples.

The specified netmask, gateway and DNS server will be applied to all VMs in a request.

Only supported for:

  • single-VM services
  • vCenter and SCVMM

$NETWORK<x>=
<network_name>$

Example:

$NETWORK1=VM Network$
$NETWORK2=Private Network$

vCenter: Specify the network the VM's NICs will be connected to.

SCVMM: Specify the logical network the VMs NICs will be connected to. If you have multiple virtual networks that are connected to the provided logical network you can specify $VIRTUALNETWORK to ensure that the proper one is selected. If $NETWORK is specified and $VIRTUALNETWORK isn't specified, then Commander chooses a matching virtual network.

Not supported for AWS or Microsoft Azure.

Syntax: Substitute <x> in the syntax with a number (1, 2, 3 and so on), as shown in the examples. Networks are assigned to the NICs in the order specified.

  • Supported for single-VM services only.
  • Returns the network name, not the network zone name.
  • Overrides the network zone specified on the request form. See Assign Network Zones.

$ORGANIZATION=<organization_name>

Example:

$ORGANIZATION=Verification$

Specify the organization for the VM when the Primary Owner is changed during a change request, and the Organization element doesn't appear on the form. The organization must be specified in order for the owner to have visibility of the VM. Supported only for change requests.

This parameter is ignored if the Organization form element appears on the change request form.

When multiple organizations are available, approvers can also use a drop-down menu on the approval landing page to specify the organization. The drop-down menu selection overrides the manually entered deployment parameter.

$VIRTUALNETWORK<x>=
<virtual_network_name>$

Example:

$VIRTUALNETWORK1=External Network$
$VIRTUALNETWORK2=Virtual Network$

Specify the virtual network the VM's NICs will be connected to. (By default, Commander chooses a matching virtual network that's a valid option for the logical network that was specified.)

Substitute <x> in the syntax with a number (1, 2, 3 and so on), as shown in the examples.

Supported for:

  • single-VM services only
  • SCVMM only

$VMNAME=<vm_name>$

Example:

$VMNAME=MyVMName

results in a VM named MyVMName

$VMNAME=My VM Name$

results in a VM named My VM Name

Multi-VM requests:

$VMNAME=MyVM #{uniqueNumber[3]}$

results in VMs named MyVM 001, MyVM 002 and so on.

Specify the deployed name for the VM.

Multi-VM requests: To ensure that multiple VMs in a request are successfully deployed with unique names, you must also specify the variable #{uniqueNumber[*]} as shown in the example.

See Syntax example: Adding custom attribute values to VM names.

For information on order of precedence for VM names, see Customize Naming Conventions.

Specify deployment parameters through REST

You can specify network deployment parameters for VMs through REST calls that are included in approval workflow steps and completion workflow steps.

Specifying deployment parameters using REST API calls allows you to assign unique IP addresses for each component in a service request. This differs from the approach of using substitution variables to assign IP addresses from comments, which only assigns one address to all components.

A script using REST API calls can also reach out to an IP Address Management (IPAM) if required.

The network deployment parameters that are set through Commander API calls take precedence over deployment parameters that may be set through substitution variables. For more information, see Specify Deployment Parameters for Services.

Access:

Configuration > Self-Service > Completion tab and add a Configure OS Networking step

OR

Configuration > Self-Service > Approval tab and add an Execute Approval Script step

Available to:

Approvers set in Approval and Completion Workflows

Administrator, Operator, Operator with Approval Access Rights

You can add network deployment parameters to a vCenter VM through the following Commander API URL pattern:

/rest/v3/service-requests/{service request ID}/services/{service name}/components/{component name}/deployment-parameters

Deployment Parameters through REST API

Parameter Syntax

Purpose

{
        "nics": [
            {
                "ip": "",
                "netmask": "",
                "gateway": "",
                "dns_primary": "",
                "dns_secondary": "",
                "network": ""
            }
         ]
}

Specify the IP address, Netmask, Gateway, DNS names and network for one or more NICs of the VM. The IP address, Netmask, Gateway, and DNS names properties must be configured for successful deployment. The network property is optional.

The specified IP, netmask, gateway, DNS primary server, and DNS secondary server will be applied to the VM specified in the REST URL.

Supported for:

  • multi-VM services
  • multi-NIC services
  • VMWare only

Example: Specify deployment parameters through REST calls

In the following example, the user wants to provision two vCenter VMs with component names "Ubuntu_16" and "Windows_10", each of which has two NICs (1, 2) in a single service ("acme_service") deployment request. The user also wants to supply configuration parameter for both components to each NIC using a script that will be invoked in the approval workflow.

The script submits two POST requests, one for each component in the service. These scripts are added to steps in approval workflows or command workflows. Note that these scripted requests are only supported for deployment requests; they aren't supported for change requests.

The first POST request URL contains the service request id (1), service name (acme_service) and name of the first component (Ubuntu_16):

/rest/v3/service-requests/1/services/acme_service/components/Ubuntu_16/deployment-parameters

The body of the request contains the following content:

{
       "nics": [
               {
                        "ip": "1.1.1.1",
                        "netmask": "255.255.0.0",
                        "gateway": "1.1.1.10",
                        "dns_primary": "1.1.1.20",
                        "dns_secondary": "1.1.1.21",
                        "network": "ralph_network1"
               },
               {
                        "ip": "1.1.1.2",
                        "netmask": "255.255.255.0",
                        "gateway": "1.1.1.11",
                        "dns_primary": "1.1.1.30",
                        "dns_secondary": "1.1.1.31",
                        "network": "ralph_network2"
               }
       ]}

The second POST request URL contains the service request id (1), service name (acme_service) and name of the second component (Windows_10):

/rest/v3/service-requests/1/services/acme_service/components/Windows_10/deployment-parameters

The body of the request contains this content: 

{
       "nics": [
               {
                       "ip": "1.1.1.3",
                       "netmask": "255.255.0.0",
                       "gateway": "1.1.1.10",
                       "dns_primary": "1.1.1.20",
                       "dns_secondary": "1.1.1.21",
                       "network": "sam_network1",
                       "virtual_network": "sam_vn1"
               },
               {
                       "ip": "1.1.1.4",
                       "netmask": "255.255.255.0",
                       "gateway": "1.1.1.11",
                       "dns_primary": "1.1.1.30",
                       "dns_secondary": "1.1.1.31",
                       "network": "sam_network2",
                       "virtual_network": "sam_vn2"
               }
       ]