Skip to content

Usage Considerations

Some usage notes about the LiteSpeed Ingress Controller:

  • When you install a LiteSpeed Ingress Controller it will immediately behave as a load balancer. Most cloud implementations will assign it an external IP address from which it can be accessed from the outside world. LiteSpeed supports multiple LoadBalancers.
  • Use Kubernetes cert-manager to manage TLS secrets for https connections.

Multiple Load Balancers

You may want to use multiple load balancers. The advantages of this are:

  • Each LoadBalancer is assigned a separate external IP address by most cloud providers. By having multiple load balancers you can separate traffic.
  • You may wish to separate your definitions by namespace.
  • You may wish to have separate vendor load balancers including cloud-provided load balancers.
  • You wish to separate test from production environments.

When you install the LiteSpeed LoadBalancer by default it will publish all Ingress definitions which:

  • Specify an Ingress.spec.ingressClassName which contains the value configured in --ingress-class-controller which defaults to litespeedtech.com/lslbd
  • Specify an Ingress.metadata.annotations.kubernetes.io/ingress.class which contains the value configured in --ingress-class-controller which defaults to litespeedtech.com/lslbd
  • Do not specify either of the above (is the default controller)

The advantage of specifying a specific load balancer is that you'll be able to have multiple load balancers in your environment which may be useful if you need to transition, test or otherwise need multiple load balancers.

Modifying your Ingress definitions

Using an IngressClass

If you're going to use an IngressClass you're first going to need to create the IngressClass. Then you'll modify the Ingress definitions which each need to specify the IngressClass you've created.

Creating an IngressClass

If you wish to use Ingress.spec.ingressClassName for your Ingress definitions, you'll need an IngressClass that uses the LiteSpeed ingress-class-controller specification.

This is a one time operation and not namespace specific.

An example YAML definition:

apiVersion: "networking.k8s.io/v1"
kind: "IngressClass"
metadata:
  name: "ls-k8s-webadc"
spec:
  controller: "litespeedtech.com/lslbd"

There's currently no direct way to create this with kubectl. The easiest way to do it is to create a file of the above named: ingressclass.yaml and then apply it with:

$ kubectl create -f ingressclass.yaml
Modifying your Ingress definitions

If your Ingress definitions are in .yaml files, you will have something that looks like this:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ...
spec:
  rules:
  - host: DOMAIN_NAME
...

At the same level as rules if you named your IngressClass ls-k8s-webadc (as in the example above), you'd add the ingressClassName:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ...
spec:
  ingressClassName: ls-k8s-webadc
  rules:
  - host: DOMAIN_NAME
...

You could then apply it using kubectl to take effect immediately.

Using an Annotation

A simpler modification to your Ingress definitions, is to add a single Ingress.metadata.annotations. Using the example above you'd need to modify your Ingress defintion.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ...
    kubernetes.io/ingress.class: litespeedtech.com/lslbd
...

You could then apply it using kubectl to take effect immediately.

Supported annotations

Besides the ingress.class annotation described above, ingress annotations supported with the controller include rewrite annotations.

Name Description Value Example
ingress.kubernetes.io/app-root Defines the Application Root that the Controller must redirect if it's in / context. string /subdir with a / request will result in a 302 redirecting the request to the same host at /subdir
ingress.kubernetes.io/force-ssl-redirect Forces the redirection to HTTPS even if the Ingress is not TLS Enabled. "true" or "false" Regardless of whether or not there is a SSL secret configured, setting to true will result in all non-https requests returning a 302 Found redirecting to the same host and location using https
ingress.kubernetes.io/rewrite-target Target URI where the traffic must be redirected. string If specified without use-regex can be used for example, to take two paths, say /api/customer/ and /api/customer/ and have them routed to the root by specifying rewrite-target /. If specified with use-regex: "true" you can use numbered groups. For example, if you specify the path /something(/|$)(.*) and rewrite-target: /$2 and the request is for /something/abc it will match the second group and be routed to /abc.
ingress.kubernetes.io/ssl-redirect Indicates if the location section is only accessible via SSL (defaults to "true" when Ingress contains a Certificate). "true" or "false" If there is a SSL secret configured, unless set to false, all non-https requests will result in a 302 Found redirecting to the same host and location using https
ingress.kubernetes.io/use-regex Indicates if the paths defined on an Ingress use regular expressions. "true" or "false" If set to true the paths will be examined for regular expressions. For example if the path is set to /foo/\d{5} any requests which are not preceded by /foo/ and 5 numeric digits will be rejected with a 404 Not Found. Any requests which match the requirement will be passed as specified to the backend, unless a rewrite-target is specified.
litespeed.ingress.kubernetes.io/template Specifies a configured, existing Virtual Host Template name. Generally used to add WAF security. string In the documentation, the template comodo is created as an example to demonstrate the feature.

Using cert manager

Using the Kubernetes cert-manager simplifies the creation and updating of certificates to guarantee the continuation of HTTPS availability for each of your Ingress defined backends. In particular it generates the certs and the Kubernetes secrets that are used by Ingress definitions. It is strongly recommended that it be used when possible.


Last update: May 12, 2022