Product Documentation

Substitutions

The substitutions section is used to define shorthand names for complex expressions that can be used in the rest of the StyleBook to make reading the StyleBook easier. They are also useful when the same expression or value is repeated more than once in the StyleBook, for example, a constant value. Using a substitution name for this value allows you to update only the substitution value when this value needs to be changed rather than updating it at every location it appears in the StyleBook, which could 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 as well as 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 will take 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

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

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

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

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

This implies that if the user of the StyleBook specifies the Boolean value “true” to the parameter is-secure, or selects the checkbox corresponding to this parameter in the NetScaler MAS 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 checkbox in the NetScaler MAS 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 should 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 new 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”)

which 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)**

Substitution can also be made up of a key and a value. The value can be a simple value, an expression, a function, a map, a list, or a dictionary.

The following is an example of a substitution called ‘slist’ whose value is a list:

substitutions:

  slist:

    - a

    - b

    - c

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

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

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

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 when specify the properties:

    properties:

      a: $substitutions.slist

      b: $substitutions.sdict

      c: $substitutions.slistofdict

      d: $substitutions.sdictoflist

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 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” specify 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 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

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

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

Substitutions

In this article