jetstack/kube-lego repository overview

⁠kube-lego

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

⁠Screencast

⁠Features

• 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)

⁠Requirements

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

⁠Usage

⁠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:

metadata:
  annotations:
    kubernetes.io/tls-acme: "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:

spec:
  tls:
  - secretName: mysql-tls
    hosts:
    - phpmyadmin.example.com
    - mysql.example.com
  - secretName: postgres-tls
    hosts:
    - postgres.example.com

kube-lego will obtain two certificates (one with phpmyadmin.example.com and mysql.example.com, the other with postgers.example.com). 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)

##Ingress controllers

⁠Nginx Ingress Controller⁠

• available through image gcr.io/google_containers/nginx-ingress-controller
• fully supports kube-lego from version 0.8

⁠Environment variables

⁠Full example

See the examples⁠ directory.

⁠Authors

Christian Simon for Jetstack Ltd⁠