How to Create Your Own StyleBooks

Mar 15, 2018

You can write your own StyleBook for your deployment, import it to NetScaler MAS, and create configuration objects. You can also use API to create configurations from your StyleBooks.

Before you begin

Before you begin creating StyleBooks, make sure you have knowledge of the following:

  • NITRO API
  • YAML

StyleBook files use the YAML format. For information about the YAML format, see http://learn.getgrav.org/advanced/yaml.

The following is a list of YAML guidelines you must be aware of while creating StyleBooks:

  • YAML is case sensitive.

  • YAML requires proper indentation

  • Use <spacebar> key to create proper indentation. Do not use <tab> key. Using <tab> key creates compilation error while importing your StyleBook to MAS.

  • Do not use strings within quotation marks. Include the string within quotation marks only if a string contains punctuation marks (dashes, colons, and so on.) If you want to interpret a number as a string, either include the number within quotation marks or use the str() built-in function of StyleBooks.
  • Literals like YES/Yes/yes/Y/y/NO/no/No/n/N, ON/On/on/OFF/Off/off, and TRUE/true/truthy/FALSE/False/false/falsely are considered Booleans, and are equivalent to true and false respectively. To interpret them as strings, include them within quotation marks. For example: “YES”, “No”, “True”, “False”, and so on.

Note

Before importing your StyleBook file into NetScaler MAS, it is recommended that you validate if your file is compliant with the YAML format. To validate your file, you can use the online tool: http://www.yamllint.com/

Anatomy of a StyleBook

Writing StyleBooks requires that you understand the grammar, syntax, and structure of StyleBooks. A typical StyleBook has the following sections:

  • Header: This section lets you define the identity of a StyleBook and describe what it does. This is a mandatory section.

  • Import StyleBooks: This section lets you declare which other StyleBook you want to refer to from your current StyleBook. Importing NetScaler NITRO configuration StyleBooks or other StyleBooks is required to write a StyleBook. This is a mandatory section.

  • Parameters: This section lets you define the parameters you require in your StyleBook to create a configuration. It describes the input that your StyleBook takes. This is an optional section.

  • Components: This section lets you define the entities (configuration objects) that are created by the StyleBook for a specific configuration. This section is considered as the core of a StyleBook. Components generally use the input provided in the parameters section to adapt the configuration generated by the StyleBook. This is an optional section.

    A StyleBook may have a parameters section, or a components section, or both. A StyleBook with only the parameters section is useful to define a list of parameters that can be used by other StyleBooks. This promotes reusability of parameter groups across a set of StyleBooks. A StyleBook with only a components section may be used when you want to specify the values for attributes in the StyleBook instead of defining parameters to take user input.

  • Outputs: While the parameters section defines the inputs of the StyleBook, this optional section defines its outputs. In this optional outputs section, you can specify the components that you want to expose to users creating a configuration from this StyleBook and to other StyleBooks that import this StyleBook. Users and importing StyleBooks can then reference the properties of the exposed components.

  • Operations: A StyleBook may contain an optional section to enable Analytics in NetScaler MAS on any virtual server that is part of the StyleBook.

The following figure shows a simple outline of a StyleBook.

localized image

The examples in the following sections help you learn about the grammar and structure of a StyleBook and how to write StyleBooks with increasing levels of complexity.

StyleBook to create a load balancing virtual server

In this example, you design a basic StyleBook that creates a load balancing virtual server of HTTP protocol type and listening on port 80. The virtual server name, IP address, and load balancing method parameters accept user-defined values, that is, they are the parameters of the StyleBook.

The first six lines of a StyleBook comprise the header section. In this example, the header section is written as follows:

name: lb-vserver
description: This StyleBook defines a load balancing virtual server configuration.
display-name: Load Balancing Virtual Server (HTTP)
namespace: com.example.stylebooks
schema-version: "1.0"
version: "0.1"

The header section includes the following details:

  • name: A name for this StyleBook.
  • description: A description defining what this StyleBook does. This description appears on NetScaler MAS.
  • display-name: A descriptive name for the StyleBook that appears on NetScaler MAS.
  • namespace: A namespace forms part of a unique identifier for a StyleBook to avoid name collisions.
  • schema-version: Always takes the value “1.0” in this release.
  • version: The version number of the StyleBook. You can change the version number when you update the StyleBook.

The combination of name, namespace, and version uniquely identifies a StyleBook in the system. You cannot have two StyleBooks with the same combination of name, namespace, and version in NetScaler MAS. However, you can have two StyleBooks with the same name and version but different namespaces, or with the same namespace and version but different names.

Note

