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
LoadBalancer
s. - 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 tolitespeedtech.com/lslbd
- Specify an
Ingress.metadata.annotations.kubernetes.io/ingress.class
which contains the value configured in--ingress-class-controller
which defaults tolitespeedtech.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.