Managing Certificates

In order to secure the Cortex Helm deployment, it is advised to enable ssl on your cluster. You can either provide an SSL cert and its corresponding private key or you can configure cert-manager to automate issuing and renewal of certificates within your cluster.

If you are not providing your own certificate and key via helm overrides, it is recommended to deploy cert-manager in your kubernetes cluster and configure a ClusterIssuer resource against a CA.

Cert-manager has support for multiple issuers such as Vault, Letsencrypt, or self-signed (among others).

Cert-manager

The installation of cert-manager is streamlined to install the Custom Resource Definitions (CRDs) and cert-manager itself into a cert-manager namespace with a single kubectl apply command. The example below is using release v1.5.5 of cert-manager.

Installation

If you wish to customize the install or use other installation methods such as Helm, please reference the installation docs.

For the streamlined installation, both the CRD's and Installation can be completed with the following command:

$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.5/cert-manager.yaml

After the CRD's and cert-manager have been installed, you can verify that the pods are running:

kubectl get pods --namespace cert-manager

Setup Cluster Issuer

After cert-manager has been deployed into the cluster, you need to setup a ClusterIssuer to watch for and handle requests for certificates.

Although cert-manager has support for multiple types of issuers with different types of challenges (dns01 and http01) for domain validation, the recommended way is to use an ACME/LetsEncrypt issuer with DNS managed by Route53.

NOTE

While cert-manager has support for the http01 challenge, it is not recommended to use as it does not allow for issuing of wildcard certificates. The example that follows uses a dns01 challenge.

The following yaml file contains a ClusterIssuer resource that is configured against LetsEncrypt's staging environment with credentials to interact with Route53 and a secret resource to keep the AWS_SECRET_ACCESS_KEY from being stored in plain text. You will need to substitute the following variables accordingly:

• EMAIL: The email used for the certificate signing requests and receiving notifications about the certificate and its expiry
• HOSTED_ZONE: The hosted zone id from Route53 that this issuer will be managing; this can be the hosted zone id OR the domain of the hosted zone
• REGION: The region where your Route53 zone resides
• AWS_ACCESS_KEY_ID: The AWS access key with permissions to manage records in Route53
• B64_AWS_SECRET_ACCESS_KEY: The base64 encoded value of the secret access key

OPTIONAL: Change the spec.acme.server if you wish to use a different LetsEncrypt backend. The default is pointing to the prod environment, which isn't suitable for testing as request limits are enforced on that backend.

EXAMPLE

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
  namespace: cert-manager
spec:
  acme:
    email: ${EMAIL}
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: private-key
    solvers:
      - selector:
          dnsZones:
            - '${HOSTED_ZONE}'
        dns01:
          route53:
            region: ${REGION}
            accessKeyID: ${AWS_ACCESS_KEY_ID}
            secretAccessKeySecretRef:
              name: cert-manager-route53
              key: secret-key
---
apiVersion: v1
kind: Secret
metadata:
  name: cert-manager-route53
  namespace: cert-manager
type: Opaque
data:
  secret-key: $(B64_AWS_SECRET_ACCESS_KEY)

After the values have been updated, apply the file with kubectl:

kubectl apply -f issuer.yaml

Cortex and Cert-Manager

In order for the Ingress routes created by Cortex to be discovered by cert-manager, you must set the name of the ClusterIssuer used by Cortex in the value overrides before updating Cortex via helm.

The following settings must be made in the values.yaml:

certManager:
  enabled: true
  issuer:
    name: "letsencrypt"

Verification

Now that cert-manager and Cortex have been deployed and a ClusterIssuer configured, you should see Certificate resources being created/issued in the cortex namespace.