Product Documentation

StyleBook to create a basic load balancing configuration

May 24, 2018

In the previous example, you have built a basic StyleBook to create a load balancing virtual server. You can save this StyleBook with a different name and then update it to include additional parameters and components for a basic load balancing configuration. Save this StyleBook file as basic-lb-config.yaml.

In this section, you will design a new StyleBook that creates a load balancing configuration comprising of load balancing virtual server, a service group, and a list of services. It also binds the services to the service group and binds the service group to the virtual server.

Header

To build this StyleBook, you have to start by updating the header section. This section is similar to the one you created for load balancing virtual server StyleBook. In the header section, change the value of name to basic-lb-config. Also, update description and display-name to describe this StyleBook appropriately. You do not have to change the namespace and version values. Because you have changed the name, the combination of name, namespace, and version creates a unique identifier for this StyleBook in the system.

     name: basic-lb-config

     description: This StyleBook defines a simple load balancing configuration.

     display-name: Load Balancing Configuration

     namespace: com.example.stylebooks

     schema-version: "1.0"

     version: "0.1"

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"

Parameters

You have to update the parameters section to add two additional parameters to 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 remain the same.

     parameters:

       -

          name: name

          type: string

          label: Application Name

          description: Name of the application configuration

          required: true

      -

          name: ip

          type: ipaddress

          label: Application Virtual IP (VIP)

          description: Application VIP that the clients access          

          required: true

     -

          name: lb-alg

          type: string

          label: LoadBalancing Algorithm

          description: Choose the load balancing algorithm used for load balancing 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

In this example, the parameter svc-servers is added to accept a list of IP addresses of the services that represent the backend servers of the application. This 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 for svc-port parameter, if it is not specified by the user. 

Components

You have to also update the components section to define additional 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


In this example, the original component lbvserver-comp (from the previous example) now has a child component called svcg-comp. And, the svcg-comp component 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 static value for servicetype, while name gets its value from the input parameter. You refer to the parameter name defined in the parameters section by using $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 multiple 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 above example, you have used nesting of components inside each other to easily construct this configuration. In this particular case, nesting of components was not the only way of building the configuration. You could have achieved the same result without nesting, as shown below: 

     components:

      -

          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: $components.svcg-comp.properties.name

     -

          name: lbvserver-svg-binding-comp

          type: ns::lbvserver_servicegroup_binding

          properties:

                 name: $components.lbvserver-comp.properties.name

                 servicegroupname: $components.svcg-comp.properties.name

      -    

          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:

               name: $parameters.name + "-svcgrp"

               servicetype: HTTP
  

Here, all the components are at the same level (that is, they are not nested) but the result achieved (the NetScaler configuration generated) is the same as that of the nested components used earlier. Also, 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 multiple 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 "-comp" string. 

Outputs

The last section you can add to the new StyleBook is the outputs section where you specify what this StyleBook exposes to its users (or in other StyleBooks) after it is used to create a configuration. For example, you can specify in the outputs section to expose the lbvserver and the servicegroup configuration objects that would be 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

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 more flexibility as you can see 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. Run the contents of your StyleBook through the online tool http://www.yamllint.com/ to validate the YAML syntax.

The full content of the file basic-lb-config.yaml is reproduced below:

basic-lb-config.yaml Copy

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

    components:

      -

        name: svcg-comp

        type: ns::servicegroup

        properties:

          servicegroupname: $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.servicegroupname

            -

              name: members-svcg-comp

              type: ns::servicegroup_servicegroupmember_binding

              repeat: $parameters.svc-servers

              repeat-item: srv

              properties:

                ip: $srv

                port: $parameters.svc-port

                servicegroupname: $parent.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.lbvserver-comp.components.svcg-comp

    description: The component that builds the Nitro servicegroup configuration object

To start using your StyleBook to create configurations, you have to import it to NetScaler MAS 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.