Self-signed certificates and custom Certificate Authority (CA)

This document covers:

• Deploying openDesk into an environment with custom public key infrastructure (PKI) that is usually not part of public certificate authority chains
• deploying openDesk into a local cluster

Certificates

There are four options to address the certificate use case:

Option 0: ACME / in-tree

To have a better overview of all certificate use-cases, we list the ACME option here as well. As this is the default option and is widely used in conjunction with Let’s Encrypt, you can configure an organization-provided ACME endpoint here:

certificate:
  create: true
  issuerRef:
    name: "my-company-issuer"
    kind: "ClusterIssuer"
    group: "cert-manager.io"

Detailed information on how to create an ACME issuer or use any other supported in-tree issuer can be found in the cert-manager documentation.

Option 1: Bring Your Own Certificate

This option is useful when you have your own PKI in your environment which is also trusted by all clients that should access openDesk.

1. Disable cert-manager.io certificate resource creation:

   certificate:
     create: false

2. Create a Kubernetes secret named opendesk-certificates-tls of type kubernetes.io/tls containing either a valid wildcard certificate or a certificate with all required subdomains set as SANs (Subject Alternative Name).

Option 2: Use cert-manager.io with auto-generated namespace root-certificate

This option is useful when you do not have a trusted certificate available and want to quickly deploy openDesk. It will result in a cert-manager managed root certificate in the namespace you deploy openDesk into.

1. Configure certificates section:

   certificate:
     selfSigned: true
     selfSignedOverrides:
       issuer:
         create: true
       caCertificate:
         create: true

2. The generated root CA is stored in the secret opendesk-certificates-ca-tls. As this root certificate is not publicly trusted, you need to configure trust with that secret as the CA source:

   trust:
     create: true
     certificateAuthorities:
       secret: "opendesk-certificates-ca-tls"
     secret:
       mount: true
       name: "opendesk-certificates-ca-bundle-tls"

Option 3: Use EJBCA with cert-manager.io

In case you run an open-source EJBCA instance and have properly configured the Keyfactor cert-manager issuer for it, you can point openDesk at the resulting ClusterIssuer. The standalone opendesk-ejbca helper chart from the opendesk-certificates repository can create that ClusterIssuer and its credential secrets for you; it is not part of the openDesk deployment itself. Reference the issuer through certificate.issuerRef:

certificate:
  selfSigned: true
  issuerRef:
    name: "my-ejbca"
    kind: "ClusterIssuer"
    group: "ejbca-issuer.keyfactor.com"
  selfSignedOverrides:
    organizations:
      - "MyOrg"
    privateKey:
      algorithm: "RSA"
      size: 4096

Trust

One of the challenging parts of self-signed certificates is distributing trust to clients and applications.

For eval purposes, openDesk contains a simple Job which bundles the debian ca-certificates¹ with custom provided certificates and mounts them into all cluster components.

You can enable it via:

trust:
  create: true
  secret:
    mount: true
    name: "opendesk-certificates-ca-bundle-tls"

You benefit from trust.create when adding your root certificates to the default debian ca-bundle. This can be achieved by either adding the root certificate as plain-text:

trust:
  certificateAuthorities:
    # Additional certificate authorities which should be added to trust bundle.
    # Certificates have to end with ".crt" to be added to the bundle.
    values:
      corporate.crt: |
        -----BEGIN CERTIFICATE-----
        ...

or from an existing secret:

trust:
  certificateAuthorities:
    secret: "my-ca-tls"

In case you want to use e.g. trust-manager, just create the certificate bundle with the name opendesk-certificates-ca-tls or change the name via

trust:
  create: false
  secret:
    mount: true
    name: "opendesk-certificates-ca-tls"

Please keep in mind that you have to provide a keystore and a truststore as well, so the certificates include:

• ca.crt
• keystore.jks
• truststore.jks