Kube Lego (Let’s Encrypt)

Dependencies

The way kube-lego works is by looking for annotations on Ingress and Service resources. Thus to use kube-lego, it’s necessary to first install an ingress controller.

Out of the box, kube-lego support 2 types of ingress controllers * GCE Load Balancers * Nginx Ingress Controller

Install

You can install kube-lego in a few different ways, but we recommend to use the Helmfile.

Install with Master Helmfile

  1. Set the KUBE_LEGO_EMAIL secret with chamber
  2. Run then install kube-lego using helmfile sync.

Install kube-lego

chamber write kops KUBE_LEGO_EMAIL [email protected]
chamber exec kops --selector chart=kube-lego sync

These are some of the environment variables you may want to configure:

  • KUBE_LEGO_REPLICA_COUNT - Count of kube-lego pods
  • KUBE_LEGO_IMAGE_TAG - Version of kube-lego image
  • KUBE_LEGO_DEBUG - Boolean to enabled debug mode. Defaults false
  • KUBE_LEGO_PROD - Boolean to enabled prod/stage mode. Defaults true

Environment variables can be specified in the Geodesic Module’s Dockerfile or using Chamber storage, which is recommended for all secrets.

Install with Custom Helmfile

Add to your Kubernetes Backing Services Helmfile this code

helmfile

repositories:
- name: cloudposse-incubator
  url: https://charts.cloudposse.com/incubator/

releases:
- name: tls
  namespace: kube-system
  labels:
    job: kube-system
  chart: cloudposse-incubator/kube-lego
  version: 0.1.2
  set:
    ### Optional: KUBE_LEGO_REPLICA_COUNT; e.g. 1
    - name: "replicaCount"
      value: '1'

    ### Optional: KUBE_LEGO_DEBUG; e.g. false
    - name: "debug"
      value: 'false'

    ## Image
    - name: "image.repository"
      value: "jetstack/kube-lego"

    ### Optional: KUBE_LEGO_IMAGE_TAG; e.g. 0.1.2
    - name: "image.tag"
      value: '0.1.5'

    - name: "image.pullPolicy"
      value: "IfNotPresent"

    ## Lego Settings
    ### Required: KUBE_LEGO_EMAIL; e.g. [email protected]
    - name: "lego.email"
      value: ''

    ### Optional: KUBE_LEGO_PROD; e.g. true
    - name: "lego.prod"
      value: 'true'

    ## Pod Settings
    - name: "pod.internalPort"
      value: "8080"

    ## Resources
    - name: "resources.limits.cpu"
      value: "200m"

    - name: "resources.limits.memory"
      value: "256Mi"

    - name: "resources.requests.cpu"
      value: "50m"

    - name: "resources.requests.memory"
      value: "128Mi"

Then follow the instructions for running helmfile sync.

Usage

To leverage kube-lego, you will need to add an annotations (e.g. kubernetes.io/tls-acme: "true") to the Ingress resource.

With these in place, then kube-lego will handle all e2e TLS certificate issueing and save the certificate from Let’s Encrypt to a secret specificied by the tls config.

Here are some examples:

ingress.yaml

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: chartmuseum
  annotations:
    kubernetes.io/tls-acme: "true"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: chartmuseum-service
          servicePort: 80
  tls:
  - secretName: chartmuseum-tls
    hosts:
    - example.com
    - www.example.com

values.yaml

## Ingress for load balancer
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
    kubernetes.io/tls-acme: "true"
  hosts:
    example.com:
      - /charts
      - /index.yaml
  tls:
    - secretName: chartmuseum-server-tls
      hosts:
      - example.com

helmfile

repositories:
- name: stable
  url: https://kubernetes-charts.storage.googleapis.com

releases:
- name: charts
  chart: stable/chartmuseum
  version: 1.3.1
  set:
  - name: ingress.enabled
    value: true
  - name: ingress.annotations.kubernetes\.io/ingress\.class
    value: nginx
  - name: ingress.annotations.kubernetes\.io/tls-acme
    value: true
  - name: ingress.hosts.example\.com[0]
    value: /charts
  - name: ingress.hosts.example\.com[1]
    value: /index.yaml
  - name: ingress.tls[0].secretName
    value: chartmuseum-server-tls
  - name: ingress.tls[0].hosts[0]
    value: example.com

Note

There is no unified specification for helm chart values structure. Different charts may have very different structures to values. The only way to know for sure what is supported is to refer to the chart manifests.

The examples provided here are based on the stable/chartmuseum chart https://github.com/kubernetes/charts/blob/master/stable/chartmuseum