Public Repository

Last pushed: 2 months ago
Short Description
Kube-Lego automatically requests certificates for Kubernetes Ingress resources from Let's Encrypt
Full Description


kube-lego automatically requests certificates for Kubernetes Ingress resources from Let's Encrypt



  • Recognizes the need of new certificates for this cases
    • domain name missing
    • certificate expired
    • certificate unparseable
  • Obtains certificates per TLS object in ingress resources and stores it in Kubernetes secrets using HTTP-01 challenge
  • Creates a user account (incl. private key) for Let's Encrypt and stores it in Kubernetes secrets (secret name is configurable via LEGO_SECRET_NAME)
  • Watches changes of ingress resources and reevaluate certificates
  • Configures endpoints for HTTP-01 challenge in a separate ingress resource (ingress name is configurable in LEGO_INGRESS_NAME)


  • Kubernetes 1.2+
  • Compatible ingress controller (cf. here)
  • Non-production use case :laughing:


run kube-lego

  • deployment for kube-lego
    • don't forget to configure LEGO_EMAIL with your mail address
    • the default value of LEGO_URL is the Let's Encrypt staging environment. If you want to get "real" certificates you have to configure their production env.
  • service pointing to kube-lego pods

how kube-lego works

As soon as the kube-lego daemon is running, it will look for ingress resources that have this annotations:

  annotations: "true"

Every ingress resource that has this annotations will be monitored by kube-lego (cluster-wide in all namespaces). The only part that is watched is the list spec.tls. Every element will get their own certificate through Let's encrypt.

Let's take a look at this ingress controller:

  - secretName: mysql-tls
  - secretName: postgres-tls

kube-lego will obtain two certificates (one with and, the other with Please note:

  • The secretName statements have to be unique per namespace
  • secretName is required (even if no secret exists with that name, as it will be created by kube-lego)


##<a name="ingress"></a>Ingress controllers

Nginx Ingress Controller

  • available through image
  • fully supports kube-lego from version 0.8

Environment variables

Name Required Default Description
LEGO_EMAIL y - E-Mail address for the ACME account, used to recover from lost secrets
LEGO_NAMESPACE n default Namespace where kube-lego is running in
LEGO_URL n URL for the ACME server
LEGO_SECRET_NAME n kube-lego-account Name of the secret in the same namespace that contains ACME account secret
LEGO_SERVICE_NAME n kube-lego Service name that connects to this pod
LEGO_INGRESS_NAME n kube-lego Ingress name which contains the routing for HTTP verification
LEGO_PORT n 8080 Port where this daemon is listening for verifcation calls (HTTP method)
LEGO_CHECK_INTERVAL n 8h Interval for periodically certificate checks (to find expired certs)

Full example

See the examples directory.


Christian Simon for Jetstack Ltd

Docker Pull Command