New to Voyager? Please start here.

1. Install Cert-Manager

https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html

kubectl create namespace cert-manager
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.4.1/cert-manager.yaml

2. Setup Issuer/ClusterIssuer

Supported Issuer

These are the supported Certificate Issuers:

1. acme
2. ca
3. self signed
4. vault
5. venafi

Here we will show issuing certificates from Let’s Encrypt using ACME protocol. For others, click on the link for the respective issuers.

acme

The ACME Issuer type represents a single Account registered with the ACME server. When you create a new ACME Issuer, cert-manager will generate a private key which is used to identify you with the ACME server. To set up a basic ACME issuer, you should create a new Issuer or ClusterIssuer resource.

Issuer

Issuers (and ClusterIssuers) represent a certificate authority from which signed x509 certificates can be obtained, such as Let’s Encrypt. You will need at least one Issuer or ClusterIssuer in order to begin issuing certificates within your cluster.

Like this issuer.yaml

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-prod
  namespace: edge-services
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: [email protected]
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-prod
    # Enable HTTP01 validations
    solvers:
    - http01:
        ingress:
          class: voyager

The spec.email will be used to register for your let’s encrypt account and privateKeySecretRef will contain the private key of this account.

ClusterIssuer

An Issuer is a namespaced resource, and it is not possible to issue certificates from an Issuer in a different namespace. If you want to create a single issuer than can be consumed in multiple namespaces, you should consider creating a ClusterIssuer resource.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: [email protected]
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-prod
    # Enable HTTP01 validations
    solvers:
    - http01:
        ingress:
          class: voyager

When referencing a Secret resource in ClusterIssuer resources (eg spec.acme.solvers.dns01.cloudflare.apiKeySecretRef) the Secret needs to be in the same namespace as the cert-manager controller pod. You can optionally override this by using the --cluster-resource-namespace argument to the controller.

Let’s Encrypt Production vs Staging Environment

For production use, use the Let’s Encrypt Production API like above. For testing things out, you can use the Staging API as there is a rate limit for issuing certificates. Just replace the spec.acme.server like this

spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory

In this doc, we used the staging api and as a result, you will see that the certificate was issued by Fake LE Intermediate X1.

For more to know, visit here

Certificate Duration and Renewal Window

The default duration for all certificates is 90 days and the default renewal windows is 30 days. This means that certificates are considered valid for 3 months and renewal will be attempted within 1 month of expiration.

You can change that value using duration and renewBefore field in certificate.yaml,

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example
  namespace: edge-services
spec:
  secretName: example-tls
  duration: 24h
  renewBefore: 12h
  dnsNames:
    - foo.example.com
    - bar.example.com
  issuerRef:
    name: my-internal-ca
    kind: Issuer

That means, this certificate’s validity period is 24 hours and it will begin trying to renew 12 hours before the certificate expiration.