Dynamic IP address allocation through NetScaler IPAM Controller
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.
Prerequisites
Before configuring dynamic IP address allocation through NetScaler IPAM Controller, ensure the following:
-
NetScaler Gateway Controller is deployed with
ipam: Truein the Helmvalues.yaml. For more information, see Deploy NetScaler Kubernetes Gateway Controller. -
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
<!--NeedCopy-->
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
<!--NeedCopy-->
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
<!--NeedCopy-->
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}'
<!--NeedCopy-->
Expected output:
[{"type":"IPAddress","value":"10.1.2.1"}]
<!--NeedCopy-->
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"
<!--NeedCopy-->
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. |
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 ipam: True is set 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 | 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-rangeannotation 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).