Skip to main content
Skip table of contents

Configure the Kommander Installation with a Custom Domain and Certificate

This page contains instructions on how to set up custom certificates for your Management or Essential cluster during the installation of DKP.

There are two configuration methods:

Configuration Method

WHILE installing the Kommander component

AFTER installing the Kommander component

Supported cluster types

Only Essential or Management clusters

All cluster types

Documentation

Remain in this page

Go to Configure Custom Domains or Custom Certificates post Kommander Installation

Configuration Options

  • Choose an ACME-supported Certificate Authority, if you want the cert-manager to automatically handle certificate renewal and rotation.

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

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 ONE time, 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 Certificate Issuer and KommanderCluster 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

      (warning) 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.
      (info) In on-premise environments, replace the annotation in the previous example with traefik.ingress.kubernetes.io/router.tls: "true".

    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

      (warning) The values kommander-acme-issuer, kommander-acme-issuer-account 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 the external-dns service. This way, the external-dns will take care of pointing the DNS record to the ingress of the cluster automatically.
    (info) You can also create a DNS record manually, that maps your domain name or IP address to the cluster ingress. If you choose to create a DNS record manually, finish installing the Kommander component, and then manually create a DNS record that points 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:

Verify and Troubleshoot the Domain and Certificate Customization

Related Topics:

JavaScript errors detected

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

If this problem persists, please contact our support.