Config Sets: The Next Generation of Declarative Nitro API
Config Sets bridge the gap between the Nitro API and the Next-Gen API's declarative model. They allow you to configure advanced NetScaler features — expressed as raw Nitro entities — within the same desired-state framework as the App-Centric API. This is designed for scenarios where the feature or granularity you need is not yet natively available through the App-Centric model.
A
config_set wraps a collection of related Nitro objects (vservers, servicegroups, servers, bindings, etc.) as a single desired-state unit. The system validates and commits the configuration synchronously, then reconciles it against the installed state asynchronously — the same behavior as App-Centric resources.
Use Case
To illustrate the config_sets API, let's configure a basic load-balancing setup with a VIP and backend servers. The config_sets API enables you to define all related objects as a single configuration unit.
POST /mgmt/api/nextgen/v1/config_sets
{
"config_set": {
"name": "app1",
"config": {
"server": [
{
"name": "192.168.10.11",
"ipaddress": "192.168.10.11"
},
{
"name": "192.168.10.14",
"ipaddress": "192.168.10.14"
}
],
"servicegroup": [
{
"servicegroupname": "app1-_default-sg",
"servicetype": "HTTP"
}
],
"lbvserver": [
{
"name": "app1-_default-lbvserver",
"ipv46": "70.122.23.11",
"port": 443,
"lbmethod": "ROUNDROBIN",
"servicetype": "SSL"
}
],
"lbvserver_servicegroup_binding": [
{
"name": "app1-_default-lbvserver",
"servicegroupname": "app1-_default-sg"
}
],
"servicegroup_servicegroupmember_binding": [
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.11",
"port": 80
},
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.14",
"port": 80
}
],
"sslvserver_sslcertkey_binding": [
{
"vservername": "app1-_default-lbvserver",
"certkeyname": "app1_cert"
}
]
}
}
}
Let's say we want to update the configuration to add more servers or make other changes. We can simply issue another API call to add more servers as follows:
PUT /mgmt/api/nextgen/v1/config_sets/app1
{
"config_set": {
"name": "app1",
"config": {
"server": [
{
"name": "192.168.10.11",
"ipaddress": "192.168.10.11"
},
{
"name": "192.168.10.14",
"ipaddress": "192.168.10.14"
},
{
"name": "192.168.10.15",
"ipaddress": "192.168.10.15"
},
{
"name": "192.168.10.16",
"ipaddress": "192.168.10.16"
}
],
"servicegroup": [
{
"servicegroupname": "app1-_default-sg",
"servicetype": "HTTP"
}
],
"lbvserver": [
{
"name": "app1-_default-lbvserver",
"ipv46": "70.122.23.11",
"port": 443,
"lbmethod": "ROUNDROBIN",
"servicetype": "SSL"
}
],
"lbvserver_servicegroup_binding": [
{
"name": "app1-_default-lbvserver",
"servicegroupname": "app1-_default-sg"
}
],
"servicegroup_servicegroupmember_binding": [
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.11",
"port": 80
},
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.14",
"port": 80
},
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.15",
"port": 80
},
{
"servicegroupname": "app1-_default-sg",
"servername": "192.168.10.16",
"port": 80
}
],
"sslvserver_sslcertkey_binding": [
{
"vservername": "app1-_default-lbvserver",
"certkeyname": "app1_cert"
}
]
}
}
}
This shows how to add two new servers (192.168.10.15 and 192.168.10.16) to the existing configuration by updating the config_set with a PUT request.
Listing Config Sets
To retrieve all config sets:
GET /mgmt/api/nextgen/v1/config_sets
Pagination
When managing a large number of config sets, use
pageno and pagesize to paginate results. pageno specifies the page number (starting from 1) and pagesize specifies the number of config sets returned per page.
Retrieve the first 10 config sets:
GET /mgmt/api/nextgen/v1/config_sets?pageno=1&pagesize=10
Retrieve the second page of 10:
GET /mgmt/api/nextgen/v1/config_sets?pageno=2&pagesize=10
Count
To retrieve only the total number of config sets without fetching the full list, use
count=yes:
GET /mgmt/api/nextgen/v1/config_sets?count=yes
Response:
{
"__count": 20
}
Shareable Config Sets
By default, the Nitro entities defined in a config_set are exclusively owned by that config_set. Setting
shareable: true marks those entities as shared resources that can be referenced by other config_sets without causing conflicts.
This is particularly useful for resources that are common across multiple applications — such as an SSL certificate chain. Multiple application config_sets may bind to the same certificate, but only one config_set should define and manage the underlying certificate files and certkey objects. Marking that config_set as
shareable allows other config_sets to coexist without attempting to take exclusive ownership of the same entities.
Example: Shared SSL certificate chain
First, create a shareable config_set that uploads the certificate files and creates the certkey objects:
POST /mgmt/api/nextgen/v1/config_sets
{
"config_set": {
"name": "cert_chain",
"shareable": true,
"config": {
"systemfile": [
{
"filename": "rootcert.cert",
"filecontent": "<base64-encoded-content>",
"filelocation": "/nsconfig/ssl",
"fileencoding": "BASE64"
},
{
"filename": "intermediate.cert",
"filecontent": "<base64-encoded-content>",
"filelocation": "/nsconfig/ssl",
"fileencoding": "BASE64"
},
{
"filename": "servercert.cert",
"filecontent": "<base64-encoded-content>",
"filelocation": "/nsconfig/ssl",
"fileencoding": "BASE64"
},
{
"filename": "servercert.key",
"filecontent": "<base64-encoded-content>",
"filelocation": "/nsconfig/ssl",
"fileencoding": "BASE64"
}
],
"sslcertkey": [
{
"certkey": "rootcert.certck",
"cert": "rootcert.cert"
},
{
"certkey": "intermediate.certck",
"cert": "intermediate.cert",
"linkcertkeyname": "rootcert.certck"
},
{
"certkey": "appcert",
"cert": "servercert.cert",
"key": "servercert.key",
"linkcertkeyname": "intermediate.certck"
}
]
}
}
}
Multiple application config_sets can now reference
appcert in their SSL bindings without conflicting with each other:
POST /mgmt/api/nextgen/v1/config_sets
{
"config_set": {
"name": "app1",
"config": {
"sslvserver_sslcertkey_binding": [
{
"vservername": "app1-_default-csvserver",
"certkeyname": "appcert"
}
]
}
}
}
Config Set Statistics
The statistics endpoint returns real-time runtime statistics for the Nitro entities within a config_set — such as connection counts, request/response throughput, and health state for lbvservers and service group members.
GET /mgmt/api/nextgen/v1/config_sets/{config_set-name}/statistics
Example:
GET /mgmt/api/nextgen/v1/config_sets/app1/statistics
Response:
{
"config_set": {
"name": "app1",
"statistics": {
"lbvserver": [
{
"name": "app1-_default-lbvserver",
"primaryipaddress": "70.122.23.11",
"primaryport": 443,
"type": "SSL",
"state": "DOWN",
"actsvcs": "0",
"inactsvcs": "2",
"vslbhealth": "0",
"tothits": "0",
"hitsrate": 0,
"totalrequests": "0",
"requestsrate": 0,
"totalresponses": "0",
"responsesrate": 0,
"curclntconnections": "0",
"cursrvrconnections": "0",
"totspillovers": "0",
"cltresponsetimeapdex": 1.0
}
],
"servicegroup": [
{
"servicegroupname": "app1-_default-sg",
"state": "ENABLED",
"servicetype": "HTTP",
"servicegroupmember": [
{
"servicegroupname": "app1-_default-sg?192.168.10.11?80",
"primaryipaddress": "192.168.10.11",
"primaryport": 80,
"state": "DOWN",
"totalrequests": "0",
"requestsrate": 0,
"cursrvrconnections": "0",
"curclntconnections": "0"
},
{
"servicegroupname": "app1-_default-sg?192.168.10.14?80",
"primaryipaddress": "192.168.10.14",
"primaryport": 80,
"state": "DOWN",
"totalrequests": "0",
"requestsrate": 0,
"cursrvrconnections": "0",
"curclntconnections": "0"
}
]
}
]
}
}
}
Limitations
-
Statistics are only available for entity types that support them. Entities such as
server,sslcertkey, andsystemfiledo not have runtime statistics and will not appear in the response. -
Read-only. The statistics endpoint is GET-only — it cannot be used to reset or modify counters.
Config Set Status
When you create or update a config_set, the system validates and commits the configuration synchronously but applies it to the NetScaler data plane asynchronously. The config_status endpoint lets you track the progress of that asynchronous reconciliation.
GET /mgmt/api/nextgen/v1/config_sets/{config_set-name}/config_status
The response includes an overall
state for the config_set and a tasks array describing the stages executed.
State values
| State | Description |
|---|---|
ACCEPTED |
The config_set was received, validated, and committed to the database. Reconciliation with the data plane has not yet started or is in progress. |
INSTALLED |
The config_set has been fully applied to the NetScaler data plane. This is the expected steady state after a successful create or update. |
INSTALL_FAILED |
Applying the config_set to the data plane failed. Check the tasks array for which stage failed and why. |
UNINSTALL_PENDING |
A delete request has been received and is queued for processing. |
UNINSTALLED |
The config_set has been successfully removed from the data plane. |
UNINSTALL_FAILED |
Removing the config_set from the data plane failed. |
Task stages
The
tasks array captures the pipeline of operations executed during reconciliation. Each task has a stage and a state.
| Stage | Description |
|---|---|
Compute Differential Config |
The system calculates the difference between the desired state (what you submitted) and the current state on the data plane. Only the delta is applied, not the full config. |
Apply Differential Config |
The computed delta is applied to the NetScaler data plane. |
Compute Rollback Config |
If Apply Differential Config fails, the system computes a rollback config to restore the previous known-good state. |
Apply Rollback Config |
The rollback config is applied to the data plane to recover from the failed apply. |
Task state values
| State | Description |
|---|---|
PENDING |
The task has been queued but execution has not started yet. |
INPROGRESS |
The task is currently executing. |
COMPLETED |
The task finished successfully. |
DIFF_FAILED |
The diff computation failed. Only applies to the Compute Differential Config stage. This usually indicates a conflict or inconsistency between the desired state and the data plane state. |
ERROR |
The task encountered an error during execution. Applies to Apply Differential Config, Compute Rollback Config, and Apply Rollback Config stages. |
Examples
Successfully installed
The config_set has been fully reconciled with the data plane:
{
"status": {
"description": "Progress status for CONFIG_SET: app1",
"state": "INSTALLED",
"tasks": [
{
"stage": "Compute Differential Config",
"state": "COMPLETED"
},
{
"stage": "Apply Differential Config",
"state": "COMPLETED"
}
]
}
}
Reconciliation in progress
The config_set has been accepted and the system is computing the diff:
{
"status": {
"description": "Progress status for CONFIG_SET: app1",
"state": "ACCEPTED",
"tasks": [
{
"stage": "Compute Differential Config",
"state": "INPROGRESS"
}
]
}
}
Install failed — diff computation failed
The system could not compute a valid differential config:
{
"status": {
"description": "Progress status for CONFIG_SET: app1",
"state": "INSTALL_FAILED",
"tasks": [
{
"stage": "Compute Differential Config",
"state": "DIFF_FAILED"
}
]
}
}
Install failed — apply failed with rollback
The config was applied but failed on the data plane. The system attempted a rollback to restore the previous state:
{
"status": {
"description": "Progress status for CONFIG_SET: app1",
"state": "INSTALL_FAILED",
"tasks": [
{
"stage": "Compute Differential Config",
"state": "COMPLETED"
},
{
"stage": "Apply Differential Config",
"state": "ERROR"
},
{
"stage": "Compute Rollback Config",
"state": "COMPLETED"
},
{
"stage": "Apply Rollback Config",
"state": "COMPLETED"
}
]
}
}
Limitations
-
Application-specific scope only. Config Sets are intended for objects tied to a specific application. Global configuration entities are outside the scope of Config Sets and must be configured using the Nitro API directly. For example, global HTTP parameter settings cannot be configured through the Next-Gen API — see ns httpParam for the corresponding Nitro configuration.