Consider that you have updated your StyleBook and you have an updated version number. Now if you are referring to (that is, if you are importing) this StyleBook in other StyleBooks, ensure to update the version number in other StyleBooks too, so that they use the correct version of the imported StyleBook.

Import StyleBooks

The section after header is called “import-stylebooks.” In this section, you must declare the namespace and version number of any other StyleBook that you want to refer to in your current StyleBook. This enables you to import and reuse other StyleBooks instead of rebuilding the same configuration in your own StyleBook.

In this example, the import-stylebooks section is written as follows:

import-stylebooks:
-
namespace: netscaler.nitro.config
prefix: ns
version: "10.5"

Every StyleBook must refer to the netscaler.nitro.config namespace if it uses any of the NITRO configuration objects directly. This namespace contains all the NetScaler NITRO types, such as lbvserver.As software versions 10.5 and later are supported, you can use your StyleBook to create and run configurations on any NetScaler instance running release 10.5 and later.

The prefix used in the import-stylebooks section is a shorthand to refer to the combination of namespace and version. In this case, ns refers to netscaler.nitro.config of version 10.5. In the later sections of your StyleBook, instead of using the namespace and version to refer to the imported StyleBook, you can use the prefix string chosen, for example, ns, in the example above.

The version used in the StyleBooks is the NetScaler NITRO version. A StyleBook that is based on Nitro version X can be used to configure any NetScaler that is version X or higher.

Note

To ensure that your StyleBooks can be used to configure any NetScaler instance of version 10.5 or later, Citrix recommends that for maximum compatibility you should import the Nitro 10.5 namespace in your StyleBooks that directly use Nitro built-in StyleBooks (namespace: netscaler.nitro.config, version: 10.5).

It is important that a StyleBook that imports other StyleBooks need to be based on a Nitro version that is at the same or higher version than the StyleBooks it imports. For example, a StyleBook that is based on Nitro version 10.5 cannot depend on or use or import a StyleBook that is based on 11.1. But a StyleBook based on version 11.1 can import a StyleBook based on any version less than 11.1.  

It is also possible that a StyleBook that doesn’t import the Nitro namespace at all. That means a StyleBook need not directly define Nitro components but can import (depend on) StyleBooks that defines Nitro components. The StyleBook that imports other StyleBooks always acquires the highest Nitro version in the hierarchy of its dependencies and could therefore be used to configure NetScalers that are of that version or higher.

Parameters

The parameters section lets you declare all the parameters that you need in your StyleBook. You, as the StyleBook developer, have to decide what is the input that you want the users of your StyleBook to specify. In this example, you have built your StyleBook in a way that requires its users to provide the name of the virtual server, its IP address, and the load balancing method.

The parameters section would look as follows:

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 (method) used for load balancing client request between the application servers.
  allowed-values:
   - ROUNDROBIN
   - LEASTCONNECTION
   default: ROUNDROBIN

Note

If you do not provide the label of a parameter, then NetScaler MAS uses the name attribute when displaying this parameter. You must always define a label for your parameters so that you can control how they show up in NetScaler MAS.

When using the APIs however, the parameter is designated by its name.

In this section, you have declared three parameters indicated by their name attribute values - name for virtual server name, ip for IP address of the virtual server, and lb-alg for the load balancing method.

  • type refers to the type of value these parameters can take. For example, name and lb-alg can take a string value and the ip value has to be of type ip address. Parameters in a StyleBook can be of any of the following built-in types:

    • string: An array of characters. If a length is not specified, the string value can take any number of characters. However, you can limit the length of a string type by using the attributes min-length and max-length.

    • number: An integer number. You can specify the minimum and maximum number that this type can take by using the attributes min-value and max-value.

    • boolean: Can be either true or false. Also, note that all the literals are considered by YAML as booleans (for example, Yes or No).

    • ipaddress: A string that represents a valid IPv4 or IPv6 address.

    • tcp-port: A number between 0 and 65535 that represents a TCP or UDP port.

    • password: An opaque/secret string value. When NetScaler MAS displays a value for this parameter, it is shown as asterisks (*****).

    • certfile: A certificate file.

    • keyfile: A certificate private key file.

    • file: A parameter of this type requires the user to upload a file, for example, a certificate or key file.

    • object: Consists of multiple elements and each of these elements is a parameter. This type can be used to group multiple related parameters under one parent parameter.

  • required states whether a parameter is mandatory or optional. If it is set to true, the parameter is mandatory and the user has to provide a value for this parameter when creating configurations using this StyleBook. By default, all parameters are optional. In this example, name and ip are mandatory parameters while lb-alg is an optional parameter, the default value of which is “ROUNDROBIN.”

