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-vservernamespace: com.example.stylebookversion: "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 Citrix ADM.
• display-name: A descriptive name for the StyleBook that appears on Citrix ADM.
• 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 Citrix ADM. 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 Citrix ADC 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 Citrix ADC 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 Citrix ADC NITRO version. A StyleBook that is based on NITRO version X can be used to configure any Citrix ADC that is version X or higher.

Note

To ensure that your StyleBooks can be used to configure any Citrix ADC 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 Citrix ADCs 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 Citrix ADM 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 Citrix ADM.

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 Citrix ADM 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, Citrix ADM 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 Citrix ADC 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 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 Citrix ADM, or the default StyleBook that is shipped with Citrix ADM. 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 Citrix ADC NITRO resources and their attributes, see the Citrix ADC 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 Citrix ADC 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-vservernamespace: com.example.stylebookversion: "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: stlbparameters: -  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-CONNECTIONcomponents: -  name: lbvserver-comp  description: This StyleBook component (a Builtin Nitro StyleBook) builds a Citrix ADC 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 Citrix ADM 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.