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.
Header
The first six lines of a StyleBook comprise the header section. In this example, the header section is written as follows:
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"
<!--NeedCopy-->
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 Console.
- display-name: A descriptive name for the StyleBook that appears on NetScaler Console.
- 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 Console. 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"
<!--NeedCopy-->
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, 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, it is 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
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
<!--NeedCopy-->
Note
If you do not provide the label of a parameter, then NetScaler Console 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 Console.
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-algcan 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 Console 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 Console 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 StyleBook.
For this example, you have to write the components section as follows:
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
<!--NeedCopy-->
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
lbvserverorservicegroup. 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 Console, or the default StyleBook that is shipped with NetScaler Console. 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. 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 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
<!--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 (using the import-stylebooks construct.) Or, you can modify this StyleBook to include more parameters and components as described in the next section.