Skip to main content
Version: Next 🚧

Set up and use certificate issuers

Epinio comes with many cert-manager ClusterIssuers for creating certificates. By default, it installs the issuers epinio-ca and selfsigned-issuer. If requested it also installs either letsencrypt-staging or letsencrypt-production, to create certificates issued from Let's Encrypt.

  • epinio-ca (default)
  • selfsigned-issuer (internal)
  • letsencrypt-[staging|production] (optional)

You use the specified issuer for both Epinio API endpoint and workloads (that is, the pushed applications).

Choosing a different issuer

When installing Epinio with helm, you can choose between those issuers by using the global.tlsIssuer helm variable.

It's also possible to create a cert-manager cluster issuer in the cluster, before installing Epinio, and referencing it by name when installing, using global.customTlsIssuer.

When using either letsencrypt-staging or letsencrypt-production then use the global.tlsIssuerEmail helm variable to set an email address for the reception of the certificate notification e-mails sent by that issuer.

Cluster issuer for ACME DNS challenge

For an example, to use Let's Encrypt with a DNS challenge, which supports wildcards and private IP addresses, create this cluster issuer after installing cert-manager:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: dns-staging
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: example-issuer-account-key
solvers:
- dns01:
cloudflare:
email: user@example.com
apiKeySecretRef:
name: cloudflare-apikey-secret
key: apikey
selector:
dnsNames:
- 'example.com'
- '*.example.com'

This uses the Let's Encrypt staging endpoint for testing. There's more information in the cert-manager ACME documentation.

You then install Epinio with the global.tlsIssuer pointing to the new cluster issuer:

helm install epinio epinio/epinio --set global.tlsIssuer=dns-staging ...(other values here)

Cluster issuer for an existing private CA

According to the instructions from cert-manager, follow these steps:

Create secret with CA certificate and key

If you don't already have a private CA, use a tool like openssl or easy-rsa to create it.

The following one-liner creates a CA:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
-keyout example.key -out example.crt -subj "/CN=*.yourdomainhere.org"

Make sure the CN field matches the domain you are planning to use with Epinio.

Create a Kubernetes secret from the CA, in the cert-manager namespace.

kubectl create secret -n cert-manager tls private-ca-secret \
--cert=./example.crt --key=./example.key

The cert-manager documentation has more details about this.

Create ClusterIssuer

Then create the cluster issuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: private-ca
spec:
ca:
secretName: private-ca-secret

Install Epinio

Use the global.tlsIssuer variable to choose your cluster issuer:

helm install --set global.tlsIssuer=private-ca epinio epinio/epinio --global.domain=epinio.yourdomainhere.org

Background on Cert manager and issuers

Cert manager watches for a certificate resource and uses the referenced cluster issuer to generate a certificate. The certificate is stored in a secret, in the namespace the certificate resource was created in. An Ingress resource can then use that secret to set up TLS.

Example:

  1. The Epinio installation creates a certificate resource in the Epinio namespace

    apiVersion: cert-manager.io/v1alpha2
    kind: Certificate
    metadata:
    name: epinio
    namespace: epinio
    spec:
    commonName: epinio.172.27.0.2.omg.howdoi.website
    dnsNames:
    - epinio.172.27.0.2.omg.howdoi.website
    issuerRef:
    kind: ClusterIssuer
    name: epinio-ca
    secretName: epinio-tls
  2. cert-manager creates the 'epinio-tls' secret, using the referenced cluster issuer 'epinio-ca'

    apiVersion: v1
    kind: Secret
    type: kubernetes.io/tls
    metadata:
    annotations:
    cert-manager.io/alt-names: epinio.172.27.0.2.omg.howdoi.website
    cert-manager.io/certificate-name: epinio
    cert-manager.io/common-name: epinio.172.27.0.2.omg.howdoi.website
    cert-manager.io/ip-sans: ""
    cert-manager.io/issuer-group: ""
    cert-manager.io/issuer-kind: ClusterIssuer
    cert-manager.io/issuer-name: epinio-ca
    cert-manager.io/uri-sans: ""
    name: epinio-tls
    namespace: epinio
    data:
    ca.crt: ...
    tls.crt: ...
    tls.key: ...
  3. Epinio creates an ingress resource

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
    annotations:
    kubernetes.io/ingress.class: traefik
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.middlewares: epinio-epinio-api-auth@kubernetescrd
    traefik.ingress.kubernetes.io/router.tls: "true"
    labels:
    app.kubernetes.io/name: epinio
    name: epinio
    namespace: epinio
    spec:
    rules:
    - host: epinio.172.27.0.2.omg.howdoi.website
    http:
    paths:
    - backend:
    service:
    name: epinio-server
    port:
    number: 80
    path: /
    pathType: ImplementationSpecific
    tls:
    - hosts:
    - epinio.172.27.0.2.omg.howdoi.website
    secretName: epinio-tls

Epinio push

The same is true for applications, epinio push creates a certificate in the app's workspace and cert-manager creates a secret for the app's ingress.