Use the default attribute to assign a default value to an optional parameter. While creating a configuration, if a user does not specify a value, the default value is used. For example, for the lb-alg parameter, the default value is ROUNDROBIN.

Use the allowed-values attribute to define specific values that a user can choose from when creating a configuration. In this example, you have specified two values for the lb-alg parameter - ROUNDROBIN and LEASTCONNECTION.

When you import your StyleBook and use it, NetScaler MAS displays a form with these three parameters. The fields displayed for name and ip allow string and ipaddress type of value to be entered, and the lb-alg field is displayed as a drop-down list with ROUNDROBIN selected as the default value.

Note

In addition to built-in types, a parameter can have another StyleBook as its type. This is a way of reusing parameters defined in other StyleBooks.

Components

The last section in this StyleBook is called the components section and is considered as the most important section in the StyleBook. In this section, you define the configuration objects that have to be created by the SyleBook.

For this example, you have to write the components section as follows:

components:
 -
  name: lbvserver-comp
  type: ns::lbvserver
  properties:
   name: $parameters.name
   servicetype: HTTP
   ipv46: $parameters.ip
   port: 80
   lbmethod: $parameters.lb-alg

This example contains only one component. The main attributes of a component are name, type, and properties. The type of a component determines what properties this component provides. Components are of two types:

  • Built-in type: This type is provided by the system and you do not have to define it, for example, the NITRO entity types “lbvserver” or “servicegroup.” In this example,  you are using a built-in component type.

  • Composite type: This type is the StyleBook that you created and imported into NetScaler MAS, or the Default StyleBook that is shipped with NetScaler MAS. You can learn more about Composite StyleBooks in Create a Composite StyleBook.

In this example, you have defined a component called lbvserver-comp. This component is of type ns::lbvserver (a built-in Nitro type), where “ns” is the prefix that refers to the namespace  netscaler.nitro.config and version 10.5 that you had specified in the import-stylebooks section, and “lbvserver” is a Nitro resource in this namespace.

The properties defined here are the attributes of the “lbvserver” resource. To learn more about all the available NetScaler Nitro resources and their attributes, see the NetScaler NITRO REST API documentation.

The properties in this section include the mandatory attributes of the “lbvserver” resource and allows you to specify values for these attributes. In this example, you are specifying static values for servicetype and port while the name, ipv46, and lbmethod properties get their values from the input parameters. In the rest of the StyleBook, you can refer to the parameter names defined in the parameters section by using $parameters.<parameter-name> expression, for example, $parameters.ip.

Note

By convention, the prefix “ns” is always used to designate a NetScaler Nitro namespace in the “import-stylebooks” section. Though it is not mandatory, Citrix recommends to use the same convention in your own StyleBooks for consistency.

Build your StyleBook

Now that you have defined all the required sections of this StyleBook, bring them all together to build your first StyleBook. Copy and paste the StyleBook content to a text editor, and then save the file as lb-vserver.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 lb-vserver.yaml is reproduced below:

name: lb-vserver
namespace: com.example.stylebook
version: "1.0"
display-name: Load Balancing Virtual Server (HTTP)
description: "This stylebook defines a very simple load balancing HTTP virtual server configuration"
schema-version: "1.0"

import-stylebooks:
 -
  namespace: netscaler.nitro.config
  version: "10.5"
  prefix: ns
 -
  namespace: com.citrix.adc.stylebooks
  version: "1.0"
  prefix: stlb

parameters:
 -
  name: name
  label: "Application Name"
  description: "Give a name to the application configuration."
  type: string
  required: true
 -
  name: vip-ipaddress
  label: "Load Balancer IP Address"
  description: "The Application VIP that clients access"
  type: ipaddress
  required: true
 -
  name: lb-alg
  label: LB Algorithm
  description: Load Balancing Algorithm
  type: string
  default: ROUNDROBIN
  allowed-values:
   - ROUNDROBIN
   - LEAST-CONNECTION

components:
 -
  name: lbvserver-comp
  description: This StyleBook component (a Builtin Nitro StyleBook) builds a NetScaler lbvserver configuration object.
  type: ns::lbvserver
  properties:
   name: $parameters.name
   ipv46: $parameters.vip-ipaddress
   lbmethod: $parameters.lb-alg
   servicetype: HTTP
   port: 80

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 (using the import-stylebooks construct.) Or, you can modify this StyleBook to include more parameters and components as described in the next section.

StyleBook to create a basic load balancing configuration

In the previous section, 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:

    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.

Create a composite StyleBook

