Customize Certificates

Verrazzano issues certificates to secure access from external clients to secure system endpoints.
A certificate from a certificate authority (CA) must be configured to issue the endpoint certificates in one of the following ways:

• Let Verrazzano generate a self-signed CA (the default).
• Configure a CA that you provide.
• Configure LetsEncrypt as the certificate issuer (requires OCI DNS).

In all cases, Verrazzano uses CertManager to manage the creation of certificates.

Use the Verrazzano self-signed CA

By default, Verrazzano creates its own self-signed CA. No configuration is required.

Use a custom CA

If you want to provide your own CA, you must:

• (Optional) Create your own signing key pair and CA certificate.

  For example, you can use the openssl CLI to create a key pair for the nip.io domain:

  # Generate a CA private key
  $ openssl genrsa -out tls.key 2048
  
  # Create a self signed certificate, valid for 10yrs with the 'signing' option set
  $ openssl req -x509 -new -nodes -key tls.key -subj "/CN=*.nip.io" -days 3650 -reqexts v3_req -extensions v3_ca -out tls.crt
  

  The output of these commands will be two files, tls.key and tls.crt, the key and certificate for your signing key pair. These files must be named in that manner for the next step.

  If you already have generated your own key pair, you must name the private key and certificate, tls.key and tls.crt, respectively. If your issuer represents an intermediate, ensure that tls.crt contains the issuer’s full chain in the correct order.

  You can find more details on providing your own CA, in the CertManager CA documentation.

• Save your signing key pair as a Kubernetes secret.

  $ kubectl create ns mynamespace
  $ kubectl create secret tls myca --namespace=mynamespace --cert=tls.crt --key=tls.key
  

• Specify the secret name and namespace location in the Verrazzano custom resource.

  The custom CA secret must be provided to CertManager using the following fields in spec.components.certManager.certificate.ca in the Verrazzano custom resource:

  • spec.components.certManager.certificate.ca.secretName
  • spec.components.certManager.certificate.ca.clusterResourceNamespace

For example, if you created a CA secret named myca in the namespace mynamespace, you would configure it as shown:

apiVersion: install.verrazzano.io/v1alpha1
kind: Verrazzano
metadata:
  name: custom-ca-example
spec:
  profile: dev
  components:
    certManager:
      certificate:
        ca:
          secretName: myca
          clusterResourceNamespace: mynamespace

Use LetsEncrypt certificates

You can configure Verrazzano to use certificates generated by LetsEncrypt. LetsEncrypt implements the ACME protocol, which provides a standard protocol for the automated issuance of certificates signed by a trusted authority. This is managed through the spec.components.certManager.certificate.acme field in the Verrazzano custom resource.

To configure CertManager to use LetsEncrypt as the certificates provider, you must configure a CertManager ACME provider with the following values in the Verrazzano custom resource:

• Set the spec.components.certManager.certificate.acme.provider field to letsEncrypt.
• Set the spec.components.certManager.certificate.acme.emailAddress field to a valid email address for the letsEncrypt account.
• (Optional) Set the spec.components.certManager.certificate.acme.environment field to either staging or production (the default).

The following example configures Verrazzano to use the LetsEncrypt production environment by default, with OCI DNS for DNS record management:

apiVersion: install.verrazzano.io/v1alpha1
kind: Verrazzano
metadata:
  name: letsencrypt-certs-example
spec:
  profile: dev
  components:
    certManager:
      certificate:
        acme:
          provider: letsEncrypt
          emailAddress: jane.doe@mycompany.com
    dns:
      oci:
        ociConfigSecret: oci
        dnsZoneCompartmentOCID: ocid1.compartment.oc1.....
        dnsZoneOCID: ocid1.dns-zone.oc1.....
        dnsZoneName: example.com

The following example configures Verrazzano to use the LetsEncrypt staging environment with OCI DNS:

apiVersion: install.verrazzano.io/v1alpha1
kind: Verrazzano
metadata:
  name: letsencrypt-certs-example
spec:
  profile: dev
  components:
    certManager:
      certificate:
        acme:
          provider: letsEncrypt
          emailAddress: jane.doe@mycompany.com
          environment: staging
    dns:
      oci:
        ociConfigSecret: oci
        dnsZoneCompartmentOCID: ocid1.compartment.oc1.....
        dnsZoneOCID: ocid1.dns-zone.oc1.....
        dnsZoneName: example.com

LetsEncrypt staging versus production

LetsEncrypt provides rate-limits on generated certificates to ensure fair usage across all clients. The production environment limits can be exceeded more frequently in environments where Verrazzano may be being installed or reinstalled frequently (like a test environment). This can result in failed installations due to rate limit exceptions on certificate generation.

In such environments, it is better to use the LetsEncrypt staging environment, which has much higher limits than the production environment. For test environments, the self-signed CA also may be more appropriate to completely avoid LetsEncrypt rate limits.