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

Instruction	CLI Command
View a list of DNS Zones	`wf get globaldnszones`
View a DNS Zone's manifest	`wf get globaldnszones DNS-ZONE -o yaml`
Output a DNS Zone's manifest to file	`wf get globaldnszones DNS-ZONE -o yaml > MyDNSZone.yaml`
Apply a DNS Zone's manifest from file	`wf 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:

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.
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.
.
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.

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

Wayfinder's Web Interface Steps

Expand Admin, then navigate to DNS.
Click the + Global DNS Zone button.
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

Enter the Name and the Description for the DNS Zone.
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

2. Scope Section Steps

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.
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.
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

3. Provider Section Steps

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.
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.
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)
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:

Private DNS Zone:

Azure DNS with region:

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

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

For more information about each field see the properties section.

Screenshots

Add Network Link button:

Fill in the details:

- AWS:

- Azure:

- GCP:

Network Link Overview:

5. Summary

Verify that all the details are correct.

Screenshots

Public:

Private:

6. YAML

Press the Apply button to apply the configuration.
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:

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

Screenshots

YAML Overview:

When you click on the Apply button:

Wayfinder informs you that you need to Delegate:

Just press Close when no delegation is needed:

7. Delegation

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

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

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.
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:

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

Screenshots

NS Records:

Successful completion of the delegation process:

DNS Zone Properties

Details Section Properties

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

Field	Description
Name	The name of this DNS Zone
Description	A meaningful description for this DNS Zone
Domain	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. 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.

Field	Description
Auto provision child zones for	The 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`
Stage	The 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.
Workspaces	The 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

Field	Description
DNS Provider	The Cloud DNS Provider to use. Option(s): - AWS Route 53 - Azure DNS - GCP Cloud DNS
Cloud Access Configuration	The 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 Type	The 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

Field	Description
Region	The region of the resource group in which the DNS zone will be created. The zone itself is global.

Network Link Properties (Private DNS Zones only)

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

Common properties across all providers

Field	Description
ID	The identifier of the VPC/vNet. Option(s): - AWS: VPC ID - Azure: vNet ID - GCP: VPC ID

AWS specific properties

Field	Description
Region	The region in which the VPC exists.
Cloud Access configuration	The 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: AWS Azure GCP 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.

Field

Description

Region

The region in which the VPC exists.

Cloud Access configuration

The 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

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

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

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

CLI Quick Reference​

Overview​

Supported Cloud DNS providers​

Prerequisites​

Workflow overview​

FQDN Examples​

Quick Start: Add a new DNS Zone​

CLI Steps​

Wayfinder's Web Interface Steps​

1. Details Section Steps​

2. Scope Section Steps​

3. Provider Section Steps​

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

5. Summary​

6. YAML​

7. Delegation​

DNS Zone Properties​

Details Section Properties​

Scope Section Properties​

Provider Section Properties​

Network Link Properties (Private DNS Zones only)​

View DNS Zones​

Edit & Apply DNS Zones​

YAML Examples​

Public​

Private​

AWS​

Azure​

GCP​

CLI Quick Reference

Overview

Supported Cloud DNS providers

Prerequisites

Workflow overview

FQDN Examples

Quick Start: Add a new DNS Zone

CLI Steps

Wayfinder's Web Interface Steps

1. Details Section Steps

2. Scope Section Steps

3. Provider Section Steps

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

5. Summary

6. YAML

7. Delegation

DNS Zone Properties

Details Section Properties

Scope Section Properties

Provider Section Properties

Network Link Properties (Private DNS Zones only)

View DNS Zones

Edit & Apply DNS Zones

YAML Examples

Public

Private

AWS

Azure

GCP