Values.yaml and Let's Encrypt

Currently, I have deployed a Kubernetes cluster using KubeOne that will serve as my ‘master cluster’. I am trying to prepare the configuration for Kubermatic Kubernetes Platform, but am a bit confused regarding the ‘values.yaml’ file.

I would like to deploy the minimal components for the ‘master’ cluster - cert-manager, Nginx-controller, and OAuth. So looking at the ‘values.yaml’ file for cert-manager there is a couple of things that I don’t quite understand how they fit in. For example: “ingressShim” and “clusterIssuers”. I can see that ‘ingressShim” is empty by default and we can configure a couple of settings for it - but what is this used for? Also, “clusterIssuers” refers to some “letsencrypt-prod” and “letsencrypt-staging” dicts that look like are pointing to some letsencrypt upstream servers? How does ‘letsencrypt’ fit in to KKP and is it a pre-requirement? Can we bypass letsencrypt? I noticed that ‘letsencrypt-prod’ is also referenced as the ‘certIssuer’ for Dex. Is this the only option for managing certificates?

Let me clarify your questions:

  • The ingressShim component is responsible for creating certificates based on annotations on Ingress resources (Kubermatic does not use this mechanism, but it’s generally useful and harmless to leave it enabled). See the cert-manager documentation for more information on this.
  • Our cert-manager Helm chart can be used to automatically create ClusterIssuers (i.e. certificate issuers that are available in all Kubernetes namespaces, in contrast to a regular Issuer). A common choice nowadays is using Let’s Encrypt (LE) to acquire certificates for free, which is why we pre-configure our Helm chart to create ClusterIssuers for LE by default. LE servers are indeed out in the Internet and need direct access (port 80) to the Kubernetes cluster, so that cert-manager can perform domain authentication and get a certificate. An air-gapped cluster for example could not make use of LE.
  • You can extend or change the predefined list of ClusterIssuers via the values.yaml. This is useful if your have your own internal CA infrastructure, as documented in the cert-manager documentation.
  • Our certificates are configured to use the letsencrypt-prod issuer by default (LE offers two, a production and staging/testing setup, where the staging environment would issue certificates that are not actually trusted by anyone, but the rate limit for getting certificates is much higher – useful during testing).
  • During installation you can change the issuer to whatever you like, as long as someone at some point provides a valid certificate so that the Kubermatic components can talk to each other. Both the IAP chart and the KubermaticConfiguration CRD have options for this. The certificates do not need to be issued by Let’s Encrypt.
  • In special circumstances it is also possible to forgo the cert-manager alltogether (except for its CRDs, which must be available in the cluster) and configure a self-signed certificate. This does require some more configuration, like setting spec.auth.caBundle in the KubermaticConfiguration, so that the Kubermatic components can validate Dex’ certificate.

I hope this clears up your questions :slight_smile: