Skip to content

Installing Lagoon Into Existing Kubernetes Cluster#


  • Kubernetes 1.19+ (Kubernetes 1.22+ is not yet supported, see for progress)
  • 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
  • RWO storage


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 March 2022)#


Lagoon supports Kubernetes versions 1.19, 1.20 and 1.21. Support for 1.22 is underway, and mostly complete. There are a number of relevant API deprecations in 1.22 that Lagoon utilized across a number of dependencies.


Lagoon is currently only for a single ingress-nginx controller, and therefore defining an IngressClass has not been necessary.

This means that Lagoon currently works best with version 3 of the ingress-nginx Helm chart - latest release 3.40.0.

In order to use a version of the Helm chart (>=4) that supports Ingress v1 (i.e for Kubernetes 1.22), the following configuration should be used, as per the ingress-nginx docs.

  • nginx-ingress should be configured as the default controller - set .controller.ingressClassResource.default: true in Helm values
  • nginx-ingress should be configured to watch ingresses without IngressClass set - set .controller.watchIngressWithoutClass: true in 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 IngressClass set.

Other configurations may be possible, but have not been tested.


Only Harbor <2.2 is currently supported - the method of retrieving robot accounts was changed in 2.2, and we are working on a fix.

This means you should install Harbor 2.1.6 with Helm chart 1.5.6.

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.