Skip to content
Automatically request certificates for Kubernetes Ingress resources from Let's Encrypt
Branch: master
Clone or download
Latest commit d9ff008 Sep 6, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
examples Update VERSION May 8, 2018
pkg
tests
vendor Upgrade to dep 0.3.2. and latest client-go v4.0.0 Jan 16, 2018
.dockerignore
.gitignore
.gitlab-ci.yml Adds gitlab CI automation Mar 26, 2017
.travis.yml Update to golang v1.9.2 Jan 16, 2018
CHANGELOG.md Update CHANGELOG.md Jul 3, 2017
CONTRIBUTING.md Add DCO guide Sep 5, 2018
Dockerfile Run kube-lego as non root in docker image Mar 26, 2017
Gopkg.lock Upgrade to dep 0.3.2. and latest client-go v4.0.0 Jan 16, 2018
Gopkg.toml
Jenkinsfile
LICENSE Adds LICENSE May 3, 2016
Makefile
README.md Update README.md Apr 21, 2018
VERSION Update VERSION May 8, 2018
labels.yaml Adds labels Jan 16, 2018
main.go Parse any command line arguments using flag.Parse Mar 24, 2017
main_test.go Fix a typo in the test method name Mar 24, 2017

README.md

kube-lego

⚠️

kube-lego is in maintenance mode only. There is no plan to support any new features. The latest Kubernetes release that kube-lego officially supports is 1.8. The officially endorsed successor is cert-manager.

If you are a current user of kube-lego, you can find a migration guide here.

⚠️

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

Build Status

Screencast

Kube Lego screencast

Features

  • Recognizes the need of a new certificate for this cases:
    • No certificate existing
    • Existing certificate is not containing all domain names
    • Existing certificate is expired or near to its expiry date (cf. option LEGO_MINIMUM_VALIDITY)
    • Existing certificate is unparseable, invalid or not matching the secret key
  • 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)
  • Obtains the missing certificates from Let's Encrypt and authorizes the request with the HTTP-01 challenge
  • Makes sure that the specific Kubernetes objects (Services, Ingress) contain the rights configuration for the HTTP-01 challenge to succeed
  • Official Kubernetes Helm chart for simplistic deployment.

Requirements

  • Kubernetes 1.2+
  • Compatible ingress controller (nginx or GCE see here)
  • Non-production use case 😆

Usage

run kube-lego

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.

how kube-lego works

As soon as the kube-lego daemon is running, it will create a user account with LetsEncrypt, make a service resource, and look for ingress resources that have this annotation:

metadata:
  annotations:
    kubernetes.io/tls-acme: "true"

Every ingress resource that has this annotation 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 its own certificate through Let's Encrypt.

Let's take a look at this ingress resource:

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

On finding the above resource, the following happens:

  1. An ingress resource is created coordinating where to send acme challenges for the said domains.

  2. kube-lego will then perform its own check for i.e. http://mysql.example.com/.well-known/acme-challenge/_selftest to ensure all is well before reaching out to letsencrypt.

  3. kube-lego will obtain two certificates (one with phpmyadmin.example.com and mysql.example.com, the other with postgres.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)
  • Setups which utilize 1:1 NAT need to ensure internal resources can reach gateway controlled public addresses.
  • Additionally, your domain must point to your externally available Load Balancer (either directly or via 1:1 NAT)

Switching from staging to production

At some point you'll be ready to use LetsEncrypt production API URL. To make the switch in kube-lego, please do the following:

  • Update LEGO_URL to https://acme-v01.api.letsencrypt.org/directory.
  • Delete the existing k8s secret kube-lego-account.
  • Delete other secrets that hold data for certificates you want to replace.
  • Restart 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 onwards

GCE Loadbalancers

  • you don't have to maintain the ingress controller yourself, you pay GCE to do that for you
  • every ingress resource creates one GCE load balancer
  • all service that you want to expose, have to be Type=NodePort

Environment variables

Name Required Default Description
LEGO_EMAIL y - E-Mail address for the ACME account, used to recover from lost secrets
LEGO_POD_IP y - Pod IP address (use the downward API)
LEGO_NAMESPACE n default Namespace where kube-lego is running in
LEGO_URL n https://acme-staging.api.letsencrypt.org/directory URL for the ACME server. To get "real" certificates set to the production API of Let's Encrypt: https://acme-v01.api.letsencrypt.org/directory
LEGO_SECRET_NAME n kube-lego-account Name of the secret in the same namespace that contains ACME account secret
LEGO_SERVICE_SELECTOR n kube-lego Set the service selector to the the kube-lego pod
LEGO_SERVICE_NAME_NGINX n kube-lego-nginx Service name for NGINX ingress
LEGO_SERVICE_NAME_GCE n kube-lego-gce Service name for GCE ingress
LEGO_SUPPORTED_INGRESS_CLASS n nginx,gce Specify the supported ingress class
LEGO_SUPPORTED_INGRESS_PROVIDER n nginx,gce Specify the supported ingress provider
LEGO_INGRESS_NAME_NGINX n kube-lego-nginx Ingress name which contains the routing for HTTP verification for nginx ingress
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)
LEGO_MINIMUM_VALIDITY n 720h (30 days) Request a renewal when the remaining certificate validity falls below that value
LEGO_DEFAULT_INGRESS_CLASS n nginx Default ingress class for resources without specification
LEGO_DEFAULT_INGRESS_PROVIDER n $LEGO_DEFAULT_INGRESS_CLASS Default ingress provider for resources without specification
LEGO_KUBE_API_URL n http://127.0.0.1:8080 API server URL
LEGO_LOG_LEVEL n info Set log level (debug, info, warn or error)
LEGO_LOG_TYPE n text Set log type. Only json as custom value supported, everything else defaults to default logrus textFormat
LEGO_KUBE_ANNOTATION n kubernetes.io/tls-acme Set the ingress annotation used by this instance of kube-lego to get certificate for from Let's Encrypt. Allows you to run kube-lego against staging and production LE
LEGO_WATCH_NAMESPACE n `` Namespace that kube-lego should watch for ingresses and services
LEGO_RSA_KEYSIZE n 2048 Size of the private RSA key
LEGO_EXPONENTIAL_BACKOFF_MAX_ELAPSED_TIME n 5m Max time to wait for each domain authorization attempt
LEGO_EXPONENTIAL_BACKOFF_MAX_INITIAL_INTERVAL n 30s Initial interval to wait for each domain authorization attempt
LEGO_EXPONENTIAL_BACKOFF_MAX_MULTIPLIER n 2.0 Multiplier for every step

Full deployment examples

Troubleshooting

When interacting with kube-lego, its a good idea to run with LEGO_LOG_LEVEL=debug for more verbose details. Additionally, be aware of the automatically created resources (see environment variables) when cleaning up or testing.

Possible resources for help:

  • The official channel #kube-lego #cert-manager on kubernetes.slack.com (The old channel was renamed)

There is also a good chance to get some support on non-official support channels for kube-lego, but be aware that these are rather general kubernetes discussion channels.

  • #coreos on freenode
  • Slack channels like #kubernetes-users or #kubernetes-novice on kubernetes.slack.com
  • If you absolutely just can't figure out your problem, file an issue.

Enable the pprof tool

To enable the pprof tool run kube-lego with environment LEGO_LOG_LEVEL=debug.

Capture 20 seconds of the execution trace:

$ wget http://localhost:8080/debug/pprof/trace?seconds=20 -O kube-lego.trace

You can inspect the trace sample running

$ go tool trace kube-lego.trace

Authors

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.