Configure a Custom Domain

Configure a custom domain during installation

Kommander supports configuring a custom domain name for accessing the DKP UI and other platform services. Additionally, you can provide a custom certificate for each domain, or one can be issued automatically by Let’s Encrypt, or other certificate authorities supporting the ACME protocol. Refer to Custom domains and certificates configuration for more information on use cases and alternatives.

This section provides instructions and examples on how to configure the DKP installation to add a customized domain and certificate on your Essential cluster or your Management cluster. If you want to customize the domain and certificate on any Attached or Managed cluster, refer to Configure a custom domain and certificate for your cluster.

Prerequisite

Review the DKP Install Configuration page to gain better understanding of how to initialize and edit a configuration file.

Configure a custom domain

To configure Kommander to use a custom domain, the domain name must be provided in an installation config file. For example, to use the domain mycluster.example.com, create the following file:

CODE

apiVersion: config.kommander.mesosphere.io/v1alpha1
kind: Installation
clusterHostname: <mycluster.example.com>

This configuration can be used when installing or reconfiguring Kommander by passing it to the dkp install kommander command:

CODE

dkp install kommander --installer-config <config_file.yaml>

To ensure Kommander is installed on the right cluster, use the --kubeconfig=cluster_name.conf flag as an alternative to KUBECONFIG.

After the command completes, obtain the cluster ingress IP address or hostname using the following command:

CODE

kubectl -n kommander get svc kommander-traefik -o go-template='{{with index .status.loadBalancer.ingress 0}}{{or .hostname .ip}}{{end}}{{ "\n"}}'

Next, create a DNS record (for example, by using external-dns) for your custom hostname that resolves to the cluster ingress load balancer hostname or IP address. If the previous command returns a hostname, you should create a CNAME DNS entry that resolves to that hostname. If the cluster ingress is an IP address, create a DNS A record.

The domain must be resolvable from the client (your browser) and from the cluster. If you set up an external-dns service, it will take care of pointing the DNS record to the ingress of the cluster automatically. If you are manually creating a DNS record, you have to install Kommander first to obtain the load balancer address required for the DNS record. Refer to the examples below for more details on how and when to set up the DNS record.

Configure a custom certificate

If you want to use your own certificate for the configured domain, you need the following files (in PEM format):

The certificate
The certificate’s private key
The CA bundle (containing the root and intermediate certificates)

Specify the local file path to these files in the installation config file:

CODE

apiVersion: config.kommander.mesosphere.io/v1alpha1
kind: Installation

clusterHostname: <mycluster.example.com>
ingressCertificate:
  certificate: <certs/cert.pem>
  private_key: <certs/key.pem>
  ca: <certs/ca.pem>

Certificates that support ACME

You can configure the cert-manager to automatically issue a trusted certificate for the configured custom domain. The cert-manager also takes care of renewing the certificate before expiration.

The certificate must be supported by the Automatic Certificate Management Environment or ACME protocol.

Before you start, gather all relevant information (domain, email, keys, PEM file, others) from your certificate provider. In the following, we provide a few examples:

Let’s Encrypt

What you need

Your domain name
Your email
Basic understanding of how to initialize, configure and run a configuration file

Configure Let’s Encrypt

This section provides information on how to set up a Let’s Encrypt certificate for the cluster ingress. This allows most browsers to validate the certificate for the cluster when users try to log into the operations portal. DKP allows setting up Let’s Encrypt in a few simple steps.

Open the 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.
Provide the acquired domain name in the clusterHostname field, enable acme, and add an email to register with Let's encrypt.
CODE
```
apiVersion: config.kommander.mesosphere.io/v1alpha1
kind: Installation
clusterHostname: mycluster.example.com
acme:
  email: <your_email>
```
NOTE: Let’s Encrypt uses this email to contact you about expiring certificates, and issues related to your account.
Create a DNS record and install Kommander:
1. You can set 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.
  In this case: FIRST, set up the external-dns in the kommander.yaml. THEN use the configuration file to install Kommander.
2. Alternatively, create a DNS record manually, that maps your domain name or IP address to the cluster ingress.
  In this case: FIRST, use the configuration file to install Kommander and wait for the load balancer address to be provisioned. THEN manually create the DNS record pointing to the load balancer address.

ZeroSSL

What you need

Your domain name
Your email
An access and a secret key provided by ZeroSSL
Basic understanding of how to initialize, configure and run a configuration file

Configure ZeroSSL

This section provides information on how to set up a ZeroSSL certificate for the cluster ingress. This allows most browsers to validate the certificate for the cluster when users try to log into the operations portal.

Open the 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.

Provide the acquired domain name in the clusterHostname field, enable acme, and add an email and server to register with ZeroSSL's.

CODE

apiVersion: config.kommander.mesosphere.io/v1alpha1
kind: Installation
clusterHostname: <mycluster.example.com>
acme:
  email: <email>
  server: https://acme.zerossl.com/v2/DV90

Create a DNS record:
1. You can set 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.
2. Alternatively, create a DNS record manually, that maps your domain name or IP address to the cluster ingress.
Use the configuration file to install Kommander.
Set up External Account Bindings by customizing the Issuer or ClusterIssuer details, as shown in the Customize Issuer Details section.

Other ACME issuers

Open the 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.
You can use other issuers that support the ACME protocol by configuring the issuer’s server in the installation configuration, for example:
CODE
```
acme:
  email: <your_email>
  server: <your_server>
[...]
```
Create a DNS record and install Kommander:
1. You can set 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.
  In this case: FIRST, set up the external-dns in the kommander.yaml. THEN use the configuration file to install Kommander.
2. Alternatively, create a DNS record manually, that maps your domain name or IP address to the cluster ingress.
  In this case: FIRST, use the configuration file to install Kommander and wait for the load balancer address to be provisioned. THEN manually create the DNS record pointing to the load balancer address.

Some certificate authorities require setting additional fields for the custom configuration to work. Use the kubectl -n <namespace> patch command to configure any other additional fields in the Issuer or ClusterIssuer. For an example, refer to the ZeroSSL configuration.

Customize issuer details

By default, dkp install kommander sets up a working ACME solver using HTTP01 challenges. If further control over the certificate issuing is needed, you can modify the pre-configured ClusterIssuer. For example, you can use a DNS01 challenge:

CODE

cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: kommander-acme-issuer
spec:
  acme:
    email: <your_email>
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: kommander-acme-issuer-account
    solvers:
      - dns01:
          route53:
            region: us-east-1
            role: arn:aws:iam::YYYYYYYYYYYY:role/dns-manager
EOF

For more information on the available options, refer to the ACME section in the cert-manager documentation.

If you need to make changes in the configuration of your custom domain or certificate after you have installed DKP, modify the ingress in the KommanderCluster object as shown in the Custom domains and certificates configuration section.