Skip to main content

Managing DNS Zones

Wayfinder simplifies DNS Zone

A DNS zone is used to host the DNS records for a particular domain. The DNS (Domain Name System) is a hierarchy of domains.

management by automatically installing and configuring the ExternalDNS Kubernetes package in each cluster that Wayfinder manages and where the cluster has been pre-configured with Ingress. This allows Wayfinder to dynamically control the delegation of child DNS zones in a DNS provider agnostic way.

This article guides Wayfinder administrators on creating both public and private DNS zones. This allows Wayfinder to automatically delegate child DNS zones from the given parent DNS zone. The delegated child DNS zones can either service applications or clusters within the specified stage and workspace(s) combination.

Create private DNS zones when you want to have internally-resolvable DNS entries that you can use within a private network. Private DNS zones cannot be resolved outside your network environment, so they can't be used to expose workloads on the public internet.

If you want to make workloads accessible on the public internet, use public DNS zones instead.

note

Users with tenant access to a multi-tenanted cluster cannot make DNS zones available to that multitenant cluster.


CLI Quick Reference

InstructionCLI Command
View a list of DNS Zoneswf get globaldnszones
View a DNS Zone's manifestwf get globaldnszones DNS-ZONE -o yaml
Output a DNS Zone's manifest to filewf get globaldnszones DNS-ZONE -o yaml > MyDNSZone.yaml
Apply a DNS Zone's manifest from filewf apply -f MyDNSZone.yaml

Overview

Supported Cloud DNS providers

Wayfinder supports the following main cloud DNS Providers:

You can use any of the above Cloud DNS providers, regardless of whether Wayfinder's instance is installed in an AWS account, Azure subscription, or GCP Project.

For public DNS zones, Wayfinder can create child zones for your clusters and applications across all three providers with a single configured zone. For private zones, you must configure a zone for each provider individually.


Prerequisites

When you create a public AWS DNS Zone you must:

  • Already be in control of the parent domain (e.g. 'mycompany.com') .
  • Configure a Cloud Access account

    When you add a cloud account, subscription, or project to Wayfinder, it gains the ability to manage specific cloud resources and facilitate cloud automation.

    of Cloud Access Type

    Access types are the types of automation that Wayfinder provides. Some of these are specific to development team automation, while others revolve around platform services, ultimately delivering an end-to-end experience to end-users.

    'DNS Provisioning' before you create DNS Zones.

When you create a private AWS DNS Zone:

For private DNS Zones you will need to know the IDs of the cloud provider networks in which to make the zone resolvable, and ensure Wayfinder has access to perform the DNS linking:

  • On AWS, one or more VPC ID in which you want the domain to be resolvable. If these are in a different AWS account to where you are creating the DNS zone, you will need to add an additional Cloud Access Config with DNS management for that account.
  • On Azure, one or more vNet resource IDs in which you want the domain to be resolvable. You must grant Wayfinder's Azure identity 'Network Contributor' access to the specified vNets.
  • On GCP, one or more VPC IDs in which you want the domain to be resolvable. You must grant Wayfinder's GCP identity access to this VPC.

A typical setup is to configure Wayfinder to make all private zones resolvable in a single network, then run a DNS resolver in that network which is used by your cloud estate, making private DNS resolvable throughout.


Workflow overview

For each DNS Zone that you want to configure, you need to:

  1. Decide which FQDN

    Fully Qualified Domain Name

    For public zones, you must be in control of the top-level domain e.g., if you enter "devapps.mycompany.com" as the FQDN then you must be in control of "mycompany.com".

    you want to use for the DNS Zone that Wayfinder creates and manages.
  2. Decide the scope for the child DNS Zones. It can service clusters

    Wayfinder automatically creates and manages child zones which applies to all clusters created in the specified workspace(s) and stage.

    Example: ws1-coolcluster.qa.mycompany.com

    Explanation: "coolcuster" refers to your cluster's name, "ws1" refers to the workspace, and "qa.mycompany.com" refers to the FQDN you specified in the previous step.

    or applications

    Wayfinder automatically creates and manages child zones which applies to all applications created in the specified workspace(s) and stage.

    Example: mycoolapp.devapps.mycompany.com

    Explanation: "mycoolapp" refers to your application's name and "devapps.mycompany.com" refers to the FQDN you specified in the previous step.

    within a given stage

    A stage is used to isolate and test resources at the infrastructure level. Adding a stage to a resource restricts its availability to that specific stage, such as development or production.

    and workspace(s)

    A workspace is where teams provision and manage applications, environments, clusters, and cloud resources. Allocating a DNS zone to specific workspaces restricts it to creating child zones only within those workspaces.

    .
  3. Decide if you need to use public

    Create public DNS zones when you want to have publically-resolvable DNS entries and where workloads are exposed on the public internet.

    or private

    Create private DNS zones when you want to have internally-resolvable DNS entries that you can use within a private network. Private DNS zones cannot be resolved outside your network environment, so they can't be used to expose workloads on the public internet.

    DNS Zones.

