Dynamic IP address allocation through NetScaler IPAM Controller

Last published : Nov 02, 2026
NetScaler Kubernetes Gateway Controller supports IP address allocation for Kubernetes Gateway resources using NetScaler IPAM Controller. When IPAM is enabled, Gateways that do not have a static IP address configured in spec.addresses automatically receive a Virtual IP (VIP) address from NetScaler IPAM controller. With this feature, the need to manually assign and track IP addresses for each Gateway is eliminated.
Related information
Traffic management

Prerequisites

Before configuring dynamic IP address allocation through NetScaler IPAM Controller, ensure the following:
  • NetScaler Kubernetes Gateway Controller is deployed with the Helm value gatewayController.ipam set to true (for example, --set gatewayController.ipam=true). For more information, see Deploy NetScaler Kubernetes Gateway Controller.
    Helm does not update a CRD that already exists in the cluster. If the vips.citrix.com CRD was installed by an earlier NetScaler Helm chart, apply the CRD file of the NetScaler Kubernetes Gateway Controller chart before you enable IPAM, for example kubectl apply -f https://raw.githubusercontent.com/netscaler/netscaler-helm-charts/master/netscaler-kubernetes-gateway-controller/crds/crds.yaml. An earlier vip CRD might not accept Gateways, and then no IP address is allocated to a Gateway.
  • NetScaler IPAM Controller is deployed in the cluster with the IP address ranges. For information on how to deploy NetScaler IPAM controller with the desired IP address ranges, see NetScaler IPAM Controller Installation Guide.
    When configuring the VIP_RANGE, you can define named ranges (for example, Production, Staging) that can be referenced from Gateway annotations, and unnamed ranges that serve as the default pool.

Configuration

Perform the following steps to configure dynamic IP address allocation through NetScaler IPAM Controller.

Step 1: Create a GatewayClass

Create a GatewayClass with NetScaler Kubernetes Gateway Controller name.
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: citrix-gateway-class
spec:
  controllerName: citrix.com/nsgc-controller

Step 2: Create a Gateway

Create a Gateway without spec.addresses. NetScaler IPAM controller automatically allocates an IP address from the configured pool.

Basic Gateway (default IP range)

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: citrix-gateway-class
  listeners:
    - name: http-listener
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All

Gateway with a named IP range

Use the gateway.citrix.com/ipam-range annotation on the Gateway to allocate an IP address from a specific named range:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  annotations:
    gateway.citrix.com/ipam-range: "Production"
spec:
  gatewayClassName: citrix-gateway-class
  listeners:
    - name: https-listener
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: All
The range name in the annotation must match a named range defined in VIP_RANGE configuration of NetScaler IPAM controller.

Verify the IP address allocation

After creating the Gateway, check the status.addresses field to confirm the allocated IP address:
kubectl get gateway my-gateway -o jsonpath='{.status.addresses}'
Expected output:
[{"type":"IPAddress","value":"10.1.2.1"}]

Static IP versus IPAM

Configuration Behavior
spec.addresses is set NetScaler Kubernetes Gateway Controller uses the specified IP address directly. IPAM is not invoked.
spec.addresses is omitted NetScaler Kubernetes Gateway Controller requests an IP address from NetScaler IPAM controller if IPAM is enabled.
If you need a specific IP address for a Gateway, set it explicitly in spec.addresses:
spec:
  addresses:
    - type: IPAddress
      value: "10.1.2.50"

Annotation Reference

Annotation Scope Description
gateway.citrix.com/ipam-range Gateway Specifies the named IP address range from which NetScaler IPAM Controller allocates an address. If omitted, the default (unnamed) range is used.

IP address allocation when the pool is exhausted

If every IP address in the requested range is already allocated when a Gateway is created, NetScaler IPAM Controller keeps the request pending and retries automatically instead of dropping it. The Gateway stays without an IP address in status.addresses, the backing vip object is left without an IP address, and NetScaler IPAM Controller records a Kubernetes warning event (reason IPAMPoolExhausted) on the vip object.
As soon as an IP address is released in that range — for example, when another Gateway, service of type LoadBalancer, ingress, or listener that was using it is deleted — NetScaler IPAM Controller assigns the freed IP address to the oldest pending Gateway and records an IPAMAllocated event. The Gateway's status.addresses is updated with the allocated IP address and NetScaler Kubernetes Gateway Controller configures the VIP on NetScaler, without recreating the Gateway.

Troubleshooting

Symptom Possible Cause Resolution
Gateway stays in pending state with no IP address assigned NetScaler IPAM controller is not running or not enabled while deploying NetScaler Kubernetes Gateway Controller Verify that NetScaler IPAM controller pod is running and gatewayController.ipam is set to true in values.yaml of NetScaler Kubernetes Gateway Controller
IP address not allocated from expected range Range name in the annotation does not match NetScaler IPAM configuration Check that the gateway.citrix.com/ipam-range annotation value matches a named range in VIP_RANGE of NetScaler IPAM controller
IP pool exhausted All IP addresses in the configured range are allocated The Gateway stays pending and NetScaler IPAM Controller assigns an IP address automatically when one is released in that range (IPAMPoolExhausted and IPAMAllocated events are recorded on the vip object). To unblock sooner, expand the VIP_RANGE in NetScaler IPAM Controller configuration or free unused Gateways
Gateway works without IPAM after spec.addresses is set Expected behavior Static addresses bypass IPAM. Remove spec.addresses to use IPAM allocation

Limitations

  • Each Gateway receives a single VIP from NetScaler IPAM Controller.
  • The gateway.citrix.com/ipam-range annotation must reference a range name that exists in NetScaler IPAM controller configuration. An invalid range name prevents IP allocation.
  • When the annotation is omitted, NetScaler IPAM Controller automatically assigns an IP from the default (unnamed) pool (if configured).