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:

• AWS Route 53
• Azure DNS
• Google Cloud DNS

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

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

3. Provider Section Steps

1. Select a Cloud DNS Provider

   Wayfinder supports the following main cloud DNS Providers:

   • AWS Route 53
   • Azure DNS
   • Google Cloud DNS

   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:

Private DNS Zone:

Azure DNS 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:

Fill in the details:

- AWS:

- Azure:

- GCP:

Network Link Overview:

5. Summary

1. Verify that all the details are correct.

Screenshots

Public:

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:

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.

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:

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.

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

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

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