Each child DNS zone that Wayfinder delegates has the following naming convention:

  • Application-level: APPLICATIONNAME.DNSZONE
  • Cluster-level: WORKSPACENAME-CLUSTERNAME.DNSZONE

FQDN Examples

Example 1: Application-level

A Wayfinder administrator configures a DNS Zone as follows:

  • Stage: non-prod
  • DNS zone should apply to: Applications
  • Workspace(s): All
  • FQDN: devapps.mycompany.com (you must have control over mycompany.com)

Then,

  • Wayfinder automatically creates and manages a child DNS zone called devapps.mycompany.com which applies to all applications in all workspaces in the non-prod stage.
  • Thereafter, Wayfinder uses the child DNS zone it created (devapps.mycompany.com) to automatically delegate child DNS zones for your applications (via ExternalDNS Kubernetes package), using the APPLICATIONNAME.DNSZONE naming convention.

Thereafter, a developer creates:

  • Application: coolapps
  • Environment: cooldev

Then,

  • Wayfinder automatically delegates a child DNS zone as: coolapps.devapps.mycompany.com
  • Wayfinder makes this available to the cluster hosting the environment cooldev
Example 2: Cluster-level

A Wayfinder administrator configures a DNS Zone as follow:

  • Stage: non-prod
  • DNS zone should apply to: Clusters
  • Workspace(s): ws1
  • FQDN: qa.mycompany.com (you must have control over mycompany.com)

Then,

  • Wayfinder automatically creates and manages a child DNS zone called qa.mycompany.com which applies to all clusters in the ws1 workspace in the non-prod stage.
  • Thereafter, Wayfinder uses the child DNS zone it created (qa.mycompany.com) to automatically delegate child DNS zones for your clusters (via ExternalDNS Kubernetes package), using the WORKSPACENAME-CLUSTERNAME.DNSZONE naming convention.

Thereafter, a Wayfinder administrator or Workspace Owner creates:

  • Cluster: coolclustr
  • Workspace: ws1

Then,

  • Wayfinder automatically delegates a child DNS zone as: ws1-coolclustr.qa.mycompany.com

Quick Start: Add a new DNS Zone

CLI Steps

The easiest way to create a new DNS Zone is to edit an existing one.

  1. Copy one of the existing DNS Zone configurations, by outputing the yaml to file.
  2. Update the details as needed
  3. Apply the yaml of the DNS Zone that you've edited.

Wayfinder's Web Interface Steps

  1. Expand Admin, then navigate to DNS.
  2. Click the + Global DNS Zone button.
  3. You are presented with the Add DNS Zone form. There are multiple sections you need to complete and they're outlined below:

1. Details Section Steps

  1. Enter the Name and the Description for the DNS Zone.
  2. Specify the FQDN

    Fully Qualified Domain Name

    For public zones, you must be in control of the top-level domain e.g., if you enter "devapps.mycompany.com" as the FQDN then you must be in control of "mycompany.com".

    for the DNS Zone that Wayfinder will create and manage for the child DNS Zones.

For more information about each field see the properties section.

Screenshots
Details Section

2. Scope Section Steps

  1. Select whether Wayfinder should automatically create child DNS Zones at the Application

    Wayfinder automatically creates and manages child zones which applies to all applications created in the specified workspace(s) and stage.

    Example: mycoolapp.devapps.mycompany.com

    Explanation: "mycoolapp" refers to your application's name and "devapps.mycompany.com" refers to the FQDN you specified in the previous step.

    or Cluster

    Wayfinder automatically creates and manages child zones which applies to all clusters created in the specified workspace(s) and stage.

    Example: ws1-coolcluster.qa.mycompany.com

    Explanation: "coolcuster" refers to your cluster's name, "ws1" refers to the workspace, and "qa.mycompany.com" refers to the FQDN you specified in the previous step.

    level.
  2. Select a Stage

    A stage is used to isolate and test resources at the infrastructure level. Adding a stage to a resource restricts its availability to that specific stage, such as development or production.

  3. Select one or more Workspaces

    A workspace is where teams provision and manage applications, environments, clusters, and cloud resources. Allocating a DNS zone to specific workspaces restricts it to creating child zones only within those workspaces.

