Citrix NetScaler Virtual Server Discovery

Overview

The Citrix Discovery Service automates the discovery of virtual servers from a Citrix NetScaler appliance using its NITRO REST API. The service connects to a target NetScaler instance, enumerates all configured load balancing virtual servers (lbvserver), resolves their backend service members, and synchronizes this data into the platform's database.

This component solves the problem of keeping the platform's service catalog up-to-date with the configuration of an external load balancer. It provides a mechanism to idempotently create, update, and deactivate service representations based on the live state of the NetScaler appliance.

The discovery process is initiated by an administrative action, which invokes the runDiscovery method with a target instance identifier. The service then:

1. Retrieves credentials for the target NetScaler instance.
2. Connects to the NetScaler NITRO API.
3. Fetches all virtual server and backend member configurations.
4. Persists the discovered data to the s2r_discovered_service table within a single database transaction.
5. Returns a DiscoveryResult object summarizing the outcome, including any non-fatal errors encountered.

How it Works

The discovery process follows a precise sequence of operations to ensure data consistency and provide detailed feedback. The entire persistence phase is transactional; either all database changes are committed, or none are.

flowchart TD
    subgraph "Discovery Run"
        A[Start] --> B(Load Credentials);
        B --> C(Login to Citrix NITRO API);
        C --> D(List Virtual Servers);
        D --> E{For each server};
        E -- Yes --> F(Get Backend Members);
        F --> E;
        E -- No --> G(Logout from NITRO API);
    end

    subgraph "Database Synchronization"
        G --> H(Begin Transaction);
        H --> I{For each discovered server};
        I -- Yes --> J{Server exists in DB?};
        J -- Yes --> K(Update Server Record);
        J -- No --> L(Insert New Server Record);
        K --> I;
        L --> I;
        I -- No --> M(Mark Unseen Servers as Inactive);
        M --> N(Commit Transaction);
    end

    subgraph "Result"
       N --> O(Return DiscoveryResult);
       B -- Fail --> O;
       C -- Fail --> O;
       D -- Fail --> G;
       N -- Fail --> P(Rollback & Return Error);
       P --> O;
    end

1. Load Credentials: The process begins by loading the connection details (host, port, credentials) for the specified gatewayType and instanceName from the LbConnectorCredentialService.
2. NITRO API Login: A session is established with the NetScaler NITRO API using the loaded credentials. A failed login terminates the run immediately.
3. Enumerate Virtual Servers: The service makes a GET /nitro/v1/config/lbvserver request to fetch all load balancing virtual servers.
4. Resolve Backend Members: For each virtual server discovered, the service performs two additional lookups:
   • It retrieves all service bindings for the virtual server to get the names of the backend services.
   • For each bound service name, it fetches the service's details, including its IP address and port.
   • Errors in resolving a specific backend member are recorded but do not stop the discovery of other members or virtual servers.
5. Persist Data: The collected information is synchronized with the s2r_discovered_service database table in a single transaction.
   • For each discovered virtual server, the service checks if a record with the same gateway_type, instance_name, and vendor_service_id (the virtual server's name) already exists.
   • If a record exists, it is updated with the latest information, and its last_seen_at timestamp is refreshed.
   • If no record exists, a new one is inserted.
6. Deactivate Stale Records: After processing all discovered servers, the service marks any existing records for the target instance as inactive (is_active = false) if they were not found in the current discovery run. This prunes services that have been removed from the NetScaler appliance.
   • Edge Case: If a discovery run returns zero virtual servers, all existing active services for that instance are marked as inactive. However, if the run is interrupted by an error after a successful login (e.g., session expiration), the deactivation step is skipped to prevent accidental data loss.
7. Logout: The service attempts to log out from the NITRO API session. This is a best-effort action performed in a finally block.
8. Return Result: A DiscoveryResult object is returned, containing counters for discovered, new, updated, and inactive services, along with a list of any non-fatal errors that occurred.

API Reference

The service exposes a single public method, runDiscovery, to initiate a discovery run.

runDiscovery Method

This method executes a full discovery and synchronization pass for a specific Citrix NetScaler instance.

DiscoveryResult runDiscovery(String gatewayType, String instanceName)

Parameters

Returns

Returns a DiscoveryResult object detailing the outcome of the run.

Throws

DiscoveryResult Object

This object encapsulates the results of a discovery run.

Database Persistence

The primary side effect of the discovery service is the population of the s2r_discovered_service table. The service performs idempotent "upserts" to keep this table synchronized with the NetScaler appliance.

s2r_discovered_service Table Schema

Troubleshooting

The service is designed to be resilient, capturing errors without halting the entire process where possible. Errors are logged and returned in the errors list of the DiscoveryResult object.

See Also

• Load Balancer Connector Credentials: Documentation on how to configure and manage credentials for connecting to load balancer instances.

All SOAP-to-REST docs