Application Delivery Management

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 the occurrences of the parameter in the StyleBook which might be prone to errors.

Substitutions are also used for defining mappings between values.

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

You can 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-->

This implies that 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 ADM 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 ADM GUI, servicetype is assigned the value of HTTP and the port is assigned the value of 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, IP address, boolean, and other types.

substitutions:

  form-lb-name(name): $name + “-lb”

In this example, a substitution function “form-lb-name” is defined 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 is 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 is shown as:

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

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
<!--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 can be used in condition, properties, repeat, and 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. As all the load balancing virtual servers tied to the same content switching virtual server might have an identical configuration, use a substitution list and dictionary to build the configuration to avoid repeating the same configuration for every load balancing 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 load balancing virtual servers associated with the ccontent switching 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 the cs-pools component, you can assign the value of this substitution to the 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 doesn’t 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-->
Substitutions