For more information about each field see the properties section.

Screenshots
Scope Section

3. Provider Section Steps

  1. Select a Cloud DNS Provider

    Wayfinder supports the following main cloud DNS Providers:

    You can use any of the above Cloud DNS providers, regardless of whether Wayfinder's instance is installed in an AWS account, Azure subscription, or GCP Project.

    For public DNS zones, Wayfinder can create child zones for your clusters and applications across all three providers with a single configured zone. For private zones, you must configure a zone for each provider individually.

  2. Select the Cloud Access Configuration

    When you add a cloud account, subscription, or project to Wayfinder, it gains the ability to manage specific cloud resources and facilitate cloud automation.

  3. Select a region (only applicable when using Azure DNS - this sets the region of the resource group in which the DNS zone will be created; the zone itself is global)
  4. Select if the DNS Zone should be public

    Create public DNS zones when you want to have publically-resolvable DNS entries and where workloads are exposed on the public internet.

    or private

    Create private DNS zones when you want to have internally-resolvable DNS entries that you can use within a private network. Private DNS zones cannot be resolved outside your network environment, so they can't be used to expose workloads on the public internet.

For more information about each field see the properties section.

Screenshots

Public DNS Zone:

Provider Section - Public

Private DNS Zone:

Provider Section - Private

Azure DNS with region:

Provider Section - AWS with region

4. Linked Networks Section Steps (Private DNS Zones only)

  1. Click the + Add Network Link button.
  2. Fill in the provider specific fields.

For more information about each field see the properties section.

Screenshots

Add Network Link button:

Network Link - Add button

Fill in the details:

- AWS:

Network Link Details - AWS

- Azure:

Network Link Details - Azure

- GCP:

Network Link Details - GCP

Network Link Overview:

Network Link Details - Overview


5. Summary

  1. Verify that all the details are correct.
Screenshots

Public:

Summary Section - Public

Private:

Summary Section - Private


6. YAML

  1. Press the Apply button to apply the configuration.
  2. Alternatively, download the YAML and apply it using Wayfinder's CLI or your CI pipeline.

When using Wayfinder's web interface to apply the configuration:

  1. The DNS configuration progress is displayed. If there are any errors, then you need to fix them before you can proceed.
  2. Once the DNS Zone is created, Wayfinder informs you whether delegation is needed or not.
  3. If delegation is needed, press the Delegation button to continue, otherwise press Close.
Screenshots

YAML Overview:

YAML Overview

When you click on the Apply button:

YAML Overview - Applying

Wayfinder informs you that you need to Delegate:

YAML Overview - Ready to Delegate

Just press Close when no delegation is needed:

YAML Overview - Delegation not needed


7. Delegation

Where needed, you must complete the delegation to complete the DNS Zone configuration.

  1. Update the parent domain (e.g. mycompany.com) with the name servers (NS) records listed in Wayfinder. Each registrar

    A domain name registrar is an organisation that allows you to purchase a domain name such as "mycompany.com".

    has its own DNS management tools to change the NS records for a domain.

Example: Delegation Workflow

A Wayfinder administrator configures a DNS Zone as follows:

  • Parent domain: mycomapny.com
  • FQDN: devapps.mycomapny.com
  • Cloud DNS Provider: AWS Route53

Then,

  • Wayfinder creates devapps.mycomapny.com in AWS Route53.
  • AWS Route53 allocates the NS servers for devapps.mycomapny.com and tells Wayfinder what they are.
  • Wayfinder conveys those NS servers to the Wayfinder administrator.

Thereafter, the Wayfinder administrator,

  • Uses those NS servers to update the parent domain: 'mycomapny.com'

important
  1. Use all four NS records, regardless of the name of your domain. When you copy each NS record address, make sure you copy the trailing period at the end of the address. The trailing period indicates the end of a fully qualified domain name.
  2. It can take about 5 - 30 minutes for the updated NS records to propagate through DNS (sometimes longer). Wayfinder continues to check the status until the propagation finishes.

note

You are free to close the DNS Zone form whilst you wait for the NS records to propagate throught the DNS. To get back to the Delegation section:

  1. Expand Admin, and navigate to DNS
  2. Select the name of the DNS Zone you've created
  3. Select Status > Delegation from the sub navigation.

Screenshots

NS Records:

Delegation - NS Records

Successful completion of the delegation process:

Delegation - Success

DNS Zone Properties

Details Section Properties

This section specifies the general properties for the DNS Zone you're adding.

