Manage DNS

Learn how to add and manage DNS in Humanitec.


DNS names provide a standard way to make services accessible on the public internet. In Kubernetes applications, DNS names are most often used with Ingress objects to map incoming requests to an external Load Balancer to workloads running inside the cluster.
In Humanitec, a DNS name is represented as a Resource of type dns. A TLS certificate is represented by a Resource of type tls-cert.
By default, Humanitec will automatically generate dynamic DNS name under the domain along with a valid SSL certificate. However, it is possible to configure different DNS names that will get picked up in different environments.

Dynamic DNS names

A Resource Definition can be used to define how new DNS names should be generated. In most cases, this involves creating a subdomain to an existing domain. Humanitec provides 3 drivers which can be used to dynamically generate DNS names as required on existing domains:
This driver assumes that a wildcard record exists in the appropriate zone file resolving all DNS requests on any subdomain to be directed to the cluster Load Balancer. The driver will generate new unique subdomains and requires a static wildcard TLS certificate.
By definition, this driver can only be used for environments in a single cluster as the wildcard Zonefile record can only point to a single IP.
This driver adds records to a Cloudflare Zonefile pointing at the Load Balancer for the relevant cluster. The driver will generate new unique subdomains.
This driver can be used with environments running on different clusters.
This driver adds records to a Route53 Hosted Zone pointing at the Load Balancer for the relevant cluster. The driver will generate new unique subdomains.
This driver can be used with environments running on different clusters.

Add Resource Definition

  • Start on the Resource Management screen and click on the Show all resources button. An overlay with all available resource categories and types will be presented to you.
  • Below Routing select DNS.
  • Choose an ID that you will use to identify the resource definition in Humanitec later.
  • Select a driver. Based on your resource driver, a form will be down with the required driver parameters which will be passed to the driver on every resource creation.
  • Fill out the connection parameters that Humanitec and click on Create.

Static DNS

The static driver type can be used to define static DNS names to be used for ingress.
As each workload that needs to be exposed requires a different DNS name the resource matching criteria used must exactly match the relevant workload.
Here is an example of the API call to create a Static Resource Definition where a workload called frontend-service in the production environment of the topic-share app will be exposed with the DNS name
curl --request POST \
--header "Authorization: Bearer $HUMANITEC_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"id": "fe-dns-name",
"type": "dns",
"driver_type": "humanitec/static",
"driver_inputs": {
"values": {
"host": ""
"criteria": [
"app_id": "topic-share",
"env_id": "production",
"res_id": "workloads.frontend-service"
}' \
Where $HUMANITEC_TOKEN is an appropriate authentication token.

TLS Certificates

Most ingress controllers support TLS termination in-cluster. For that, they need access to the TLS Certificate and Private Key. By default, the ingress Resource Definition resource will reference a tls-cert resource with the same Resource ID as the dns it is routing from. In order to satisfy that, the simplest thing to do is to create a tls-cert Resource Definition with the same matching criteria as that for the DNS resource definition.

Static TLS

If you have a static wildcard certificate that you want to to use, it can be injected by using the humanitec/template driver.
You will need a template defining the Secret manifest that will contain the certificate and also specify the secret name it will be injected with.
Here are the sections that need to be filled in:
Init Template
tlsSecretName: {{ .id }}-tls
Manifests Template
location: namespace
apiVersion: v1
kind: Secret
name: {{ .init.tlsSecretName }}
tls.crt: {{ .outputs.secrets.tls_crt | b64enc }}
tls.key: {{ .outputs.secrets.tls_key | b64enc }}
Values Template
tls_secret_name: {{ .init.tlsSecretName }}
Secrets Template
tls_crt: |
tls_key: |
Replacing the above with your actual keys and certificates.

Resolving TLS at the Load Balancer

It is also common to let cloud providers manage certificates at the edge - i.e. at the Load Balancer. In this case, no tls-cert resource is needed in the clutser. Instead, the ingress resource must be configured not to do TLS termination. If you are using the humanitec/ingress driver, you can simply set the no_tls field to true.