NetScaler ingress controller

Ingress class support

What is Ingress class?

In a Kubernetes cluster, there might be multiple ingress controllers and you need to have a way to associate a particular ingress resource with an ingress controller.

You can specify the ingress controller that should handle the ingress resource by using the kubernetes.io/ingress.class annotation in your ingress resource definition.

NetScaler Ingress Controller and Ingress classes

The NetScaler Ingress Controller supports accepting multiple ingress resources, which have kuberneters.io/ingress.class annotation. Each ingress resource can be associated with only one ingress.class. However, the Ingress Controller might need to handle various ingress resources from different classes.

You can associate the Ingress Controller with multiple ingress classes using the --ingress-classes argument under the spec section of the YAML file.

If ingress-classes is not specified for the Ingress Controller, then it accepts all ingress resources irrespective of the presence of the kubernetes.io/ingress.class annotation in the ingress object.

If ingress-classes is specified, then the Ingress Controller accepts only those ingress resources that match the kubernetes.io/ingress.class annotation. The Ingress controller does not process an Ingress resource without the ingress.class annotation in such a case.

Note: Ingress class names are case-insensitive.

Sample YAML configurations with Ingress classes

Following is the snippet from a sample YAML file to associate ingress-classes with the Ingress Controller. This configuration works in both cases where the Ingress Controller runs as a standalone pod or runs as a sidecar with NetScaler CPX. In the given YAML snippet, the following ingress classes are associated with the Ingress Controller.

  • my-custom-class

  • Citrix

spec:
    serviceAccountName: cic-k8s-role
    containers:
    - name: cic-k8s-ingress-controller
      image:"quay.io/citrix/citrix-k8s-ingress-controller:latest"
      # specify the ingress classes names to be supportedbyIngress Controller in args section.
      # First line should be --ingress-classes, andeverysubsequent line should be
      # the name of allowed ingress class. In the givenexampletwo classes named
      # "citrix" and "my-custom-class" are accepted. Thiswill be case-insensitive.
      args:
        - --ingress-classes
          Citrix
          my-custom-class
<!--NeedCopy-->

Following is the snippet from an Ingress YAML file where the Ingress class association is depicted. In the given example, an Ingress resource named web-ingress is associated with the ingress class my-custom-class. If the NetScaler Ingress Controller is configured to accept my-custom-class, it processes this Ingress resource.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: my-custom-class
  name: web-ingress
<!--NeedCopy-->

Ingress V1 and IngressClass support

With the Kubernetes version 1.19, the Ingress resource is generally available. As a part of this change, a new resource named as IngressClass is added to the ingress API. Using this resource, you can associate specific Ingress controllers to Ingresses. For more information on the IngressClass resource, see the Kubernetes documentation.

The following is a sample IngressClass resource.


apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: citrix
spec:
  controller: citrix.com/ingress-controller

<!--NeedCopy-->

An IngressClassresource must refer to the ingress class associated with the controller that should implement the Ingress rules as shown as follows:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
spec:
  ingressClassName: citrix
  rules:
  - host: abc.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80
<!--NeedCopy-->

The NetScaler Ingress Controller uses the following rules to match the Ingresses.

  • If the NetScaler Ingress Controller is started without specifying the --ingress-classes argument:

    • If the Kubernetes version is lesser than 1.19 (IngressClass V1 resource is supported)

      • Matches any ingress object
    • If the Kubernetes version is greater than or equal to 1.19 (IngressClass V1 resource is supported)

      • Matches any ingress object in which the spec.ingressClassName field is not set.

      • Matches any ingress if the spec.ingressClassName field of the Ingress object is set and a v1.IngressClass resource exists with the same name and the spec.controller field of the resource is citrix.com/ingress-controller.

  • If the NetScaler Ingress Controller is started with one or more ingress classes set using the --ingress-classes argument.

    • If the Kubernetes version is lesser than 1.19 (IngressClass V1 resource is supported)

      • Matches any ingress with the ingress class annotation kubernetes.io/ingress.class matching to that of the configured ingress classes.
    • If the Kubernetes version is greater than or equal to 1.19 (IngressClass V1 resource is supported).

      • Matches any ingress in which the ingress class annotation kubernetes.io/ingress.class matches with the configured ingress classes. This annotation is deprecated but it has higher precedence over the spec.IngressClassName field to support backward compatibility.

      • Matches any ingress object, if a v1.IngressClass resource exists with the following attributes:

        • The name of the resource matches the --ingress-classes argument value.

        • The spec.controller field of the resource is set as the citrix.com/ingress-controller.

        • The name of the resource matches with the spec.ingressClassName field of the Ingress object.

      • Matches any ingress object where the spec.ingressClassName field is not set and if a v1.IngressClass resource exists with the following attributes:

        • The name of the resources matches the --ingress-classes argument value.

        • The spec.controller field of the resource is set as citrix.com/ingress-controller.

        • The resource is configured as the default class using the ingressclass.kubernetes.io/is-default-class annotation. For more information, see the Kubernetes documentation.