FieldDescription
NameThe name of this DNS Zone
DescriptionA meaningful description for this DNS Zone
DomainSpecify the FQDN

Fully Qualified Domain Name

For public zones, you must be in control of the top-level domain e.g., if you enter "devapps.mycompany.com" as the FQDN then you must be in control of "mycompany.com".

for the DNS Zone that Wayfinder will create and manage. You must already have control over the top-level domain. The FQDN must be unique per stage and workspace(s) combination.

Example: If you enter devapps.mycompany.com then you must already be in control of mycompany.com.

Scope Section Properties

This section specifies the scope properties for the DNS Zone you're adding.

FieldDescription
Auto provision child zones forThe level at which the child DNS Zones should be created.
Option(s):
- Applications
-- Child DNS Zones to be provisioned for each application

In Wayfinder, Applications are a way to model the elements of your applications (containers, cloud resources, environments, etc) to simplify deployment and provisioning. Applications should consist of things that follow the same software lifecycle and would typically be deployed together, although individual components can be deployed separately.

.
-- FORMAT: APPLICATIONNAME.DNSZONE
- Clusters
-- Child DNS Zones to be provisioned for each cluster

To get your application running on Wayfinder, you need a cluster. A cluster represents a dedicated, isolated Kubernetes cluster available for your workspace. It can be hosted in AWS, Google Cloud, or Microsoft Azure. Once you are in a Wayfinder workspace, you can access a cluster, and create one if needed.

.
-- FORMAT: WORKSPACENAME-CLUSTERNAME.DNSZONE
StageThe stage

A stage is used to isolate and test resources at the infrastructure level. Adding a stage to a resource restricts its availability to that specific stage, such as development or production.

to which this DNS Zone will be limited.
WorkspacesThe workspace(s)

A workspace is where teams provision and manage applications, environments, clusters, and cloud resources. Allocating a DNS zone to specific workspaces restricts it to creating child zones only within those workspaces.

to which this DNS Zone will be limited.
Option(s):
- All workspaces
- Specified workspaces
- None (Choose this option if you want to assign workspaces at a later time)

Provider Section Properties

This section specifies the provider properties for the DNS Zone you're adding.

  • Common properties across all providers
FieldDescription
DNS ProviderThe Cloud DNS Provider to use.
Option(s):
- AWS Route 53
- Azure DNS
- GCP Cloud DNS
Cloud Access ConfigurationThe cloud account, subscription or project where Wayfinder will create this DNS Zone. You must give Wayfinder access to the account, subscription or project before Wayfinder can create the DNS Zone. See prerequisites section.
Zone TypeThe type of the DNS Zone to create.
Option(s):
- Public: Creates a public DNS Zone.

Create public DNS zones when you want to have publically-resolvable DNS entries and where workloads are exposed on the public internet.

- Private: Creates a private DNS Zone.

Create private DNS zones when you want to have internally-resolvable DNS entries that you can use within a private network. Private DNS zones cannot be resolved outside your network environment, so they can't be used to expose workloads on the public internet.


  • Azure specific properties
FieldDescription
RegionThe region of the resource group in which the DNS zone will be created. The zone itself is global.

Provide Wayfinder with the details of the VPC/vNet that you have pre-configured within your cloud provider.

  • Common properties across all providers

FieldDescription
IDThe identifier of the VPC/vNet.
Option(s):
- AWS: VPC ID
- Azure: vNet ID
- GCP: VPC ID

  • AWS specific properties
FieldDescription
RegionThe region in which the VPC exists.
Cloud Access configurationThe AWS cloud account in which your VPC resides.

Note:

Wayfinder needs access to the AWS cloud account in which your VPC

Virtual Private Cloud (VPC)

When a private cloud solution is provided within a public cloud provider'a infrastructure:


resides.

If this VPC is in a different AWS account to the DNS zone, you must choose a cloud access configuration with DNS Zone Management feature (Cloud Access Type set to "DNS Provisioning") that will allow Wayfinder access to bind the DNS zone into that VPC. This is not needed if the VPC is in the same AWS account as the DNS zone.


View DNS Zones

Use the wf get globaldnszones command to view a list of existing DNS Zones.


wf get globaldnszones

NAME PROVIDER DOMAIN STATUS
aws-devapps-mycompany aws devapps.mycompany.com ActionRequired
azure-private-mycompany azure cluster.exampleorg.internal Success

Use the wf get globaldnszones DNS-ZONE with the -o yaml postfix to output the configuration of a specific DNS Zone to console.

wf get globaldnszones aws-devapps-mycompany -o yaml

