Application Delivery Management

Substitutions

December 31, 2023

Contributed by:

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
<!--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 checkbox corresponding to this parameter in the Citrix 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 checkbox in the Citrix ADM 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)
<!--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 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
<!--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 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
<!--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

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Substitutions

December 31, 2023

Contributed by:

December 31, 2023

Contributed by:

Substitutions

In this article