This Driver generates a new subdomain for a domain. It is intended for used with a wildcard DNS record.

Property Description
Resource type dns
Account type None



Name Type Description
domain string The domain under which to specify the subdomainFor example, staging.example.com
template string [Optional] A Go Template which should render to a valid DNS Name.




There must be a wildcard DNS Record configured for the domain name specified in domain. The record should point to the appropriate Load Balancer.

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.


The template string is evaluated as a Go Template. The Sprig library of template functions is also available. Note that the template string does not need to include any Go template structures. For example, the context placeholders can be used on their own to create friendly subdomains. For example:


will generate a subdomain made up of the Environment ID and the Application ID.


Use the humanitec/dns-wildcard Driver to provision a new subdomain under staging.hosted-domain.com for an app called wildcard-dns-example-app. The subdomain will include the name of the app and a random alphanumeric string.

Then the following dynamic Resource Definition should be added. Apply the following modifications as needed:

  • Adjust the criteria to the Matching Criteria to fit your setup.
  • Decide whether you need to co-provision an ingress resource as shown, and remove the provision section if not. See Routes for a discussion on how the networking Resource Types work together.

cat <<EOF > dynamic-dns.yaml
apiVersion: entity.humanitec.io/v1b1
kind: Definition
  id: dynamic-dns-wildcard
  driver_type: humanitec/dns-wildcard
  name: "Dynamic DNS Wildcard"
  type: dns
      domain: staging.hosted-domain.com
      template: \${context.app.id}-{{ randAlphaNum 4 | lower}}
    - app_id: wildcard-dns-example-app
      is_dependent: false

humctl create -f dynamic-dns.yaml

curl https://api.humanitec.io/orgs/my-org/resources/defs \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary '{
  "id": "dynamic-dns-wildcard",
  "name": "Dynamic DNS Wildcard",
  "type": "dns",
  "driver_type": "humanitec/dns-wildcard",
  "driver_inputs": {
    "values": {
      "domain": "staging.hosted-domain.com",
      "template": "${context.app.id}-{{ randAlphaNum 4 | lower}}"
  "criteria": [
      "app_id": "wildcard-dns-example-app"
  "provision": {
    "ingress": {
      "is_dependent": false

Use this Resource Definition for the Humanitec Terraform Provider:

resource "humanitec_resource_definition" "dns-wildcard" {
  id          = "dynamic-dns-wildcard"
  name        = "Dynamic DNS Wildcard"
  type        = "dns"
  driver_type = "humanitec/dns-wildcard"

  driver_inputs = {
    values_string = jsonencode({
      "domain"   = "staging.hosted-domain.com"
      "template" = "$${context.app.id}-{{ randAlphaNum 4 | lower}}" 

  provision = {
    ingress = {
      is_dependent = false

resource "humanitec_resource_definition_criteria" "dns-wildcard" {
  resource_definition_id = humanitec_resource_definition.dns-wildcard.id
  app_id                 = "wildcard-dns-example-app"