Latest Release
🌻
Getting Started
💐
Using Garden
🌿
Guides
🌺
Advanced
☘️ Reference
cert-manager Integration
When starting a new Kubernetes project or when maintaining your existing ones, dealing with the creation and renewal of TLS certificates can easily become a headache. A popular tool to help automate certficate generation and renewal is cert-manager.
The kubernetes and local-kubernetes providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults. We don't aim to support all the features of cert-manager, but rather accommodate the most common use case, while still allowing full control of the underlying setup when needed.
Requirements
You need to have an ingress controller configured, that is configured using Ingress resources (e.g. nginx). You can install nginx automatically by setting
setupIngressController: nginx in your kubernetes provider config. You also need make sure your DNS and routing are configured to point the domains you will configure below to your ingress controller.Limitations
cert-manager is currently under development. Currently we only support cert-manager v0.11.0, which requires Kubernetes v1.11 or higher.
If you set
certManager.install: false garden will expect to find a cert-manager installation in the cert-manager namespace. If you already have installed cert-manager please verify it's running by checking the status of the main pods as suggested in the documentationThe integration currently only supports Let's Encrypt and HTTP-01 challenges. We also only support cert-manager ClusterIssuers and not namespace Issuers.
More configuration options will be implemented, but we need your help to prioritize them! Please file an issue to request the features you need.
Usage
Enabling and configuring cert-manager
To enable cert-manager, you'll need to configure it in the
kubernetes provider configuration in your project garden.yml file:1
kind: Project
2
name: cert-manager-example
3
environments:
4
- name: remote-dev
5
providers:
6
- name: kubernetes
7
context: your-remote-k8s-cluster-context
8
setupIngressController: nginx
9
...
10
certManager:
11
install: true # let garden install cert-manager
12
email: [email protected] # your email (required when requesting Let's Encrypt certificates)
13
issuer: acme # the type of issuer for the certificate generation (currently only Let's Encrypt ACME is supported)
14
acmeChallengeType: HTTP-01 # type of ACME challenge (currently only "HTTP-01" is supported)
15
acmeServer: letsencrypt-staging # the ACME server to use ("letsencrypt-staging" or "letsencrypt-prod")
16
tlsCertificates:
17
...
Copied!
Unless you want to use your own installation of cert-manager, you will need to set the option
install: true. Garden will then install cert-manager for you under the cert-manager namespace.Note: Garden will wait until all the pods required by cert-manager will be up and running. This might take more than 2 minutes depending on the cluster.
If nothing is specified or
install: false, Garden will assume you already have a valid and running cert-manager installation in the cert-manager namespace.A valid email address is also required for Let's Encrypt certificate requests.
Issuing your first certificate
cert-manager is a powerful tool with a lot of different possible configurations. While integrating it with Garden we decided to start with an opinionated setup which should get you up to speed quickly, without thinking too much about configuration. If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the
tlsCertificates[].managedBy config field.Example
When you set
managedBy: cert-manager on a certificate specified in the tlsCertificates field, Garden creates a corresponding Certificate resource:1
kind: Project
2
name: cert-manager-example
3
environments:
4
- name: remote-dev
5
providers:
6
- name: kubernetes
7
context: your-remote-k8s-cluster-context
8
...
9
certManager:
10
install: true
11
email: [email protected]
12
issuer: acme
13
acmeChallengeType: HTTP-01
14
acmeServer: letsencrypt-staging
15
tlsCertificates:
16
- name: example-certificate-staging-01
17
managedBy: cert-manager # allow cert-manager to manage this certificate
18
hostnames:
19
- your-domain-name.com # the domain name(s) to be covered by the certificate
20
secretRef:
21
name: tls-secret-for-certificate # the secret where cert-manager will store the TLS certificate once it's generated
22
namespace: cert-manager-example
Copied!
The above configuration will trigger the following workflow:
- 1.cert-manager will create a ClusterIssuer in your cluster which will generate your certificate. Each certificate gets an associated ClusterIssuer, which will take care of performing the issue challenge.
- 2.Garden will then create a Certificate resource to request the TLS certificate.
- 3.cert-manager will then automatically create an Ingress to solve the HTTP-01 ACME challenge.
- 4.Once the challenge is solved the TLS certificate will be stored as a Secret using the name/namespace specified above (e.g.
cert-manager-example/tls-secret-for-certificate).
All the steps above will happen at system startup/init. All your services will be built/tested/deployed after all the secrets have been populated.
Troubleshooting
The certificate creation timeouts and garden terminates
Please make sure your domain name is pointing at the right IP address.
The best way to figure out why a certificate is not being generated is using
kubectl describe.You can list all the
Certificate resources with:1
$: kubectl get Certificates -n your-namespace
Copied!
and you can describe the failing Certificate with:
1
$: kubectl describe Certificate certificate-name -n your-namespace
Copied!
Please find more info in the "Issuing an ACME certificate using HTTP validation" guide in the official cert-manager documentation.
If have any issue, find a bug, or something is not clear from the documentation, please don't hesitate opening a new GitHub issue or ask us questions in our Slack channel.
Last modified 17d ago