Subdomains

Subdomain Modules provide infrastructure and configuration to launch and maintain subdomains through Nullstone. These modules enable developer self-service of subdomains and dynamic creation of URLs through environments.

Nullstone manages the registration of subdomains through the Nullstone UI. The Nullstone UI constructs Terraform workspaces for the necessary subdomains.

WARNING

If a developer has Architect access on the global stack, they have the ability to manage domains. Your organization should protect your domains by restricting Architect access to the global stack.

This guide discusses the practices and techniques used by Nullstone to construct DNS records.

Delegator

The official Nullstone modules delegate subdomains across AWS accounts. As an example, a subdomain like api.dev.acme.io is maintained in a dev AWS account.

To enable this delegation, the aws-domain module creates an AWS IAM user that has limited access to change its DNS zone. This delegator is passed to the aws-subdomain module to repoint the subdomain to a DNS zone in the dev AWS account.

Let's take an example using subdomain=api, env=dev, and domain=acme.io. In the dev AWS account, a new DNS zone named api.dev.acme.io is created. In the production AWS account, the delegator creates NS records with the nameservers from the dev DNS zone.

Dynamic URLs

The official Nullstone modules provide automatic subdomain generation. These modules create a unique DNS zone based on:

domain name
dns_name specified by the user
the current environment
var.create_vanity

Examples for domain acme.io:

`dns_name`	`env`	`var.create_vanity`	`fqdn`
api	dev	false	api.dev.acme.io
api	staging	false	api.staging.acme.io
api	prod	true	api.acme.io

Terraform Data Sources

`ns_subdomain`

The name of the subdomain registered in Nullstone is normally not accessible to the Terraform module. The ns_subdomain data source provides automatic discovery of the subdomain based on the current workspace.

If you create a module using nullstone modules generate, a new subdomain.tf is created for you to help. This produces the following content where local.subdomain_dns_name is the registered subdomain name (does not include the domain name).

hcl

data "ns_subdomain" "this" {
  stack_id = data.ns_workspace.this.stack_id
  block_id = data.ns_workspace.this.block_id
}

locals {
  subdomain_dns_name = data.ns_subdomain.this.dns_name
}

`ns_connection.domain`

If you are creating a subdomain, you can use ns_subdomain to get the subdomain name, but the domain name is not immediately accessible. To achieve this, Nullstone utilizes a data source for establishing connections in the Nullstone UI.

The following snippet provides access to the necessary domain metadata.

hcl

data "ns_connection" "domain" {
  name = "domain"
  type = "domain/aws"
}

locals {
  domain_name        = data.ns_connection.domain.outputs.name
  domain_zone_id     = data.ns_connection.domain.outputs.zone_id
  domain_nameservers = data.ns_connection.domain.outputs.nameservers
  domain_delegator   = data.ns_connection.domain.outputs.delegator
}

TIP

The above example illustrates a domain's DNS zone registered in AWS. For DNS zones in different providers, change type from "domain/aws" to "domain/<provider>".

Subdomains ​

Delegator ​

Dynamic URLs ​

Terraform Data Sources ​