Configure a desired set of service group members for a service group in one NITRO API call

Support is added to configure a desired set of service group members for a service group in one NITRO API call. A new API, Desired State API, is added to support this configuration. Using Desired State API, you can:

  • Provide a list of service group members in a single PUT request on “servicegroup_servicegroupmemberlist_binding” resource.
  • Provide their weight and state (optional) in that PUT request.
  • Effectively synchronize the appliance configuration with deployment changes around application servers.

The Citrix ADC appliance compares the requested desired member set with the configured member set. Then, it automatically binds the new members and unbinds the members that are not present in the request.

Note:

  • This feature is supported only for service groups of type API.
  • You can only bind IP address based services using Desired State API, domain name based services are not allowed.
  • Previously, only one service group member can be bound in a NITRO call.

Use case: Synchronize deployment changes to Citrix ADC appliance in large scale deployments, such as Kubernetes

In large scale and highly dynamic deployments (for example Kubernetes), the challenge is to keep the appliance configuration up-to-date with the rate of change of deployments to accurately serve the application traffic. In such deployments, controllers (Ingress or E-W Controller) are responsible for updating ADC configuration. Whenever there are changes to deployment, kube-api server sends the effective set of endpoints through ‘Endpoints event’ to the controller. The controller uses the Read-Delta-Modify approach where it performs the following:

  • Fetches the currently configured endpoint set (service group member set of a service group) for the service from ADC appliance.
  • Compares the configured endpoint set with the set in the received event.
  • Binds the new endpoints (service group members) or unbinds the deleted endpoints.

Because the rate of change and the size of services is high in this environment, this configuration method is not efficient and might delay configuration updates.

Desired State API solves this problem by accepting the intended member set for a service group in a single API, thereby effectively updating the configuration.

Create a service group of type API by using the CLI

At the command prompt, type;

add serviceGroup <serviceGroupName>@ <serviceType> [-autoScale <autoScale>]

Example:

add serviceGroup svg1 HTTP -autoScale API

You can configure the autoDisablegraceful and autoDisabledelay and autoScale parameters by using add serviceGroup or set serviceGroup command.

add serviceGroup <serviceGroupName>@ <serviceType> [-autoScale <autoScale>] [-autoDisablegraceful ( YES | NO)] [-autoDisabledelay <secs>]

add serviceGroup <serviceGroupName>@ <serviceType> [-autoScale (API |CLOUD | DISABLED| DNS |POLICY)]

set serviceGroup <serviceGroupName [-autoDisablegraceful ( YES | NO)] [-autoDisabledelay <secs>]

set serviceGroup <serviceGroupName [-autoScale (API |CLOUD | DISABLED| DNS |POLICY)]

Example:

add serviceGroup svg1 HTTP autoDisablegraceful YES -autoDisabledelay 100

add serviceGroup svg1 HTTP -autoScale API

set serviceGroup svg1 -autoDisablegraceful  YES -autoDisabledelay 100

set serviceGroup svg1 -autoScale API

Arguments

autoDisablegraceful

Indicates graceful shutdown of the service. If this option is enabled, the appliance waits for all outstanding connections to this service to be closed before deleting the service. For clients that already have a persistent session on the system, new connections or requests continue to be sent to this service. The service member is deleted only if there are no outstanding connections. Default value: NO

autoDisabledelay

Indicates the time allowed (in seconds) for a graceful shutdown. During this period new connections or requests continue to be sent to this service for clients that already have a persistent session on the system. Connections or requests from new clients that do not have persistence sessions on the system are not sent to the service. Instead, they are load balanced among other available services. After the delay time expires, the service member is deleted.

autoScale API

Enables using Desired State API for binding the member set to an intended service group. You can set the service group from non-autoscale to autoscale type of Desired State API, if all provided conditions match.

The set serviceGroup autoScale command might fail if the existing member bindings meet any of these conditions:

  • If the server bound to the service group is either a name server or a domain-based server.
  • If the name of the server bound to the service group is an IP address, then it must match the actual server IP address. In the following example, the server name and server IP address do not match.
    • CLI: add server IPaddress server name
    • Example: add server 1.2.3.4 4.3.2.1
  • If the loopback server name is anything other than 127.0.0.1 or 0000:0000:0000:0000:0000:0000:0000:0001.
  • If you choose different types of autoscale (Cloud, API, DNS, and Policy) in a set serviceGroup command and add serviceGroup command.

Important:

  • The autoDisablegraceful and autoDisabledelay parameters are applicable only for the service groups of autoscale type “API” and “CLOUD.”
  • If the autoDisablegraceful or the autoDisabledelay parameters are not configured, then service members are deleted immediately.

Unbind a service group member gracefully

If any of the service group members is not in the desired state list, those members are gracefully unbound based on the autoDisablegraceful or autoDisabledelay parameter configuration.

  • If one of these parameters is set, then the service group member is unbound gracefully.
  • If none of these parameters are set, then the service group member is unbound immediately.

Note:

  • Service group members identified for graceful unbind are displayed only when the show servicegroup command is executed.
  • You cannot perform any operation (such as set, unset) on the service group member identified for graceful unbind.

The following figure displays a sample show servicegroup command.

Sample show service group command

Create a service group of type API by using the GUI

1. Navigate to Traffic Management > Load Balancing > Service Groups, and click Add.

2. In AutoScale Mode, select API.

Configure graceful shutdown or a time delay for an API type service group by using the GUI

1. Navigate to Traffic Management > Load Balancing > Service Groups.

Basic settings of service groups

2. In AutoScale Mode, select API.

3. In Auto Disable Graceful, select YES.

4. In Auto Disable Delay, enter the wait time for a graceful shutdown.

Note: The Auto Disable Graceful or Auto Display Delay fields are enabled only if you select API or CLOUD in AutoScale Mode.