NetScaler ingress controller

IP address management using the IPAM controller for Ingress resources

May 7, 2024

Contributed by:

C C

IPAM controller is an application provided by NetScaler for IP address management and it runs in parallel to the NetScaler Ingress Controller in the Kubernetes cluster. Automatically allocating IP addresses to services of type LoadBalancer from a specified IP address range using the IPAM controller is already supported. Now, you can also assign IP addresses to Ingress resources from a specified range using the IPAM controller.

You can specify IP address ranges in the YAML file while deploying the IPAM controller using YAML. The NetScaler Ingress Controller configures the IP address allocated to the Ingress resource as a virtual IP address (VIP) in NetScaler MPX or VPX.

The IPAM controller requires the VIP CustomResourceDefinition (CRD) provided by NetScaler. The VIP CRD is used for internal communication between the NetScaler Ingress Controller and the IPAM controller.

Assign IP address for Ingress resource using the IPAM controller

This topic provides information on how to use the IPAM controller to assign IP addresses for Ingress resources.

To configure an Ingress resource 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/citrix/citrix-k8s-ingress-controller/master/crd/vip/vip.yaml

For more information on VIP CRD, see the VIP CustomResourceDefinition.

Step 2: Deploy the NetScaler Ingress Controller

Perform the following steps to deploy the NetScaler Ingress Controller with the IPAM controller argument.

Download the citrix-k8s-ingress-controller.yaml file using the following command:

wget  https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/deployment/baremetal/citrix-k8s-ingress-controller.yaml

Edit the NetScaler Ingress Controller YAML file:

Specify the values of the environment variables as per your requirements. For more information on specifying the environment variables, see the Deploy NetScaler Ingress Controller. Here, you don’t need to specify NS_VIP.
Specify the IPAM controller as an argument using the following:

args: - –ipam citrix-ipam-controller

Here is a snippet of a sample NetScaler Ingress Controller YAML file with the IPAM controller argument:

Note:

This YAML is for demonstration purpose only and not the full version. Always, use the latest version of the YAML and edit as per your requirements. For the latest version see the citrix-k8s-ingress-controller.yaml file.

apiVersion: v1
kind: Pod
metadata:
  name: cic-k8s-ingress-controller
spec:
      serviceAccountName: cic-k8s-role
      containers:
      - name: cic-k8s-ingress-controller
        image: "quay.io/citrix/citrix-k8s-ingress-controller:1.36.5"
        env:
          - name: "NS_IP"
            value: "x.x.x.x"
          - name: "NS_USER"
            valueFrom:
            secretKeyRef:
              name: nslogin
              key: username
          - name: "NS_PASSWORD"
            valueFrom:
            secretKeyRef:
              name: nslogin
              key: password
          - name: "EULA"
            value: "yes"
          - name: POD_NAME
            valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: metadata.name
          - name: POD_NAMESPACE
            valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
        args:
          - --ipam citrix-ipam-controller
        imagePullPolicy: Always

Deploy the NetScaler Ingress Controller using the edited YAML file with the following command:
```
kubectl create -f citrix-k8s-ingress-controller.yaml
```
For more information on how to deploy the NetScaler Ingress Controller, see the Deploy NetScaler Ingress Controller.

Step 3: Deploy the IPAM controller

Perform the following steps to deploy the IPAM controller.

Create a file named citrix-ipam-controller.yaml with the following configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: citrix-ipam-controller
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: citrix-ipam-controller
  template:
    metadata:
      labels:
        app: citrix-ipam-controller
    spec:
      serviceAccountName: citrix-ipam-controller
      containers:
      - name: citrix-ipam-controller
        image: quay.io/citrix/citrix-ipam-controller:1.0.3
        env:
        # This IPAM controller takes envirnment variable VIP_RANGE. IPs in this range are used to assign values for IP range
        - name: "VIP_RANGE"
          value: '[["10.217.6.115-10.217.6.117"], {"one-ip": ["5.5.5.5"]}, {"two-ip": ["6.6.6.6", "7.7.7.7"]}]'
        # The IPAM controller can also be configured with name spaces for which it would work through the environment variable
        # VIP_NAMESPACES, This expects a set of namespaces passed as space separated string
        imagePullPolicy: Always

The manifest contains two environment variables, VIP_RANGE and VIP_NAMESPACES. You can specify the appropriate routable IP range with a valid CIDR under the VIP_RANGE. If necessary, you can also specify a set of namespaces under VIP_NAMESPACES so that the IPAM controller allocates addresses only for services or Ingress resources from specific namespaces.

Deploy the IPAM controller using the following command:

kubectl create -f citrix-ipam-controller.yaml

Step 4: Deploy Ingress resources

Perform the following steps to deploy a sample application and Ingress resource.

Deploy the Guestbook application using the following command:

kubectl apply -f https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/example/guestbook/guestbook-all-in-one.yaml

Create the guestbook-ingress YAML file with Ingress resource definition to send traffic to the front-end of the guestbook application.

The following is a sample YAML:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: guestbook-ingress
  annotations:
annotations:
  ingress.citrix.com/ipam-range: "two-ip"
  #ingress.citrix.com/frontend-ip: "5.5.5.5"
  kubernetes.io/ingress.class: "cic-vpx"
spec:
  rules:
  - host:  www.guestbook.com
    http:
      paths:
      - path: /
        backend:
          serviceName: frontend
          servicePort: 80

Deploy the Ingress resource.

kubectl create -f guestbook-ingress.yaml

For Ingress without any frontend-ip annotation, the order of IP assignment is as follows:

If the default NS_VIP environment 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_VIP is used for that ingress.
If the default NS_VIP environment variable is not provided, NetScaler Ingress Controller always make a request to IPAM controller for IP assignment.

Multiple IP address allocations

For Ingress resources, an IP address can be allocated multiple times since multiple ingress resources may be handled by a single csvserver. If the specified IP range has only a single IP address, it is allocated multiple times. But, if the named IP range consists of multiple IP addresses, only one of them is constantly allocated.

To facilitate multiple allocations, the IPAM controller keeps track of 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.

Allocations by different resources

Both services of type LoadBalancer and Ingress resources can use the IPAM controller for IP allocations at the same time. If an IP address is allocated by one type of resource, it is not available for a resource of another type. But, the same IP address may be used by multiple ingress resources.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

IP address management using the IPAM controller for Ingress resources

May 7, 2024

Contributed by:

C C

May 7, 2024

Contributed by:

C C

IP address management using the IPAM controller for Ingress resources

Assign IP address for Ingress resource using the IPAM controller

Step 1: Deploy the VIP CRD

Step 2: Deploy the NetScaler Ingress Controller

Step 3: Deploy the IPAM controller

Step 4: Deploy Ingress resources

Multiple IP address allocations

Allocations by different resources

In this article