An important and powerful feature of StyleBooks is that they can be used as building blocks for other StyleBooks. A StyleBook can be imported into another StyleBook and it can be referred to as a type that is used by components of the second StyleBook similar to a Nitro built-in StyleBook.

For example, you can use the basic-lb-config StyleBook that you built in the previous section, to build another StyleBook called composite-example. To use the “basic-lb-config” StyleBook, you have to import it in the new StyleBook in the import-stylebooks section.

The new StyleBook would look as follows:

    name: composite-example
    namespace: com.example.stylebooks
    version: "0.1"
    display-name: Load Balancing Virtual Server (HTTP/RoundRobin)
    description: This StyleBook defines a RoundRobin load balancing configuration with a monitor.
    schema-version: "1.0"
    import-stylebooks:
      -
        namespace: netscaler.nitro.config
        version: "10.5"
        prefix: ns
      -
        namespace: com.example.stylebooks
        version: "0.1"
        prefix: stlb
    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: svc-servers
        type: ipaddress[]
        label: Application Server IPs
        description: The IP addresses of all the servers of this application
        required: true
    components:
      -
        name: basic-lb-comp
        type: stlb::basic-lb-config
        description: This component's type is another StyleBook that builds the NetScaler lbvserver, servicegroups and services configuration objects.
        properties:
          name: $parameters.name
          ip: $parameters.ip
          svc-servers: $parameters.svc-servers
      -
        name: monit-comp
        type: ns::lbmonitor
        description: This component is a basic Nitro type (a Builtin StyleBook) that builds the NetScaler monitor configuration object.
        properties:
          monitorname: $parameters.name + "-mon"
          type: HTTP
          respcode:str("200")
          httprequest: "'GET /'"
          lrtm: ENABLED
          secure: "YES"
        components:
          -
            name: monit-svcgrp-bind-comp
            type: ns::servicegroup_lbmonitor_binding
            properties:
              servicegroupname: $components.basic-lb-comp.outputs.servicegroup-comp.properties.servicegroupname
              monitor_name: $parent.properties.monitorname

In the import-stylebooks section, you import the basic-lb-config StyleBook by using its namespace and version, referred to with the prefix “stlb”.

In the components section, two components are defined. The first component is of type stlb::basic-lb-config, where “basic-lb-config” is the name of the StyleBook you created in StyleBook to create a basic load balancing configuration. The properties that are defined for this component correspond to the mandatory parameters declared in the basic-lb-config StyleBook. You can, however, use any parameter of the StyleBook (both required and optional.) Instead of re-building a lbvserver, a service group, and service and service group bindings, you import the StyleBook that does all of this as a component and use it to create these configuration objects in the new StyleBook.

StyleBook adds a second component “monit-comp” that uses the attributes of the Nitro resource “lbmonitor” (a built-in StyleBook) to create a monitor configuration object. It also has a sub-component “monit-svcgrp-bind-comp” to create the binding configuration object that binds the monitor to the servicegroup created in the first component. Because the servicegroup component created in the “basic-lb-config” StyleBook is exposed as an output, this StyleBook can access it using the expression $components.basic-lb-comp.outputs.servicegroup-comp. This is an example of how the outputs section can be used by the importing StyleBooks to have access to components in the imported StyleBooks that they would not have been able to access otherwise.

Next, copy and paste the StyleBook content to a text editor, and then save the file as composite-example.yaml. Run the contents of your StyleBook through the online tool http://www.yamllint.com/ to validate the YAML syntax. Then, import it to NetScaler MAS and create one or several configurations by using this StyleBook.

Customize your StyleBook by using GUI attributes

You can add GUI attributes in the parameters section of your StyleBook to make the fields intuitive when displayed on NetScaler MAS.

Example 1: You can add a descriptive name for the parameter by using the label attribute, and add a tooltip for this parameter by using the description attribute.

name: ip
label: Virtual Server IP Address
description: IP address of the virtual server that represents the load balanced application.
type: ipaddress
required: true

Example 2: If you have a parameter of type object, you can define the layout by using the gui attribute. In this example, the layout is a collapsible object where fields are displayed in two columns.

name: svcg-advanced
label: Advanced Application Server Settings
type: object
required: false
gui:
  collapse_pane: true
  columns: 2

Example 3: Some StyleBooks are used as building blocks for other StyleBooks and you may not want to display these StyleBooks on NetScaler MAS since they are not intended to be used directly by users. For this, you can use the private attribute to prevent a StyleBook from being listed on NetScaler MAS.

name: basic-lb-config
description: This stylebook defines a simple load balancing configuration.
display-name: Load Balancing Configuration
namespace: com.example.stylebooks
private: true
schema-version: "1.0"
version: "0.1"