IP address management using the IPAM controller
The IPAM controller is an application provided by NetScaler for IP address management and it runs in parallel to NetScaler Ingress Controller in the Kubernetes cluster. You can assign IP addresses to ingress resources, services of type LoadBalalncer, and listener resources from a specified IP address range using the IPAM controller. NetScaler Ingress Controller configures an IP address allocated to a service, or ingress, or listener resource as a virtual IP address (VIP) in NetScaler MPX or NetScaler VPX.
The IPAM controller requires the VIP CustomResourceDefinition (CRD) provided by NetScaler. The VIP CRD is used for internal communication between NetScaler Ingress Controller and the IPAM controller.
Infoblox integration with IPAM controller
With Infoblox integration, the IPAM controller assigns IP addresses to services of type LoadBalancer, ingress, or listener resources from Infoblox.
The following annotations are supported in an ingress resource, listener resource, and service of type LoadBalancer respectively: ingress.citrix.com/ipam-range, listeners.citrix.com/ipam-range, and service.citrix.com/ipam-range. You need to provide the IP address ranges defined in the IPAM controller by using these annotations for the respective resources. The IP address range must either be an IPAM VIP range or an Infoblox VIP range.
Note:
- Infoblox integration is supported for versions up to 2.12.3, starting from IPAM Controller version 2.2.10.
- You must not update or delete the IP address allocated by IPAM using Infoblox.
The IPAM controller poses the following challenges in a multi-cluster setup:
- An IP address must be provided manually.
- A common IP address must be assigned for each application deployed across multiple clusters.
- Limitations in sharing the IP address range between IPAM controllers in other clusters, adding complexity to the task.
Infoblox integration with IPAM helps with the following tasks:
- Assign an available IP address from the specified IP address range using Infoblox network management.
- Request the IP address associated with a domain name, ensuring the retrieval of a pre-existing IP address.
- In a multi-cluster ingress setup, the application deployed across various clusters can be accessed using a single, consistent IP address.
During initialization, the IPAM controller connects with Infoblox and creates a network view if it’s not already available. This network view creation is based on the network range in the DNS view that you provide. If the network range in the DNS view is not provided, the IPAM controller creates a network view.
Assign an IP address using the IPAM controller
To configure an ingress resource or listener resource or service of type LoadBalancer with an IP address from the IPAM controller, perform the following steps:
- Deploy the VIP CRD
- Deploy the NetScaler Ingress Controller
- Deploy the IPAM controller
- Deploy the application and ingress resource
Step 1: Deploy the VIP CRD
Perform the following step to deploy the NetScaler VIP CRD which enables communication between the NetScaler Ingress Controller and the IPAM controller.
kubectl create -f https://raw.githubusercontent.com/netscaler/netscaler-k8s-ingress-controller/master/crd/vip/vip.yaml
For more information on VIP CRD, see the VIP CustomResourceDefinition.
Step 2: Deploy NetScaler Ingress Controller
Prerequisites
-
Kubernetes cluster and a kubectl command-line tool to communicate with the cluster.
-
Create a secret using NetScaler VPX or NetScaler MPX credentials by using the following command:
kubectl create secret generic nslogin --from-literal=username=<username> --from-literal=password=<password> <!--NeedCopy--> -
Add the NetScaler Helm chart repository by using the following command:
helm repo add netscaler https://netscaler.github.io/netscaler-helm-charts/ <!--NeedCopy-->
Deploy NSIC
-
Update the NetScaler Helm chart repository by using the following command:
helm repo update netscaler <!--NeedCopy--> -
Update values.yaml to configure NetScaler Ingress Controller as described as following.
Sample
values.yaml:license: accept: yes adcCredentialSecret: nslogin # K8s Secret Name nsIP: <x.x.x> # CLIP (for appliances in Cluster mode), SNIP (for appliances in High Availability mode) , NSIP (for standalone appliances) openshift: false # set to true for OpenShift deployments entityPrefix: cluster1 # unique for each NSIC instance. ipam: true ingressClass: ['cic-vpx'] # ingress class used in the ingress resources serviceClass: ['netscaler'] # To use service type LB, specify the service class <!--NeedCopy--> -
Install NetScaler Ingress Controller for your NetScaler VPX or using the following Helm command:
helm install nsic netscaler/netscaler-ingress-controller -f values.yaml <!--NeedCopy-->
For detailed information about deploying and configuring NetScaler Ingress Controller using Helm charts, see the Helm chart repository.
Step 3: Deploy IPAM controller
Prerequisites
-
For Infoblox integration, ensure that you create a user role in Infoblox with the following permissions:
-
IP Address Management:
- Allocate and manage IP addresses.
- Create, update, and delete host records.
-
Extensible Attributes Management:
- Create, update, and delete extensible attributes.
-
IP Address Management:
-
For Infoblox integration, create a Kubernetes secret with Infoblox user credentials by running the following command:
kubectl create secret generic infobloxlogin --from-literal=username=<Infoblox_username> --from-literal=password=<Infoblox_password> <!--NeedCopy-->
In this procedure, let’s deploy an IPAM controller and integrate Infoblox with the IPAM controller.
-
Add the NetScaler Helm chart repository to your local registry by using the following command:
helm repo add netscaler https://netscaler.github.io/netscaler-helm-charts/ <!--NeedCopy--> -
Install NetScaler IPAM controller by using the following command:
helm install netscaler-ipam-controller netscaler/netscaler-ipam-controller -f values.yaml <!--NeedCopy-->
Sample values.yaml:
cluster: 'cluster1' # enables you to know in which cluster IPAM is installed in multi-cluster solution
vipRange: "[{\"range1\": [\"1.2.1.51-1.2.1.59\"]\,\"range2\": [\"1.2.1.61-1.2.1.69\"]}]" # range1 has IPs from 1.2.1.51 to 1.2.1.59 and range2 has IPs from 1.2.1.61 to 1.2.1.69
reuseIngressVip: "True" # set to False to assigns different IP address to each ingress resource
infoblox:
enabled: True #set to false to disable Infoblox integration with IPAM controller
credentialSecret: <secret> # Kubernetes secret created using Infoblox user credentials
gridHost: <x.x.x.x> # Infoblox grid host IP or FQDN
vipRange: "[{"infoblox-range": ["1.1.1.0/24"]}]" # Infoblox IPAM VIP Range, which is different from the vipRange mentioned above. This has to be in CIDR format like 1.1.1.0/24
<!--NeedCopy-->
The following table provides information about all the configurable parameters while installing the IPAM controller:
| Parameters | Mandatory or Optional | Default value | Description |
|---|---|---|---|
| imageRegistry | Mandatory | quay.io | The NetScaler IPAM Controller image registry. |
| imageRepository | Mandatory | netscaler/netscaler-ipam-controller | The NetScaler IPAM Controller image repository. |
| imageTag | Mandatory | 2.1.2 | The NetScaler IPAM Controller image tag. |
| pullPolicy | Mandatory | IfNotPresent |
The NetScaler IPAM Controller image pull policy. |
| vipRange | Mandatory | N/A | This variable allows you to define the IP address range. You can either define IP address range or an IP address range associated with a unique name. NetScaler IPAM controller assigns the IP address from this IP address range to the service of type LoadBalancer. |
| reuseIngressVip | Optional | True | This variable allows you to use the same IP for all ingresses using the same vipRange. |
| cluster | Mandatory if infoblox.enabled is true |
N/A | This variable allows you to provide cluster name that is used to identify the cluster in which the IPAM controller is deployed. |
| infoblox.enabled | Optional | false | Boolean value that allows you to enable or disable Infoblox IPAM. |
| infoblox.gridHost | Mandatory if infoblox.enabled is true |
N/A | Infoblox grid host IP or FQDN that must be reachable from Cluster. |
| infoblox.credentialSecret | Mandatory if infoblox.enabled is true |
N/A | Kubernetes Secret in the same namespace having Infoblox user name and password with desired access privileges as listed in the prerequisites. |
| infoblox.httpTimeout | Optional | 10 | This variable allows you to provide Infoblox client HTTP timeout in seconds. |
| infoblox.maxRetries | Optional | 3 | This variable allows you to provide Infoblox client maximum retries if there is a failure. |
| infoblox.netView | Optional | default | This variable allows you to provide Infoblox Network View. If the Network View is not present, it is created. |
| infoblox.vipRange | Mandatory if infoblox.enabled is true | N/A | Infoblox IPAM virtual IP address range that is managed by the controller. All IP addresses in this range are managed in Infoblox by the controller and must not be conflicting for any other processes. IP range must be in CIDR format a.b.c.d/n. Example: “[{“infoblox-range”: [“1.1.1.0/24”]}]”. |
| serviceAccount.create | Mandatory | true | This variable creates a service account for NetScaler IPAM Controller. |
| serviceAccount.tokenExpirationSeconds | Mandatory | 31536000 | Time in seconds when the token of service account expires. |
| serviceAccount.name | Optional | ”” | Name of the service account for the IPAM Controller. If you want to use a service account that you have already created and manage yourself, specify its name here and set serviceAccount.create to false. |
Step 4: Deploy Ingress resources
Perform the following steps to deploy a sample application and ingress resource.
-
Deploy the CNN application by using the following command:
kubectl apply -f - <<EOF apiVersion: apps/v1 kind: Deployment metadata: name: cnn-website labels: name: cnn-website app: cnn-website spec: selector: matchLabels: app: cnn-website replicas: 2 template: metadata: labels: name: cnn-website app: cnn-website spec: containers: - name: cnn-website image: quay.io/sample-apps/cnn-website:v1.0.0 ports: - name: http-80 containerPort: 80 - name: https-443 containerPort: 443 --- apiVersion: v1 kind: Service metadata: name: cnn-website labels: app: cnn-website spec: type: NodePort ports: - name: http-80 port: 80 targetPort: 80 - name: https-443 port: 443 targetPort: 443 selector: name: cnn-website EOF <!--NeedCopy--> -
Deploy the ingress resource to send traffic to the CNN application by using the following command:
kubectl apply -f - <<EOF apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cnn-ingress annotations: ingress.citrix.com/ipam-range: "<IPAM-vip-range or Infoblox-vip-range>" spec: ingressClassName: cic-vpx rules: - host: www.cnn.com http: paths: - path: / pathType: Prefix backend: service: name: cnn-website port: number: 80 EOF <!--NeedCopy-->
For the preceding ingress example, the order of IP assignment is as follows:
-
If the default
NS_VIPenvironment variable is provided, NetScaler Ingress Controller makes a request to IPAM controller only if the range-name (ingress.citrix.com/ipam-range:) is provided in the ingress. If the annotation is not provided,NS_VIPis used for that ingress. -
If the default
NS_VIPenvironment variable is not provided, NetScaler Ingress Controller always make a request to IPAM controller for IP assignment.
IP address allocations
-
For services of type LoadBalancer, a unique IP address is allocated to each service from the VIP range or Infoblox VIP range.
-
For an ingress resource, an IP address in the specified IP range is allocated. When more ingress resources refer to the same VIP range, the IP address allocated to the first ingress resource is allocated to all the other ingress resources.
-
Services of type LoadBalancer, ingress resources, and listener resources can use NetScaler IPAM controller for IP address allocations at the same time. If an IP address is allocated to any one resource type, it is not available for another resource type. But, the same IP address can be allocated to multiple ingress resources.
IP address range associated with a unique name
You can assign a unique name to the IP address range and define the range in the VIP_RANGE environment variable. This way of assigning the IP address range enables you to differentiate between the IP address ranges. When you create the services of type LoadBalancer, you can use the service.citrix.com/ipam-range annotation in the service definition to specify the IP address range to use for IP address allocation.
Multiple IP address allocations
For ingress resources, an IP address can be allocated multiple times by specifying the Helm chart parameter reuseIngressVip as true, because multiple ingress resources might be handled by a single content switching virtual server. If the specified IP range has only a single IP address, it is allocated multiple times. And, if the IP range consists of multiple IP addresses, only one of them is allocated repeatedly.
To facilitate multiple allocations, the IPAM controller tracks the allocated IP addresses. The IPAM controller places an IP address into the free pool only when all allocations of that IP address by ingress resources are released.