community.network.netscaler_lb_vserver module – Manage load balancing vserver configuration
Note
This module is part of the community.network collection (version 3.3.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.network.
To use it in a playbook, specify: community.network.netscaler_lb_vserver.
Synopsis
Manage load balancing vserver configuration
This module is intended to run either on the ansible control node or a bastion (jumpserver) with access to the actual netscaler instance
Requirements
The below requirements are needed on the host that executes this module.
nitro python sdk
Parameters
Parameter |
Comments |
|---|---|
Apply AppFlow logging to the virtual server. Choices:
|
|
Enable or disable user authentication. Choices:
|
|
Fully qualified domain name (FQDN) of the authentication virtual server to which the user must be redirected for authentication. Make sure that the Authentication parameter is set to Minimum length = 3 Maximum length = 252 |
|
Enable or disable user authentication with HTTP 401 responses. Choices:
|
|
Name of the authentication profile to be used when authentication is turned on. |
|
Name of an authentication virtual server with which to authenticate users. Minimum length = 1 Maximum length = 252 |
|
Backup load balancing method. Becomes operational if the primary load balancing me thod fails or cannot be used. Valid only if the primary method is based on static proximity. Choices:
|
|
Time period for which backup persistence is in effect. Minimum value = Maximum value = |
|
If this option is enabled while resolving DNS64 query AAAA queries are not sent to back end dns server. Choices:
|
|
Route cacheable requests to a cache redirection virtual server. The load balancing virtual server can forward requests only to a transparent cache redirection virtual server that has an IP address and port combination of *:80, so such a cache redirection virtual server must be configured on the appliance. Choices:
|
|
Idle time, in seconds, after which a client connection is terminated. Minimum value = Maximum value = |
|
Any comments that you might want to associate with the virtual server. |
|
Mode in which the connection failover feature must operate for the virtual server. After a failover, established TCP connections and UDP packet flows are kept active and resumed on the secondary appliance. Clients remain connected to the same servers. Available settings function as follows:
Choices:
|
|
Use this parameter to specify the cookie name for |
|
Length of the token to be extracted from the data segment of an incoming packet, for use in the token method of load balancing. The length of the token, specified in bytes, must not be greater than 24 KB. Applicable to virtual servers of type TCP. Minimum value = Maximum value = |
|
Offset to be considered when extracting a token from the TCP payload. Applicable to virtual servers, of type TCP, using the token method of load balancing. Must be within the first 24 KB of the TCP payload. Minimum value = Maximum value = |
|
Name of the DB profile whose settings are to be applied to the virtual server. Minimum length = 1 Maximum length = 127 |
|
Enable database specific load balancing for MySQL and MSSQL service types. Choices:
|
|
When set to When set to Note that due to limitations of the underlying NITRO API a Choices:
|
|
If the primary virtual server goes down, do not allow it to return to primary status until manually enabled. Choices:
|
|
This argument is for enabling/disabling the Choices:
|
|
Name of the DNS profile to be associated with the VServer. DNS profile properties will be applied to the transactions processed by a VServer. This parameter is valid only for DNS and DNS-TCP VServers. Minimum length = 1 Maximum length = 127 |
|
Flush all active transactions associated with a virtual server whose state transitions from UP to DOWN. Do not enable this option for applications that must complete their transactions. Choices:
|
|
Number of bytes to consider for the hash value used in the URLHASH and DOMAINHASH load balancing methods. Minimum value = Maximum value = |
|
Threshold in percent of active services below which vserver state is made down. If this threshold is 0, vserver state will be up even if one bound service is up. Minimum value = Maximum value = |
|
Name of the HTTP profile whose settings are to be applied to the virtual server. Minimum length = 1 Maximum length = 127 |
|
How the NetScaler appliance responds to ping requests received for an IP address that is common to one or more virtual servers. Available settings function as follows:
Note: This parameter is available at the virtual server level. A similar parameter, ICMP Response, is available at the IP address level, for IPv4 addresses of type VIP. To set that parameter, use the add ip command in the CLI or the Create IP dialog box in the GUI. Choices:
|
|
Insert an HTTP header, whose value is the IP address and port number of the virtual server, before forwarding a request to the server. The format of the header is <vipHeader>: <virtual server IP address>_<port number >, where vipHeader is the name that you specify for the header. If the virtual server has an IPv6 address, the address in the header is enclosed in brackets ([ and ]) to separate it from the port number. If you have mapped an IPv4 address to a virtual server’s IPv6 address, the value of this parameter determines which IP address is inserted in the header, as follows:
Choices:
|
|
IP mask, in dotted decimal notation, for the IP Pattern parameter. Can have leading or trailing non-zero octets (for example, |
|
IP address pattern, in dotted decimal notation, for identifying packets to be accepted by the virtual server. The IP Mask parameter specifies which part of the destination IP address is matched against the pattern. Mutually exclusive with the IP Address parameter. For example, if the IP pattern assigned to the virtual server is If a destination IP address matches more than one IP pattern, the pattern with the longest match is selected, and the associated virtual server processes the request. For example, if virtual servers |
|
IPv4 or IPv6 address to assign to the virtual server. |
|
Use Layer 2 parameters (channel number, MAC address, and VLAN ID) in addition to the 4-tuple (<source IP>:<source port>::<destination IP>:<destination port>) that is used to identify a connection. Allows multiple TCP and non-TCP connections with the same 4-tuple to co-exist on the NetScaler appliance. Choices:
|
|
Load balancing method. The available settings function as follows:
Also available are a number of hashing methods, in which the appliance extracts a predetermined portion of the request, creates a hash of the portion, and then checks whether any previous requests had the same hash value. If it finds a match, it forwards the request to the service that served those previous requests. Following are the hashing methods:
Choices:
|
|
Default syntax expression identifying traffic accepted by the virtual server. Can be either an expression (for example, |
|
Integer specifying the priority of the listen policy. A higher number specifies a lower priority. If a request matches the listen policies of more than one virtual server the virtual server whose listen policy has the highest priority (the lowest priority number) accepts the request. Minimum value = Maximum value = |
|
Redirection mode for load balancing. Available settings function as follows:
You can use either the Choices:
|
|
This option is used to retain vlan information of incoming packet when macmode is enabled. Choices:
|
|
Maximum number of members expected to be present when vserver is used in Autoscale. Minimum value = Maximum value = |
|
Minimum number of members expected to be present when vserver is used in Autoscale. Minimum value = Maximum value = |
|
For a load balancing virtual server of type Choices:
|
|
Character set that the virtual server advertises to clients. |
|
MySQL protocol version that the virtual server advertises to clients. |
|
Server capabilities that the virtual server advertises to clients. |
|
MySQL server version string that the virtual server advertises to clients. Minimum length = 1 Maximum length = 31 |
|
Name for the virtual server. Must begin with an ASCII alphanumeric or underscore Minimum length = 1 |
|
IPv4 subnet mask to apply to the destination IP address or source IP address when the load balancing method is Minimum length = 1 |
|
Name of the network profile to associate with the virtual server. If you set this parameter, the virtual server uses only the IP addresses in the network profile as source IP addresses when initiating connections with servers. Minimum length = 1 Maximum length = 127 |
|
Number of requests, or percentage of the load on existing services, by which to increase the load on a new service at each interval in slow-start mode. A non-zero value indicates that slow-start is applicable. A zero value indicates that the global RR startup parameter is applied. Changing the value to zero will cause services currently in slow start to take the full traffic as determined by the LB method. Subsequently, any new services added will use the global RR factor. |
|
Interval, in seconds, between successive increments in the load on a new service or a service whose state has just changed from DOWN to UP. A value of 0 (zero) specifies manual slow start. Minimum value = Maximum value = |
|
Units in which to increment load at each interval in slow-start mode. Choices:
|
|
The password with which to authenticate to the netscaler node. |
|
Which protocol to use when accessing the nitro API objects. Choices:
|
|
Time in seconds until a timeout error is thrown when establishing a new session with Netscaler Default: 310 |
|
The username with which to authenticate to the netscaler node. |
|
The ip address of the netscaler appliance where the nitro API calls will be made. The port can be specified with the colon (:). E.g. 192.168.1.1:555. |
|
Oracle server version. Choices:
|
|
Persist AVP number for Diameter Persistency. In case this AVP is not defined in Base RFC 3588 and it is nested inside a Grouped AVP, define a sequence of AVP numbers (max 3) in order of parent to child. So say persist AVP number X is nested inside AVP Y which is nested in Z, then define the list as Z Y X. Minimum value = |
|
Backup persistence type for the virtual server. Becomes operational if the primary persistence mechanism fails. Choices:
|
|
Type of persistence for the virtual server. Available settings function as follows:
Choices:
|
|
Persistence mask for IP based persistence types, for IPv4 virtual servers. Minimum length = 1 |
|
Port number for the virtual server. Range
|
|
By turning on this option packets destined to a vserver in a cluster will not under go any steering. Turn this option for single packet request response mode or when the upstream device is performing a proper RSS for connection based distribution. Choices:
|
|
Process traffic with the push virtual server that is bound to this load balancing virtual server. Choices:
|
|
Expression for extracting a label from the server’s response. Can be either an expression or the name of a named expression. |
|
Allow multiple Web 2.0 connections from the same client to connect to the virtual server and expect updates. Choices:
|
|
Name of the load balancing virtual server, of type PUSH or SSL_PUSH, to which the server pushes updates received on the load balancing virtual server that you are configuring. Minimum length = 1 |
|
Number of IP addresses that the appliance must generate and assign to the virtual server. The virtual server then functions as a network virtual server, accepting traffic on any of the generated IP addresses. The IP addresses are generated automatically, as follows:
Note: The Range parameter assigns multiple IP addresses to one virtual server. To generate an array of virtual servers, each of which owns only one IP address, use brackets in the IP Address and Name parameters to specify the range. For example: add lb vserver my_vserver[1-3] HTTP 192.0.2.[1-3] 80. Minimum value = Maximum value = |
|
When set to YES, this option causes the DNS replies from this vserver to have the RA bit turned on. Typically one would set this option to YES, when the vserver is load balancing a set of DNS servers thatsupport recursive queries. Choices:
|
|
Rewrite the port and change the protocol to ensure successful HTTP redirects from services. Choices:
|
|
URL to which to redirect traffic if the virtual server becomes unavailable. WARNING! Make sure that the domain in the URL does not match the domain specified for a content switching policy. If it does, requests are continuously redirected to the unavailable virtual server. Minimum length = 1 |
|
Default syntax expression specifying which part of a server’s response to use for creating rule based persistence sessions (persistence type RULE). Can be either an expression or the name of a named expression. Example:
|
|
Route Health Injection (RHI) functionality of the NetSaler appliance for advertising the route of the VIP address associated with the virtual server. When Vserver RHI Level (RHI) parameter is set to VSVR_CNTRLD, the following are different RHI behaviors for the VIP address on the basis of RHIstate (RHI STATE) settings on the virtual servers associated with the VIP address:
Choices:
|
|
Use network address translation (NAT) for RTSP data connections. Choices:
|
|
If The module will not save the configuration on the netscaler node if it made no changes. Choices:
|
|
List of services along with the weights that are load balanced. The following suboptions are available. |
|
Service to bind to the virtual server. Minimum length = 1 |
|
Weight to assign to the specified service. Minimum value = Maximum value = |
|
List of service groups along with the weights that are load balanced. The following suboptions are available. |
|
The service group name bound to the selected load balancing virtual server. |
|
Integer specifying the weight of the service. A larger number specifies a greater weight. Defines the capacity of the service relative to the other services in the load balancing configuration. Determines the priority given to the service in load balancing decisions. Minimum value = Maximum value = |
|
Protocol used by the service (also called the service type). Choices:
|
|
Perform load balancing on a per-packet basis, without establishing sessions. Recommended for load balancing of intrusion detection system (IDS) servers and scenarios involving direct server return (DSR), where session information is unnecessary. Choices:
|
|
This argument decides the behavior incase the service which is selected from an existing persistence session has reached threshold. Choices:
|
|
Action to be performed if spillover is to take effect, but no backup chain to spillover is usable or exists. Choices:
|
|
Type of threshold that, when exceeded, triggers spillover. Available settings function as follows:
Choices:
|
|
If spillover occurs, maintain source IP address based persistence for both primary and backup virtual servers. Choices:
|
|
Timeout for spillover persistence, in minutes. Minimum value = Maximum value = |
|
Threshold at which spillover occurs. Specify an integer for the Minimum value = Maximum value = |
|
The name of the ssl certificate that is bound to this service. The ssl certificate must already exist. Creating the certificate can be done with the community.network.netscaler_ssl_certkey module. This option is only applicable only when |
|
The state of the resource being configured by the module on the netscaler node. When present the resource will be created if needed and configured according to the module’s parameters. When absent the resource will be deleted from the netscaler node. Choices:
|
|
Name of the TCP profile whose settings are to be applied to the virtual server. Minimum length = 1 Maximum length = 127 |
|
Integer value that uniquely identifies the traffic domain in which you want to configure the entity. If you do not specify an ID, the entity becomes part of the default traffic domain, which has an ID of 0. Minimum value = Maximum value = |
|
Time period for which a persistence session is in effect. Minimum value = Maximum value = |
|
TOS ID of the virtual server. Applicable only when the load balancing redirection mode is set to TOS. Minimum value = Maximum value = |
|
Number of bits to consider in an IPv6 destination or source IP address, for creating the hash that is required by the Minimum value = Maximum value = |
|
Persistence mask for IP based persistence types, for IPv6 virtual servers. Minimum value = Maximum value = |
|
If Choices:
|
|
Name for the inserted header. The default name is vip-header. Minimum length = 1 |
Notes
Note
For more information on using Ansible to manage Citrix NetScaler Network devices see https://www.ansible.com/ansible-netscaler.
Examples
# Netscaler services service-http-1, service-http-2 must have been already created with the netscaler_service module
- name: Create a load balancing vserver bound to services
delegate_to: localhost
community.network.netscaler_lb_vserver:
nsip: 172.18.0.2
nitro_user: nsroot
nitro_pass: nsroot
validate_certs: no
state: present
name: lb_vserver_1
servicetype: HTTP
timeout: 12
ipv46: 6.93.3.3
port: 80
servicebindings:
- servicename: service-http-1
weight: 80
- servicename: service-http-2
weight: 20
# Service group service-group-1 must have been already created with the netscaler_servicegroup module
- name: Create load balancing vserver bound to servicegroup
delegate_to: localhost
community.network.netscaler_lb_vserver:
nsip: 172.18.0.2
nitro_user: nsroot
nitro_pass: nsroot
validate_certs: no
state: present
name: lb_vserver_2
servicetype: HTTP
ipv46: 6.92.2.2
port: 80
timeout: 10
servicegroupbindings:
- servicegroupname: service-group-1
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
List of differences between the actual configured object and the configuration specified in the module Returned: failure Sample: {“clttimeout”: “difference. ours: (float) 10.0 other: (float) 20.0”} |
|
list of logged messages by the module Returned: always Sample: [“message 1”, “message 2”] |
|
Message detailing the failure reason Returned: failure Sample: “Action does not exist” |
Authors
George Nikolopoulos (@giorgos-nikolopoulos)