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.
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.
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 TypeAccess 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
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 applicationsWayfinder 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 stageA 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 privateCreate 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 inall workspaces
in thenon-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 thews1
workspace in thenon-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
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 ClusterWayfinder 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 privateCreate 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'
- 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.
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 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: 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.
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.
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.
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