StyleBook to create a basic load balancing configuration
In this section, you design a StyleBook that creates a load balancing configuration which includes a load balancing virtual server, a service group, and a list of services. The StyleBook binds the services to the service group and binds the service group to the virtual server.
To create a basic load balancing configuration, use the example StyleBook, lb-vserver that you created in StyleBook to create a load balancing virtual server and save it as basic-lb-config.yaml.
Header
To build this StyleBook, update the header section. This section is similar to the header section that you created in StyleBook to create a load balancing virtual server.
Change the value of name to basic-lb-config. Update description and display-name to describe the StyleBook. You do not have to change the namespace and version values. Because you’ve changed the name, a unique identifier for this StyleBook is created in the system.
name: basic-lb-config
namespace: com.example.stylebooks
version: "0.1"
display-name: Load Balancing Configuration
description: This StyleBook defines a simple load balancing configuration.
schema-version: "1.0"
<!--NeedCopy-->
Import StyleBooks
The import-stylebooks section remains the same. It refers to the netscaler.nitro.config namespace to use the NITRO configuration objects.
import-stylebooks:
-
namespace: netscaler.nitro.config
prefix: ns
version: "10.5"
<!--NeedCopy-->
Parameters
Update the parameters section to add two more parameters.
The parameters define the list of services or servers and the port on which the services listen to. The first three parameters name, ip, and lb-alg stay the same.
parameters:
-
name: name
type: string
label: Application Name
description: Give a name to the application configuration.
required: true
-
name: ip
type: ipaddress
label: Application Virtual IP (VIP)
description: The Application VIP that clients access
required: true
-
name: lb-alg
type: string
label: LoadBalancing Algorithm
description: Choose the loadbalancing algorithm (method) used for loadbalancing client requests between the application servers.
allowed-values:
- ROUNDROBIN
- LEASTCONNECTION
default: ROUNDROBIN
-
name: svc-servers
type: ipaddress[]
label: Application Server IPs
description: The IP addresses of all the servers of this application
required: true
-
name: svc-port
type: tcp-port
label: Server Port
description: The TCP port open on the application servers to receive requests.
default: 80
<!--NeedCopy-->
The parameter, svc-servers, is added to accept a list of IP addresses of the back end servers of the application. svc-servers is a mandatory parameter as indicated by required: true.
The second parameter, svc-port, denotes the port number on which the servers listen. The default port number is 80 unless specified by the user.
Components
You have to also update the components section to define more components such that they use the two new parameters and build the complete load balancing configuration.
For this example, you have to write the components section as follows:
components:
-
name: lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name + "-lb"
servicetype: HTTP
ipv46: $parameters.ip
port: 80
lbmethod: $parameters.lb-alg
components:
-
name: svcg-comp
type: ns::servicegroup
properties:
name: $parameters.name + "-svcgrp"
servicetype: HTTP
components:
-
name: lbvserver-svg-binding-comp
type: ns::lbvserver_servicegroup_binding
properties:
name: $parent.parent.properties.name
servicegroupname: $parent.properties.name
-
name: members-svcg-comp
type: ns::servicegroup_servicegroupmember_binding
repeat: $parameters.svc-servers
repeat-item: srv
properties:
ip: $srv
port: str($parameters.svc-port)
servicegroupname: $parent.properties.name
<!--NeedCopy-->
In this example, the original component lbvserver-comp (from the previous example) now has a child component called svcg-comp. The svcg-comp component also has two child components within it. Nesting a component within another component allows the nested component to create configuration objects by referring to attributes in the parent component. The nested component can create one or more objects for each object created in the parent component.
The svcg-comp component is used to create a service group on the NetScaler instance by using the values provided for the attributes of the resource servicegroup. In this example, you are specifying the static value for servicetype, while name gets its value from the input parameter. Refer to the parameter name defined in the parameters section by using the $parameters.name + “-svcgrp” notation, where “-svcgrp” is appended (concatenated) to the user-defined name.
The component svcg-comp has two child components, lbvserver-svg-binding-comp and members-svcg-comp.
The first child component, lbvserver-svg-binding-comp, is used to bind a configuration object between the service group created by its parent component and the load balancing virtual server (lbvserver) created by the parent’s parent component. The $parent notation, also called the parent reference, is used to refer to entities in the parent components. For example, servicegroupname: $parent.properties.name refers to the service group created by the parent component svcg-comp, and name: $parent.parent.properties.name refers to the virtual server created by the parent’s parent component lbvserver-comp.
The members-svcg component is used to bind configuration objects between the list of services to the service group created by the parent component. The creation of binding configuration objects is achieved by using the repeat construct of StyleBook to iterate over the list of servers specified in the parameter svc-servers. During the iteration, this StyleBook component creates a NITRO configuration object of type servicegroup_servicegroupmember_binding for each service (referred to as srv in the repeat-item construct) in the service group, and it sets the ip attribute in each NITRO configuration object to the IP address of the corresponding server.
Generally, you can use the repeat and repeat-item constructs in a component to make that component build multiple configuration objects of the same type. You can assign a variable name to the repeat-item construct, for example, srv, to designate the current value in the iteration. This variable name is referred to in the properties of the same component or in child components as $<varname>, for example $srv.
In the preceding example, the nesting of components help to easily construct the configuration. You can also build the configuration without nesting as shown in the following example:
components:
-
name: lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name + "-lb"
servicetype: HTTP
ipv46: $parameters.ip
port: 80
lbmethod: $parameters.lb-alg
-
name: svcg-comp
type: ns::servicegroup
properties:
servicegroupname: $parameters.name + "-svcgrp"
servicetype: HTTP
-
name: lbvserver-svg-binding-comp
type: ns::lbvserver_servicegroup_binding
properties:
name: $components.lbvserver-comp.properties.name
servicegroupname: $components.svcg-comp.properties.servicegroupname
-
name: members-svcg-comp
type: ns::servicegroup_servicegroupmember_binding
repeat: $parameters.svc-servers
repeat-item: srv
properties:
ip: $srv
port: 80
servicegroupname: $components.svcg-comp.properties.servicegroupname
<!--NeedCopy-->
Here, even though the components are not nested, the generated NetScaler configuration is the same as that of the nested components used earlier.
The order in which the components are declared in the StyleBook does not impact the order of creation of the configuration objects. In this example, the components svcg-comp and lbvserver-comp, even though declared last, must be built before building the second component lbvserver-svg-binding-comp because there are forward references to these components in the second component.
Note
By convention, the names of StyleBooks, parameters, substitutions, components, and outputs are in lowercase. When they contain many words, they are separated by a “-“ character. For example
lb-bindings,app-name,rewrite-config, and so on. Another convention is to suffix component names with-compstring.
Outputs
In this section, you need to specify what the StyleBook exposes to the users (or in other StyleBooks) after it creates a configuration. For example, you can specify to expose the lbvserver and the servicegroup configuration objects that are created by this StyleBook.
outputs:
-
name: lbvserver-comp
value: $components.lbvserver-comp
description: The component that builds the Nitro lbvserver configuration object
-
name: servicegroup-comp
value: $components.svcg-comp
description: The component that builds the Nitro servicegroup configuration object
<!--NeedCopy-->
The outputs section of a StyleBook is optional. A StyleBook does not need to return outputs. However, by returning some internal components as outputs, it allows any StyleBooks that import this StyleBook to have more flexibility. This functionality is useful when creating a composite StyleBook.
Note
It is a good practice to expose an entire component of the StyleBook in the outputs section, rather than just a single property of a component (for example, expose the whole $components.lbvserver-comp rather than just the name, $components.lbvserver-comp.properties.name). Also add a description to the output explaining what the specific output represents.
Build your StyleBook
Now that you have defined all the required sections of this StyleBook, bring them all together to build your second StyleBook. You have already saved this StyleBook file as basic-lb-config.yaml. Citrix recommends that you use the built-in YAML validator in StyleBooks to validate and import the YAML content.
The full content of the file basic-lb-config.yaml is reproduced as follows:
name: basic-lb-config
namespace: com.example.stylebooks
version: "0.1"
display-name: Load Balancing Configuration
description: This StyleBook defines a simple load balancing configuration.
schema-version: "1.0"
import-stylebooks:
-
namespace: netscaler.nitro.config
version: "10.5"
prefix: ns
parameters:
-
name: name
type: string
label: Application Name
description: Give a name to the application configuration.
required: true
-
name: ip
type: ipaddress
label: Application Virtual IP (VIP)
description: The Application VIP that clients access
required: true
-
name: lb-alg
type: string
label: LoadBalancing Algorithm
description: Choose the loadbalancing algorithm (method) used for loadbalancing client requests between the application servers.
allowed-values:
- ROUNDROBIN
- LEASTCONNECTION
default: ROUNDROBIN
-
name: svc-servers
type: ipaddress[]
label: Application Server IPs
description: The IP addresses of all the servers of this application
required: true
-
name: svc-port
type: tcp-port
label: Server Port
description: The TCP port open on the application servers to receive requests.
default: 80
components:
-
name: lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name + "-lb"
servicetype: HTTP
ipv46: $parameters.ip
port: 80
lbmethod: $parameters.lb-alg
-
name: svcg-comp
type: ns::servicegroup
properties:
servicegroupname: $parameters.name + "-svcgrp"
servicetype: HTTP
-
name: lbvserver-svg-binding-comp
type: ns::lbvserver_servicegroup_binding
properties:
name: $components.lbvserver-comp.properties.name
servicegroupname: $components.svcg-comp.properties.servicegroupname
-
name: members-svcg-comp
type: ns::servicegroup_servicegroupmember_binding
repeat: $parameters.svc-servers
repeat-item: srv
properties:
ip: $srv
port: 80
servicegroupname: $components.svcg-comp.properties.servicegroupname
outputs:
-
name: lbvserver-comp
value: $components.lbvserver-comp
description: The component that builds the Nitro lbvserver configuration object
-
name: servicegroup-comp
value: $components.svcg-comp
description: The component that builds the Nitro servicegroup configuration object
<!--NeedCopy-->
To start using your StyleBook to create configurations, you have to import it to NetScaler Console and then use it. For more information, see How to Use User-Defined StyleBooks.
You can also import this StyleBook into other StyleBooks and use its properties as described in the next section.