KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

kubernetes-letsencrypt

★ 114 Open GitHub ↗

A Kubernetes controller to retrieve Let's Encrypt certificates based on service annotations (unmaintained)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Kubernetes Letsencrypt Controller
=================================

[![Build Status](https://travis-ci.org/tazjin/kubernetes-letsencrypt.svg?branch=master)](https://travis-ci.org/tazjin/kubernetes-letsencrypt)

This implements a Kubernetes controller that automatically requests
and refreshes Letsencrypt certificates based on service annotations.

This controller currently supports _Amazon Route 53_ and _Google Cloud
DNS_ as the DNS targets.

## Setup

Launch the controller into your cluster using

```
kubectl apply -f letsencrypt-controller.yaml
```

This will use a release or snapshot version (depending on your git
checkout) hosted on my Docker Hub account.

The pod must run with the permissions required for updating records in
the DNS zones that you maintain.

On AWS, consider using a project such as [kube2iam][] to grant
permissions to individual pods.

Please refer to the 'Building' section for using your own image.

## Configuration

The controller currently supports three configuration options via
environment variables:

* `ACME_URL`: This can be set to an alternative ACME directory URL,
  for example the Letsencrypt staging server if you only want to test
  out the controller.
* `CLOUD_PLATFORM`: This can be set to either `GCP` or `AWS` to
  override the automatic platform detection. You can use this to for
  example use Route53 as the DNS backend with a cluster running on
  Google's Cloud Platform. If you override this option you must
  provide credentials for the DNS backend, for example via the
  environment variables for the [Google Cloud Java SDK][] or the
  [AWS Java SDK][]
* `LOG_LEVEL`: This can be used to set the log level to something
  other than the default (`INFO`).

## Usage

Simply add an annotation to your services, for example:

```
---
apiVersion: v1
kind: Service
metadata:
  name: my-app
  labels:
    app: my-app
  annotations:
    acme/certificate: www.yourdomain.com
spec:
  type: LoadBalancer
[...]
```

The controller will notice this and, assuming you have a matching
hosted zone, create a certificate and store it as a secret named
`www-yourdomain-com-tls`.

You can override the name of the secret by specifying an annotation
called `acme/secretName`.

You may specify multiple domains to include in a certificate as a JSON
array. This requires setting the `acme/secretName` annotation. For
example:

```
[...]
metadata:
  annotations:
    acme/certificate: '["yourdomain.com", "www.yourdomain.com"]'
    acme/secretName: mydomain-certificate
[...]
```

The certificate secret will contain four files named
`certificate.pem`, `chain.pem`, `key.pem` and `fullchain.pem`. You can
[mount these][] into whatever application you use to terminate TLS.

If required, you can configure these file names via the environment
variables, `CERTIFICATE_FILENAME`, `CHAIN_FILENAME`, `KEY_FILENAME`,
`FULLCHAIN_FILENAME`.

The secret will always be created in the same namespace as your
service. Removing the annotation will **never** remove a secret.

## Certificate renewals

Every secret will be annotated with the certificate expiry date. The
controller will refresh the certificate and update the secret once the
expiry date is close.

Currently this update happens within 1-2 days of expiry. The reason
for the short time-interval is that Letsencrypt has a long-term desire
to reduce the certificate lifespans so I am trying to be future-proof
here.

## Overview

The controller first attempts to find a secret in the Kubernetes
`kube-system` namespace with the name `letsencrypt-keypair`. This
secret is expected to contain the key pair used for authentication
with the Letsencrypt service.

If no such key pair is found the controller will create one and store
it as a secret.

On startup the controller will check all existing services for an
annotation

## Building

All build lifecycle steps are handled in Gradle. After determining
your desired image name, you can build a new image with:

```
# Run test suite
./gradlew test

# Create local Docker image
./gradlew dockerBuildImage
```

This will build an image locally with the tag
`tazjin/letsencrypt-controller:${VERSION}`, where `${VERSION}` is the
one specified in `build.gradle.kts`.

## Contributing

Feel free to contribute pull requests, file bugs and open issues with
feature suggestions!

Please follow the [code of conduct](CODE_OF_CONDUCT.md).

[kube2iam]: https://github.com/jtblin/kube2iam
[mount these]: http://kubernetes.io/docs/user-guide/secrets/#using-secrets-as-files-from-a-pod
[Google Cloud Java SDK]: https://github.com/GoogleCloudPlatform/google-cloud-java#authentication
[AWS Java SDK]: https://docs.aws.amazon.com/java-sdk/latest/developer-guide/credentials.html

kubernetes-letsencrypt

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README