apiVersion: dns.appvia.io/v2beta2
kind: GlobalDNSZone
metadata:
name: aws-devapps-mycompany
spec:
allocation:
type: workspaces
workspaces:
- sand2
childZoneMode: apps
childZoneScope: AllProviders
cloudAccessConfigRef:
name: aws-appvia-wf-devtest
workspace: admin
description: AWS App level DNS Zone (sand workspace)
domain: devapps.mycompany.com
privateZone: false
provider: aws
providerDetails:
aws: {}
type: AWS
stage: nonprod


In Wayfinder's web interface:

  • Expand Admin and then navigate to DNS
  • A list of available DNS Zones are displayed.
Screenshots
DNS Zones - Overview

To view the yaml:

  • Expand Admin, then navigate to DNS
  • A list of available DNS Zones are displayed.
  • Click on the name of the DNS Zone to open the form in Edit mode.
  • Select REVIEW > YAML from the sub-menu to view the YAML details.

Edit & Apply DNS Zones

  1. Output the DNS Zone configuration to file using the wf get globaldnszones DNS-ZONE command with the -o yaml > FILENAME.yaml postfix.
wf get globaldnszone aws-devapps-mycompany -o yaml > ./manifests/aws-devapps-mycompany.yaml

  1. Update the file as needed and use wf apply command with the -f PATH-TO-FILE.yaml flag to apply the changes.
important

Remember to update the object's name in the yaml file otherwise you will override the existing object when you apply it.

wf apply -f ./manifests/aws-devapps-mycompany.yaml

Using Wayfinder's web interface:

  • Expand Admin, then navigate to DNS
  • Click on the name of the DNS Zone to open the form in Edit mode.
  • Update as needed.
note

You will not be able to change some of the values such as the name of the DNS Zone, FQDN and Provider details. If they need changing then you need to create a new DNS Zone.

note

All validations must pass before you can re-apply the configuration.


YAML Examples

Public

apiVersion: dns.appvia.io/v2beta2
kind: GlobalDNSZone
metadata:
name: aws-devapps-mycompany
spec:
allocation:
type: workspaces
workspaces:
- sand2
childZoneMode: apps
childZoneScope: AllProviders
cloudAccessConfigRef:
name: aws-appvia-wf-devtest
workspace: admin
description: AWS App level DNS Zone (sand workspace)
domain: devapps.mycompany.com
privateZone: false <--- set to false
provider: aws
providerDetails:
aws: {}
type: AWS
stage: nonprod


Private

AWS

apiVersion: dns.appvia.io/v2beta2
kind: GlobalDNSZone
metadata:
name: aws-private-fields
spec:
provider: aws
childZoneMode: apps
providerDetails:
type: AWS
aws:
privateZoneVPCs:
- vpcID: vpc-0a1b2c3d4e5f67891 <--- needs VPC ID
cloudAccessConfigRef:
name: aws-appvia-wf-devtest <--- Cloud Access Config of VPC (see Network Link Properties section for when this is not needed)
workspace: admin
region: eu-west-2 <--- needs a region
description: AWS private fields example
domain: apps.exampleorg.internal
stage: nonprod
allocation:
type: all
privateZone: true <--- set to true
cloudAccessConfigRef:
name: aws-appvia-wf-devtest <--- Cloud Access Config of DNS Provider

Azure

wf get globaldnszones azure-private-mycompany -o yaml
apiVersion: dns.appvia.io/v2beta2
kind: GlobalDNSZone
metadata:
name: azure-private-mycompany
spec:
allocation:
type: workspaces
workspaces:
- sand2
childZoneMode: clusters
childZoneScope: SameProvider <--- WF instance and Cloud DNS provider is in same cloud
cloudAccessConfigRef:
name: az-dns
workspace: admin
description: Private DNS Zone Example
domain: cluster.exampleorg.internal
privateZone: true <--- set to true
provider: azure
providerDetails:
azure:
privateZoneVNetIDs: <--- needs vNet ID only
- >-
/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/myresourcegroup/providers/Microsoft.Network/virtualNetworks/myVnetName
region: uksouth
type: Azure
stage: nonprod


GCP

apiVersion: dns.appvia.io/v2beta2
kind: GlobalDNSZone
metadata:
name: aws-private-fields
spec:
provider: gcp
childZoneMode: apps
providerDetails:
type: GCP
gcp:
privateZoneVPCs: <--- needs VPC ID only
- projects/my-project/global/networks/my-vpc
description: AWS private fields example
domain: apps.exampleorg.internal
stage: nonprod
allocation:
type: none
privateZone: true <--- set to true
cloudAccessConfigRef:
name: gcp-dns