Migrating from Kube-LEGO
kube-lego is an older Jetstack project for obtaining TLS certificates from Let’s Encrypt (or another ACME server).
Since cert-managers release, kube-lego has been gradually deprecated in favor of this project. There are a number of key differences between the two:
|Configuration||Annotations on Ingress resources||CRDs|
|CAs||ACME||ACME, signing key pair|
|Debugging||Look at logs||Kubernetes Events API|
|Distinct issuance sources per Certificate||Not supported||Supported|
|Ingress controller support (ACME)||GCE, NGINX||All|
This guide will walk through how you can safely migrate your kube-lego installation to cert-manager, without service interruption.
By the end of the guide, we should have:
Scaled down and removed kube-lego
Migrated ACME private key to cert-manager
Created an ACME
ClusterIssuerusing this private key, to issue certificates throughout your cluster
ingress-shimto automatically provision Certificate resources for all Ingress resources with the
kubernetes.io/tls-acme: "true"annotation, using the
ClusterIssuerwe have created
Verified that the cert-manager installation is working
1. Scale down kube-lego
Before we begin deploying cert-manager, it is best we scale our kube-lego deployment down to 0 replicas. This will prevent the two controllers potentially ‘fighting’ each other. If you deployed kube-lego using the official deployment YAMLs, a command like so should do:
$ kubectl scale deployment kube-lego \ --namespace kube-lego \ --replicas=0
You can then verify your kube-lego pod is no longer running with:
$ kubectl get pods --namespace kube-lego
2. Deploy cert-manager
cert-manager should be deployed using Helm, according to our official installation guide. No special steps are required here. We will return to this deployment at the end of this guide and perform an upgrade of some of the CLI flags we deploy cert-manager with however.
Please take extra care to ensure you have configured RBAC correctly when deploying Helm and cert-manager - there are some nuances described in our deploying document!
3. Obtaining your ACME account private key
In order to continue issuing and renewing certificates on your behalf, we need to migrate the user account private key that kube-lego has created for you over to cert-manager.
Your ACME user account identity is a private key, stored in a secret resource.
By default, kube-lego will store this key in a secret named
in the same namespace as your kube-lego Deployment. You may have overridden this
value when you deploy kube-lego, in which case the secret name to use will be
the value of the
LEGO_SECRET_NAME environment variable.
You should download a copy of this secret resource and save it in your local directory:
$ kubectl get secret kube-lego-account -o yaml \ --namespace kube-lego \ --export > kube-lego-account.yaml
Once saved, open up this file and change the
metadata.name field to something
more relevant to cert-manager. For the rest of this guide, we’ll assume you
Once done, we need to create this new resource in the
By default, cert-manager stores supporting resources for
ClusterIssuers in the
namespace that it is running in, and we used
kube-system when deploying
cert-manager above. You should change this if you have deployed cert-manager
into a different namespace.
$ kubectl create -f kube-lego-account.yaml \ --namespace kube-system
4. Creating an ACME
ClusterIssuer using your old ACME account
We need to create a
ClusterIssuer which will hold information about the ACME
account previously registered via kube-lego. In order to do so, we need two more
pieces of information from our old kube-lego deployment: the server URL of the
ACME server, and the email address used to register the account.
Both of these bits of information are stored within the kube-lego
To retrieve them, you should be able to
$ kubectl get configmap kube-lego -o yaml \ --namespace kube-lego \ --export
Your email address should be shown under the
.data.lego.email field, and the
ACME server URL under
For the purposes of this guide, we will assume the email is
firstname.lastname@example.org and the URL
Now that we have migrated our private key to the new Secret resource, as well as
obtaining our ACME email address and URL, we can create a
Create a file named
apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: # Adjust the name here accordingly name: letsencrypt-staging spec: acme: # The ACME server URL server: https://acme-staging-v02.api.letsencrypt.org/directory # Email address used for ACME registration email: email@example.com # Name of a secret used to store the ACME account private key from step 3 privateKeySecretRef: name: letsencrypt-private-key # Enable the HTTP-01 challenge provider solvers: - http01: ingress: class: nginx
We then submit this file to our Kubernetes cluster:
$ kubectl create -f cluster-issuer.yaml
You should be able to verify the ACME account has been verified successfully:
$ kubectl describe clusterissuer letsencrypt-staging ... Status: Acme: Uri: https://acme-staging-v02.api.letsencrypt.org/acme/acct/7571319 Conditions: Last Transition Time: 2019-01-30T14:52:03Z Message: The ACME account was registered with the ACME server Reason: ACMEAccountRegistered Status: True Type: Ready
5. Configuring ingress-shim to use our new
ClusterIssuer by default
Now that our
ClusterIssuer is ready to issue certificates, we have one last
thing to do: we must reconfigure
ingress-shim (deployed as part of cert-manager)
to automatically create Certificate resources for all Ingress resources it finds
with appropriate annotations.
More information on the role of ingress-shim can be found in the
docs, but for now we can just run a
upgrade in order to add a few additional flags. Assuming you’ve named your
letsencrypt-staging (as above), run:
$ helm upgrade cert-manager \ jetstack/cert-manager \ --namespace kube-system \ --set ingressShim.defaultIssuerName=letsencrypt-staging \ --set ingressShim.defaultIssuerKind=ClusterIssuer
You should see the cert-manager pod be re-created, and once started it should automatically create Certificate resources for all of your ingresses that previously had kube-lego enabled.
6. Verify each ingress now has a corresponding Certificate
Before we finish, we should make sure there is now a Certificate resource for each ingress resource you previously enabled kube-lego on.
You should be able to check this by running:
$ kubectl get certificates --all-namespaces
There should be an entry for each ingress in your cluster with the kube-lego annotation.
We can also verify that cert-manager has ‘adopted’ the old TLS certificates by viewing the logs for cert-manager:
$ kubectl logs -n kube-system -l app=cert-manager -c cert-manager ... I1025 21:54:02.869269 1 sync.go:206] Certificate my-example-certificate scheduled for renewal in 292 hours
Here we can see cert-manager has verified the existing TLS certificate and scheduled it to be renewed in 292 hours time.