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:
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:
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:
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:
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: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.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, enableacme
, and add anemail
to register with Let's encrypt.CODEapiVersion: 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:
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 theexternal-dns
in thekommander.yaml
. THEN use the configuration file to install Kommander.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: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.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, enableacme
, and add anemail
andserver
to register with ZeroSSL's.CODEapiVersion: 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:
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.Alternatively, create a DNS record manually, that maps your domain name or IP address to the cluster ingress.
Set up External Account Bindings by customizing the
Issuer
orClusterIssuer
details, as shown in the Customize Issuer Details section.
Other ACME issuers
Open the
kommander.yaml
file: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.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:
CODEacme: email: <your_email> server: <your_server> [...]
Create a DNS record and install Kommander:
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 theexternal-dns
in thekommander.yaml
. THEN use the configuration file to install Kommander.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:
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.