Skip to main content
Skip table of contents

Configure your Custom Domain and Certificate

This page contains instructions on how to set up custom certificates for your cluster during the installation of DKP. This allows most browsers to validate the certificate for the cluster when users try to log into the operations portal.

Refer to Certificate Authority (CA) Specifics for more information on values that are specific to your Certificate Authority or CA.

There are three main options:

I want to use an automatically-generated certificate with ACME and require basic configuration*

I want to use an automatically-generated certificate with ACME and require basic configuration*

When you enable ACME, by default DKP generates an ACME-supported certificate with an HTTP01 solver. The cert-manager automatically issues a trusted certificate for the configured custom domain, and takes care of renewing the certificate before expiration.

  1. Open the Kommander Installer Configuration File or <kommander.yaml> file:

    1. If you do not have the <kommander.yaml> file, initialize the configuration file, so you can edit it in the following steps. WARNING: Initialize this file only ONCE, otherwise you will overwrite previous customizations.

    2. If you have initialized the configuration file already, open the <kommander.yaml> with the editor of your choice.

  2. In that file, configure the custom domain for your cluster:

    CODE
    [...]
    clusterHostname: <mycluster.example.com>
    [...]
  3. Enable ACME by adding acme value, the issuer's server and your e-mail. If you don’t provide a server, DKP sets up Let's Encrypt as your certificate provider:

    CODE
    acme:
      email: <your_email>
      server: <your_server>
    [...]
  4. Use the configuration file to install Kommander.

*basic configuration: ACME server without EAB (External Account Bindings) and HTTP solver

I want to use an automatically-generated certificate with ACME and require advanced configuration (e.g. EAB, DNS solver, etc.)

I want to use an automatically-generated certificate with ACME and require advanced configuration

If you require additional configuration options like DNS solver, EAB, among others, create a ClusterIssuer with the required configurations before you run the installation of Kommander. The cert-manager automatically issues a trusted certificate for the configured custom domain, and takes care of renewing the certificate before expiration.

To read more about the ClusterIssuer, other objects, and where to store them, refer to Advanced Configuration: ClusterIssuer and Advanced Configuration: Important Concepts.

  1. Create a ClusterIssuer and store it in the target cluster. It must be called kommander-acme-issuer:

    1. If you require an HTTP solver, adapt the following example with the properties required for your certificate and execute the command:

      CODE
      cat <<EOF | kubectl apply -f -
      apiVersion: cert-manager.io/v1
      kind: ClusterIssuer
      metadata:
        name: kommander-acme-issuer # This part is important
      spec:
        acme:
          email: <your_email>
          server: <https://acme.server.example>
          skipTLSVerify: true
          privateKeySecretRef:
            name: kommander-acme-issuer-account # Set this to <name>-account
          solvers:
          - http01:
              ingress:
                ingressTemplate:
                  metadata:
                    annotations:
                      kubernetes.io/ingress.class: kommander-traefik
                      "traefik.ingress.kubernetes.io/router.priority": "2147483647"
      EOF

      Note: The values kommander-acme-issuer, kommander-acme-issuer-account and "traefik.ingress.kubernetes.io/router.priority": "2147483647" are not placeholders and MUST be filled out exactly as in the example.

    2. If you require a DNS solver, adapt the following example with the properties required for your certificate and execute the command:

      CODE
      cat <<EOF | kubectl apply -f -
      apiVersion: cert-manager.io/v1
      kind: ClusterIssuer
      metadata:
        name: kommander-acme-issuer # This part is important
      spec:
        acme:
          email: <your_email>
          server: <https://acme.server.example>
          privateKeySecretRef:
            name: kommander-acme-issuer-account # Set this to <name>-account
          solvers:
            - dns01:
                route53:
                  region: us-east-1
                  role: arn:aws:iam::YYYYYYYYYYYY:role/dns-manager
      EOF

      Note: The values kommander-acme-issuer, kommander-acme-issuer-account and "traefik.ingress.kubernetes.io/router.priority": "2147483647" are not placeholders and MUST be filled out exactly as in the example.

  2. Optional: If you require External Account Bindings to link your ACME account to an external database, refer to https://cert-manager.io/docs/configuration/acme/#external-account-bindings.

  3. Optional: Create a DNS record, by setting up an external-dns service. This way, the external-dns will take care of pointing the DNS record to the ingress of the cluster automatically.
    Note: You can also create a DNS record manually, that maps your domain name or IP address to the cluster ingress. In this case, finish installing Kommander and then manually create the DNS record pointing to the load balancer address.

  4. Open the Kommander Installer Configuration File or kommander.yaml file:

    1. If you do not have the kommander.yaml file, initialize the configuration file, so you can edit it in the following steps. WARNING: Initialize this file only ONCE, otherwise you will overwrite previous customizations.

    2. If you have initialized the configuration file already, open the kommander.yaml with the editor of your choice.

  5. In that file, configure the cluster to use your custom domain:

    CODE
    [...]
    clusterHostname: <mycluster.example.com>
    [...]
  6. Enable ACME by configuring the issuer’s server and your e-mail:

    CODE
    [...]
    acme:
      email: <your_email>
      server: <your_server>
    [...]
  7. Use the configuration file to install Kommander.

I have a manually-generated certificate

I have a manually-generated certificate

D2iQ supports the use of a manually-created certificate. In this case, there is no certificate controller that handles the renewal and update of your certificate automatically, so you will have to take care of these tasks manually.

Prerequisites: 

  • Obtain the PEM files of your certificate and store them in the target cluster’s namespace:

    • Certificate

    • certificate’s private key

    • CA bundle (containing the root and intermediate certificates)

Configure the manually-generated certificate

  1. Open the Kommander Installer Configuration File or <kommander.yaml> file:

    1. If you do not have the <kommander.yaml> file, initialize the configuration file, so you can edit it in the following steps. WARNING: Initialize this file only ONCE, otherwise you will overwrite previous customizations.

    2. If you have initialized the configuration file already, open the <kommander.yaml> with the editor of your choice.

  2. In the Kommander Installer Configuration file, provide your custom domain and the paths to the PEM files of your certificate:

    CODE
    [...]
    clusterHostname: <mycluster.example.com>
    ingressCertificate:
      certificate: <certs/cert.pem>
      private_key: <certs/key.pem>
      ca: <certs/ca.pem>
    [...]
  3. Use the configuration file to install Kommander.

Certificates issued by another Issuer

You can also configure a certificate issued by another Certificate Authority. In this case, the CA will determine which information to include in the configuration.

Next Step:

Verification and Troubleshooting for Custom Certificates

Related Topics:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.