{"id":13463687,"url":"https://github.com/jetstack/kube-lego","last_synced_at":"2025-03-25T09:31:05.531Z","repository":{"id":39617163,"uuid":"53271768","full_name":"jetstack/kube-lego","owner":"jetstack","description":"DEPRECATED: Automatically request certificates for Kubernetes Ingress resources from Let's Encrypt","archived":true,"fork":false,"pushed_at":"2021-08-26T15:02:41.000Z","size":32325,"stargazers_count":2161,"open_issues_count":104,"forks_count":267,"subscribers_count":45,"default_branch":"master","last_synced_at":"2024-11-16T09:14:53.546Z","etag":null,"topics":["ingress","kubernetes","letsencrypt"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jetstack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-06T19:22:29.000Z","updated_at":"2024-09-29T11:30:39.000Z","dependencies_parsed_at":"2022-09-13T03:00:18.181Z","dependency_job_id":null,"html_url":"https://github.com/jetstack/kube-lego","commit_stats":null,"previous_names":["simonswine/kube-lego"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fkube-lego","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fkube-lego/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fkube-lego/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fkube-lego/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jetstack","download_url":"https://codeload.github.com/jetstack/kube-lego/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245435076,"owners_count":20614823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ingress","kubernetes","letsencrypt"],"created_at":"2024-07-31T14:00:26.518Z","updated_at":"2025-03-25T09:31:00.522Z","avatar_url":"https://github.com/jetstack.png","language":"Go","funding_links":[],"categories":["Tools","Secret generation and management","Go","kubernetes","Security \u0026 Compliance"],"sub_categories":["[Jenkins](#jenkins)"],"readme":"# kube-lego\n\n\u003e  :warning:\n\u003e\n\u003e  kube-lego is no longer maintained. The officially endorsed successor is **[cert-manager](https://github.com/jetstack/cert-manager/)**.\n\u003e\n\u003e  If you are a current user of kube-lego, you can find a migration guide [here](https://cert-manager.readthedocs.io/en/latest/tutorials/acme/migrating-from-kube-lego.html).\n\u003e\n\u003e  :warning:\n\n\n*kube-lego* automatically requests certificates for Kubernetes Ingress resources from Let's Encrypt\n\n[![Build Status](https://travis-ci.org/jetstack/kube-lego.svg?branch=master)](https://travis-ci.org/jetstack/kube-lego)\n[![](https://images.microbadger.com/badges/version/jetstack/kube-lego.svg)](http://microbadger.com/#/images/jetstack/kube-lego \"Get your own version badge on microbadger.com\")\n\n## Screencast\n\n[![Kube Lego screencast](https://asciinema.org/a/47444.png)](https://asciinema.org/a/47444)\n\n## Features\n\n- Recognizes the need of a new certificate for this cases:\n  - No certificate existing\n  - Existing certificate is not containing all domain names\n  - Existing certificate is expired or near to its expiry date (cf. option `LEGO_MINIMUM_VALIDITY`)\n  - Existing certificate is unparseable, invalid or not matching the secret key\n- 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`)\n- Obtains the missing certificates from Let's Encrypt and authorizes the request with the `HTTP-01` challenge\n- Makes sure that the specific Kubernetes objects (Services, Ingress) contain the rights configuration for the `HTTP-01` challenge to succeed\n- Official Kubernetes Helm [chart](https://github.com/kubernetes/charts/tree/master/stable/kube-lego) for simplistic deployment.\n\n## Requirements\n\n- Kubernetes 1.2+\n- Compatible ingress controller (nginx or GCE see [here](#ingress-controllers))\n- Non-production use case :laughing:\n\n## Usage\n\n### run kube-lego\n\n* [GCE](examples/gce/README.md)\n* [nginx controller](examples/nginx/README.md)\n\nThe 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.\n\n### how kube-lego works\n\nAs 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:\n\n```yaml\nmetadata:\n  annotations:\n    kubernetes.io/tls-acme: \"true\"\n```\n\nEvery 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.\n\nLet's take a look at this ingress resource:\n\n```yaml\nspec:\n  tls:\n  - secretName: mysql-tls\n    hosts:\n    - phpmyadmin.example.com\n    - mysql.example.com\n  - secretName: postgres-tls\n    hosts:\n    - postgres.example.com\n```\n\nOn finding the above resource, the following happens:\n\n1. An ingress resource is created coordinating where to send acme challenges for the said domains.\n\n2. *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.\n\n3. *kube-lego* will obtain two certificates (one with phpmyadmin.example.com and mysql.example.com, the other with postgres.example.com).\n\n\nPlease note:\n\n- The `secretName` statements have to be unique per namespace\n- `secretName` is required (even if no secret exists with that name, as it will be created by *kube-lego*)\n- Setups which utilize 1:1 NAT need to ensure internal resources can reach gateway controlled public addresses.\n- Additionally, your domain must point to your externally available Load Balancer (either directly or via 1:1 NAT)\n\n### Switching from staging to production\nAt some point you'll be ready to use LetsEncrypt production API URL. To make the switch in kube-lego, please do the following:\n* Update `LEGO_URL` to `https://acme-v01.api.letsencrypt.org/directory`.\n* Delete the existing k8s secret `kube-lego-account`.\n* Delete other secrets that hold data for certificates you want to replace.\n* Restart kube-lego.\n\n## Ingress controllers\n\n### [Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx/)\n\n- available through image `gcr.io/google_containers/nginx-ingress-controller`\n- fully supports kube-lego from version 0.8 onwards\n\n### [GCE Loadbalancers](https://github.com/kubernetes/ingress-gce/)\n\n- you don't have to maintain the ingress controller yourself, you pay GCE to do that for you\n- every ingress resource creates one GCE load balancer\n- all service that you want to expose, have to be `Type=NodePort`\n\n## Environment variables\n\n| Name | Required | Default | Description |\n|------|----------|---------|-------------|\n| `LEGO_EMAIL` | y | `-` | E-Mail address for the ACME account, used to recover from lost secrets |\n| `LEGO_POD_IP` | y | `-` | Pod IP address (use the [downward API](https://kubernetes.io/docs/tasks/configure-pod-container/environment-variable-expose-pod-information/#the-downward-api))|\n| `LEGO_NAMESPACE` | n | `default` | Namespace where kube-lego is running in |\n| `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` |\n| `LEGO_SECRET_NAME` | n | `kube-lego-account` | Name of the secret in the same namespace that contains ACME account secret |\n| `LEGO_SERVICE_SELECTOR` | n | `kube-lego` | Set the service selector to the the kube-lego pod |\n| `LEGO_SERVICE_NAME_NGINX` | n | `kube-lego-nginx` | Service name for NGINX ingress |\n| `LEGO_SERVICE_NAME_GCE` | n | `kube-lego-gce` | Service name for GCE ingress |\n| `LEGO_SUPPORTED_INGRESS_CLASS` | n | `nginx,gce` | Specify the supported ingress class |\n| `LEGO_SUPPORTED_INGRESS_PROVIDER` | n | `nginx,gce` | Specify the supported ingress provider |\n| `LEGO_INGRESS_NAME_NGINX` | n | `kube-lego-nginx` | Ingress name which contains the routing for HTTP verification for nginx ingress |\n| `LEGO_PORT` | n | `8080` | Port where this daemon is listening for verifcation calls (HTTP method) |\n| `LEGO_CHECK_INTERVAL` | n | `8h` | Interval for periodically certificate checks (to find expired certs) |\n| `LEGO_MINIMUM_VALIDITY` | n | `720h` (30 days) | Request a renewal when the remaining certificate validity falls below that value |\n| `LEGO_DEFAULT_INGRESS_CLASS` | n | `nginx` | Default ingress class for resources without specification|\n| `LEGO_DEFAULT_INGRESS_PROVIDER` | n | `$LEGO_DEFAULT_INGRESS_CLASS` | Default ingress provider for resources without specification |\n| `LEGO_KUBE_API_URL` | n | `http://127.0.0.1:8080` | API server URL |\n| `LEGO_LOG_LEVEL` | n | `info` | Set log level (`debug`, `info`, `warn` or `error`) |\n| `LEGO_LOG_TYPE` | n | `text` | Set log type. Only `json` as custom value supported, everything else defaults to default logrus textFormat |\n| `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 |\n| `LEGO_WATCH_NAMESPACE` | n | `` | Namespace that kube-lego should watch for ingresses and services |\n| `LEGO_RSA_KEYSIZE` | n | `2048` | Size of the private RSA key |\n| `LEGO_EXPONENTIAL_BACKOFF_MAX_ELAPSED_TIME` | n | `5m` | Max time to wait for each domain authorization attempt |\n| `LEGO_EXPONENTIAL_BACKOFF_MAX_INITIAL_INTERVAL` | n | `30s` | Initial interval to wait for each domain authorization attempt |\n| `LEGO_EXPONENTIAL_BACKOFF_MAX_MULTIPLIER` | n | `2.0` | Multiplier for every step |\n\n## Full deployment examples\n\n- [Nginx Ingress Controller](examples/nginx/)\n- [GCE Load Balancers](examples/gce/)\n\n## Troubleshooting\n\nWhen interacting with *kube-lego*, its a good idea to run with `LEGO_LOG_LEVEL=debug` for more verbose details.\nAdditionally, be aware of the automatically created resources (see environment variables) when cleaning up or testing.\n\nPossible resources for *help*:\n\n* The official channel ~~`#kube-lego`~~ `#cert-manager` on `kubernetes.slack.com` (The old channel was renamed)\n\n\u003e There is also a good chance to get some support on non-official support\n\u003e channels for *kube-lego*, but be aware that these are rather general\n\u003e kubernetes discussion channels.\n\n* `#coreos` on freenode\n* Slack channels like `#kubernetes-users` or `#kubernetes-novice` on `kubernetes.slack.com`\n* If you absolutely just can't figure out your problem, file an issue.\n\n\n### Enable the pprof tool\n\nTo enable the [pprof tool](https://golang.org/pkg/net/http/pprof/) run kube-lego with environment `LEGO_LOG_LEVEL=debug`.\n\nCapture 20 seconds of the execution trace:\n\n`$ wget http://localhost:8080/debug/pprof/trace?seconds=20 -O kube-lego.trace`\n\nYou can inspect the trace sample running\n\n`$ go tool trace kube-lego.trace`\n\n\n## Authors\n\n* Christian Simon for [Jetstack Ltd](http://www.jetstack.io)\n* [PR contributors](https://github.com/jetstack/kube-lego/graphs/contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetstack%2Fkube-lego","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjetstack%2Fkube-lego","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetstack%2Fkube-lego/lists"}