Installing Lagoon Into Existing Kubernetes Cluster#
- Kubernetes 1.23+ (Kubernetes 1.21 is supported, but 1.23 is recommended)
- Familiarity with Helm and Helm Charts, and kubectl.
- Ingress controller, we recommend ingress-nginx, installed into ingress-nginx namespace
- Cert manager (for TLS) - We highly recommend using letsencrypt
- StorageClasses (RWO as default, RWM for persistent types)
We acknowledge that this is a lot of steps, and our roadmap for the immediate future includes reducing the number of steps in this process.
Specific requirements (as of January 2023)#
Lagoon supports Kubernetes versions 1.21 onwards. We actively test and develop against Kubernetes 1.24, also regularly testing against 1.21,1.22 and 1.25.
The next large round of breaking changes is in Kubernetes 1.25, and we will endeavour to be across these in advance, although this will require a bump in the minimum supported version of Lagoon.
Lagoon is currently configured only for a single
ingress-nginx controller, and therefore defining an
IngressClass was not necessary in the past.
In order to use the recent
ingress-nginx controllers (v4 onwards, required for Kubernetes 1.22), the following configuration should be used, as per the
nginx-ingressshould be configured as the default controller - set
.controller.ingressClassResource.default: truein Helm values
nginx-ingressshould be configured to watch ingresses without
IngressClassset - set
.controller.watchIngressWithoutClass: truein Helm values
This will configure the controller to create any new ingresses with itself as the
IngressClass, and also to handle any existing ingresses without an
Other configurations may be possible, but have not been tested.
Versions 2.1 and 2.2+ of Harbor are currently supported. The method of retrieving robot accounts was changed in 2.2, and the Lagoon remote-controller is able to handle these tokens. This means that Harbor has to be configured with the credentials in
lagoon-build-deploy - not
k8up for backups#
Lagoon has built in configuration for the K8up backup operator. Lagoon can configure prebackup pods, schedules and retentions, and manage backups and restores for K8up. Lagoon currently only supports the 1.x versions of K8up, owing to a namespace change in v2 onwards, but we are working on a fix.
Lagoon does not currently support K8up v2 onwards due to a namespace change here.
Lagoon utilizes a default 'standard'
StorageClass for most workloads, and the internal provisioner for most Kubernetes platforms will suffice. This should be configured to be dynamic provisioning and expandable where possible.
Lagoon also requires a
StorageClass called 'bulk' to be available to support persistant pod replicas (across nodes). This
StorageClass should support
ReadWriteMany (RWX) access mode and should be configured to be dynamic provisioning and expandable where possible. See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes for more information, and the production drivers list for a complete list of compatible drivers.
We have curently only included the instructions for (the now deprecated) EFS Provisioner. The production EFS CSI driver has issues with provisioning more than 120 PVCs. We are awaiting upstream possible fixes here and here - but most other providers CSI drivers should also work, as will configurations with an NFS-compatible server and provisioner.
How much Kubernetes experience/knowledge is required?#
Lagoon uses some very involved Kubernetes and cloud-native concepts, and while full familiarity may not be necessary to install and configure Lagoon, diagnosing issues and contributing may prove difficult without a good level of familiarity.
As an indicator, comfort with the curriculum for the Certified Kubernetes Administrator would be suggested as a minimum.