Note:

  • If both the annotation and spec.ingressClassName is defined, the annotation is matched before the spec.ingressClassName. If the annotation does not match, the matching operation for the spec.ingressClassName field is not performed.

  • When you are using Helm charts to install the NetScaler Ingress Controller, if the IngressClass resource is supported and the NetScaler Ingress Controller is deployed with the --ingress-classes argument, the v1.IngressClass resource is created by default.

Updating the Ingress status for the Ingress resources with the specified IP address

To update the Status.LoadBalancer.Ingress field of the Ingress resources managed by the NetScaler Ingress Controller with the allocated IP addresses, specify the command line argument --update-ingress-status yes when you start the NetScaler Ingress Controller. This feature is only supported for the NetScaler Ingress Controller deployed as a stand-alone pod for managing NetScaler VPX or MPX. For NetScaler CPXs deployed as sidecars, this feature is not supported.

Following is an example YAML with the --update-ingress-status yes command line argument enabled.

args:
    - --feature-node-watch false
    - --ipam citrix-ipam-controller
    - --update-ingress-status yes
    imagePullPolicy: Always
<!--NeedCopy-->

Ingress status update for sidecar deployments

In Kubernetes, Ingress can be used as a single entry point for exposing multiple applications to the outside world. The Ingress would have an Address (Status.LoadBalancer.IP) field which is updated after the successful ingress creation. This field is updated with a public IP address or host name through which the Kubernetes application can be reached. In cloud deployments, this field can also be the IP address or host name of a cloud load-balancer.

In cloud deployments, NetScaler CPX along with the ingress controller is exposed using a service of type LoadBalancer which in turn creates a cloud load-balancer. The cloud load balancer then exposes the NetScaler CPX along with the ingress controller. So, the Ingress resources exposed with the NetScaler CPX should be updated using the public IP address or host name of the cloud load balancer.

This is applicable even on on-prem deployments. In dual-tier ingress deployments, in which the NetScaler CPX is exposed as service type LoadBalancer to the tier-1 NetScaler VPX ingress, the ingress resources operated by the NetScaler CPX is updated with the VIP address.

This topic provides information about how to enable the ingress status update for NetScaler CPX with the NetScaler Ingress Controller as sidecar deployments.

Note: The ingress status update for the sidecar feature is supported only on services of type LoadBalancer.

Sample ingress output after an ingress status update

The following is a sample ingress output after the ingress status update:

    $ kubectl get ingress

    NAME             HOSTS              ADDRESS                           PORTS    AGE                                       
    sample-ingress   sample.citrix.com   sample.abc.somexampledomain.com   80      1d

Enable ingress status update for the sidecar deployments

You can enable the ingress status update feature for side car deployments by specifying the following argument in the NetScaler CPX YAML file. You must add the argument to the args section of NetScaler CPX in the deployment YAML file for NetScaler CPX with the NetScaler Ingress Controller.

    args:
    - --cpx-service <namespace>/<name-of-the-type-load-balancer-service-exposing-cpx>

The following table describes the argument for the ingress update in detail

Keyword/variable Description
--cpx-service Specifies the argument for enabling this feature.
<namespace>/<name-of-the-type-load-balancer-service-exposing-cpx> Specifies the format in which the argument value to be provided.
<namespace> Specifies the namespace in which the service is created.
<name-of-the-type-load-balancer-service-exposing-cpx> Specifies the name of the service that exposes NetScaler CPX.

Note:

The ingress status update for the sidecar feature is supported only on services of type LoadBalancer. The service defined in the argument --cpx-service default/some-cpx-service should be a Kubernetes service of type LoadBalancer.