Substitutions
Substitutions are used to define shorthand names that can replace complex expressions in the StyleBook making the StyleBook more readable.
Substitutions are also useful when the same expression or value is used repeatedly in the StyleBook, for example, a constant value. Using a substitution name for a parameter allows you to update only the substitution value instead of updating all occurrences of the parameter in the StyleBook which might be prone to error.
Substitutions are also used for defining mappings between values as described in examples later in this document.
Each substitution in the list is made up of a key and a value. The value can be a simple value, an expression, a function, or a map.
In the following example, two substitutions are defined. The first one is http-port that can be used as a shorthand for 8181. By using a substitution, you can refer to this in the rest of the StyleBook as $substitutions.http-port instead of 8181.
substitutions:
http-port: 8181
This allows you to specify a mnemonic name to a port number and define this port number in one place in the StyleBook, irrespective of the number of times it is used. If you want to modify the port number to 8080, you can modify it in the substitution section, and the change takes effect wherever the mnemonic name http-port is used. The following example shows how a substitution is used in a component.
components:
-
name: my-lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name + "-lb"
servicetype: HTTP
ipv46: $parameters.ip
port: $substitutions.http-port
lbmethod: $parameters.lb-alg
<!--NeedCopy-->
A substitution can also be a complex expression. The following example shows how two substitutions use expressions.
substitutions:
app-rule: HTTP.REQ.HEADER("X-Test-Application").EXISTS
app-name: str("acme-") + $parameters.name + str("-app")
<!--NeedCopy-->
A substitution expression can also use existing substitution expressions as shown in the following example.
substitutions:
http-port: 8181
app-name: str("acme-") + $parameters.name + str($substitutions.http-port) + str("-app")
<!--NeedCopy-->
Another useful feature of substitutions is maps, where you can map keys to values. The following is an example of a map substitution.
substitutions:
secure-port:
true: int("443")
false: int("80")
secure-protocol:
true: SSL
false: HTTP
<!--NeedCopy-->
The following example shows how to use the maps secure-port and secure-protocol.
components:
-
name: my-lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name + "-lb"
servicetype: $substitutions.secure-protocol[$parameters.is-secure]
ipv46: $parameters.ip
port: $substitutions.secure-port[$parameters.is-secure]
lbmethod: $parameters.lb-alg
<!--NeedCopy-->
Here, if the user of the StyleBook specifies the Boolean value “true” to the parameter is-secure, or selects the check box corresponding to this parameter in the NetScaler Console GUI, the servicetype property of this component is assigned the value SSL and the port property is assigned the value 443. However, if the user specifies “false” for this parameter or clears the corresponding check box in the NetScaler Console GUI, the servicetype property is assigned the value HTTP and the port is assigned the value 80.
The following example shows how to use substitutions as a function. A substitution function can take one or more arguments. Arguments can be of simple type for example, string, number, ipaddress, boolean, and other types.
substitutions:
form-lb-name(name): $name + “-lb”
In this example, we define a substitution function “form-lb-name” that takes a string argument called “name” and uses it to create a string that suffixes “-lb” to the string in the name argument. An expression using this substitution function can be written as:
$substitutions.form-lb-name("my")
It returns my-lb
Consider another example:
substitutions:
cspol-priority(priority): 10100 - 100 * $priority
The substitution cspol-priority is a function that takes an argument called priority and uses it to calculate a value. In the rest of the StyleBook, this substitution can be used as shown in the following example:
components:
-
name: cspolicy-binding-comp
type: ns::csvserver_cspolicy_binding
condition: not $parameters.is-default
properties:
name: $parameters.csvserver-name
policyname: $components.cspolicy-comp.properties.policyname
priority: $substitutions.cspol-priority($parameters.pool.priority)
<!--NeedCopy-->
The following is an example of a substitution called slist whose value is a list:
substitutions:
slist:
- a
- b
- c
<!--NeedCopy-->
The value of a substitution can also be a dictionary of key-value pairs as seen in the following example of a substitution called sdict below:
substitutions:
sdict:
a: 1
b: 2
c: 3
<!--NeedCopy-->
You can create more complex attributes by combining the lists and dictionaries. For example, a substitution called slistofdict returns a list of key - value pairs.
slistofdict:
-
a: $parameters.cs1.lb1.port
b: $parameters.cs1.lb2.port
-
a: $parameters.cs2.lb1.port
b: $parameters.cs2.lb2.port
<!--NeedCopy-->
But, in the following example, a substitution sdictoflist returns a key-value pair, where the value itself is another list.
sdictoflist:
a:
- 1
- 2
b:
- 3
- 4
<!--NeedCopy-->
In components, these substitutions may be used in condition, properties, repeat, repeat-condition constructs.
The following example of a component shows how a substitution can be used to specify the properties:
properties:
a: $substitutions.slist
b: $substitutions.sdict
c: $substitutions.slistofdict
d: $substitutions.sdictoflist
<!--NeedCopy-->
A use case for defining a substitution whose value is a list or a dictionary is when you are configuring a content switching virtual server and multiple load balancing virtual servers. Since all lb virtual servers tied to the same cs virtual server might have an identical configuration, you can use the substitution list and dictionary to build this configuration to avoid repeating that configuration for each lb virtual server.
The following example shows the substitution and the component in the cs-lb-mon StyleBooks to create a content switching virtual server configuration. While constructing the properties of cs-lb-mon StyleBooks, the complex substitution “lb-properties” specifies the properties of the lb virtual servers associated with the cs virtual server. The “lb-properties” substitution is a function that takes the name, service type, virtual IP address, port, and servers as parameters and generates a key-value pair as the value. In cs-pools component, we assign the value of this substitution to a lb-pool parameter for each pool.
substitutions:
cs-port[]:
true: int("80")
false: int("443")
lb-properties(name, servicetype, vip, port, servers):
lb-appname: $name
lb-service-type: $servicetype
lb-virtual-ip: $vip
lb-virtual-port: $port
svc-servers: $servers
svc-service-type: $servicetype
monitors:
-
monitorname: $name
type: PING
interval: $parameters.monitor-interval
interval_units: SEC
retries: 3
components:
-
name: cs-pools
type: stlb::cs-lb-mon
description: | Updates the cs-lb-mon configuration with the different pools provided. Each pool with rule result in a dummy LB vserver, cs action, cs policy, and csvserver_cspolicy_binding configuration.
condition: $parameters.server-pools
repeat: $parameters.server-pools
repeat-item: pool
repeat-condition: $pool.rule
repeat-index: ndx
properties:
appname: $parameters.appname + "-cs"
cs-virtual-ip: $parameters.vip
cs-virtual-port: $substitutions.cs-port($parameters.protocol == "HTTP")
cs-service-type: $parameters.protocol
pools:
-
lb-pool: $substitutions.lb-properties($pool.pool-name, "HTTP", "0.0.0.0", 0, $pool.servers)
rule: $pool.rule
priority: $ndx + 1
<!--NeedCopy-->
Substitution map
You can create substitutions that map keys to values. For example, consider a scenario where you want to define the default port (value) to be used for each protocol (key). For this task, write a substitution map as follows.
substitutions:
port:
HTTP: 80
DNS: 53
SSL: 443
<!--NeedCopy-->
In this example, HTTP is mapped to 80, DNS is mapped to 53, and SSL is mapped to 443. To retrieve the port of a certain protocol that is given as a parameter, use the expression
$substitutions.port[$parameters.protocol]
The expression returns a value based on the protocol specified by the user.
- If the key is HTTP, the expression returns 80
- If the key is DNS, the expression returns 53
- If the key is SSL, the expression returns 443
- If the key is not present in the map, the expression does not return any value
Iterate through substitution lists
In the following example, the StyleBook iterates through a substitution list called apps to create a set of lbvserver components and their corresponding service groups and bound servers.
substitutions:
apps:
-
name: lb1
vip: 1.2.3.4
vport: 80
protocol: HTTP
servers:
-
ip: 10.8.11.11
port: 8080
-
ip: 10.8.11.12
port: 8080
-
name: lb2
vip: 1.2.3.5
vport: 81
protocol: HTTP
servers:
-
ip: 10.9.11.28
port: 8080
-
ip: 10.9.11.29
port: 8181
components:
-
name: lbvserver-comp
type: ns::lbvserver
repeat: $substitutions.apps
repeat-item: app
properties:
name: $app["name"]
ipv46: $app["vip"]
port: $app["vport"]
servicetype: $app["protocol"]
components:
-
name: servicegroup-comp
type: ns::servicegroup
properties:
servicegroupname: $parent.properties.name + "-svg"
servicetype: HTTP
components:
-
name: servers-comp
type: ns::server
repeat: $app["servers"]
repeat-item: server
properties:
name: $server["ip"]
ipaddress: $server["ip"]
components:
-
name: servicegroup-servicegroupmember-binding-comp
type: ns::servicegroup_servicegroupmember_binding
properties:
servicegroupname: $parent.parent.properties.servicegroupname
servername: $parent.properties.name
port: $server["port"]
<!--NeedCopy-->