Product Documentation
NetScaler ingress controller
View PDF

Ingress class support

November 15, 2024
Contributed by: 
C

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 NetScaler Ingress Controller with the allocated IP addresses, specify the command line argument --update-ingress-status yes when you start NetScaler Ingress Controller.

Note:

For Helm deployments, the Helm chart equivalent parameter for update-ingress-status is updateIngressStatus, which needs to be set to true.

This feature is supported on both standalone and sidecar NSIC deployments. For an NSIC deployed as a sidecar, this feature is supported from NSIC version 2.2.10.

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 update is applicable on on-prem deployments too.

  • In dual-tier ingress deployments, in which NetScaler CPX is exposed using a service of type LoadBalancer to the tier-1 NetScaler VPX ingress, the Address (Status.LoadBalancer.IP) field of the ingress resources operated by NetScaler CPX is updated with the VIP address.
  • In dual-tier ingress deployments, in which NetScaler CPX is exposed using a service of type ClusterIP or NodePort, the Address (Status.LoadBalancer.IP) field of the ingress resources operated by NetScaler CPX is updated with the cluster IP address of the CPX service.

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
Ingress class support
November 15, 2024
Contributed by: 
C
November 15, 2024
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.