openshift-docs/cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc

:_mod-docs-content-type: ASSEMBLY
[id="cloud-experts-custom-dns-resolver"]
= Tutorial: Deploying {product-title} with a Custom DNS Resolver
include::_attributes/attributes-openshift-dedicated.adoc[]
:context: cloud-experts-custom-dns-resolver

toc::[]

A link:https://docs.aws.amazon.com/vpc/latest/userguide/DHCPOptionSet.html[custom DHCP option set] enables you to customize your VPC with your own DNS server, domain name, and more. {product-title} clusters support using custom DHCP option sets. By default, {product-title} clusters require setting the "domain name servers" option to `AmazonProvidedDNS` to ensure successful cluster creation and operation. Customers who want to use custom DNS servers for DNS resolution must do additional configuration to ensure successful {product-title} cluster creation and operation. 

In this tutorial, we will configure our DNS server to forward DNS lookups for specific DNS zones (further detailed below) to an link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver.html[Amazon Route 53 Inbound Resolver]. 

[NOTE]
====
This tutorial uses the open-source BIND DNS server (`named`) to demonstrate the configuration necessary to forward DNS lookups to an Amazon Route 53 Inbound Resolver located in the VPC you plan to deploy a {product-title} cluster into. Refer to the documentation of your preferred DNS server for how to configure zone forwarding.
====

[id="cloud-experts-custom-dns-resolver-prerequisites"]
== Prerequisites

* ROSA CLI (`rosa`)
* AWS CLI (`aws`)
ifdef::openshift-rosa[]
* A manually created AWS VPC
endif::openshift-rosa[]
ifdef::openshift-rosa-hcp[]
* A xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-hcp-creating-vpc_rosa-hcp-sts-creating-a-cluster-quickly[manually created AWS VPC]
endif::openshift-rosa-hcp[]
* A DHCP option set configured to point to a custom DNS server and set as the default for your VPC

[id="cloud-experts-custom-dns-resolver-environment-setup"]
== Setting up your environment

. Configure the following environment variables:
+
[source,terminal]
----
$ export VPC_ID=<vpc_ID> <1>
$ export REGION=<region> <2>
$ export VPC_CIDR=<vpc_CIDR> <3>
----
<1> Replace `<vpc_ID>` with the ID of the VPC you want to install your cluster into.
<2> Replace `<region>` with the AWS region you want to install your cluster into.
<3> Replace `<vpc_CIDR>` with the CIDR range of your VPC.
+
. Ensure all fields output correctly before moving to the next section:
+
[source,terminal]
----
$ echo "VPC ID: ${VPC_ID}, VPC CIDR Range: ${VPC_CIDR}, Region: ${REGION}"
----

[id="cloud-experts-custom-dns-resolver-create-inbound-resolver"]
== Create an Amazon Route 53 Inbound Resolver

Use the following procedure to deploy an link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver.html[Amazon Route 53 Inbound Resolver] in the VPC we plan to deploy the cluster into. 

[WARNING]
====
In this example, we deploy the Amazon Route 53 Inbound Resolver into the same VPC the cluster will use. If you want to deploy it into a separate VPC, you must manually associate the private hosted zone(s) detailed below *once cluster creation is started*. You cannot associate the zone before the cluster creation process begins. Failure to associate the private hosted zone during the cluster creation process will result in cluster creation failures.
====

. Create a security group and allow access to ports `53/tcp` and `53/udp` from the VPC: 
+
[source,terminal]
----
$ SG_ID=$(aws ec2 create-security-group --group-name rosa-inbound-resolver --description "Security group for ROSA inbound resolver" --vpc-id ${VPC_ID} --region ${REGION} --output text)
$ aws ec2 authorize-security-group-ingress --group-id ${SG_ID} --protocol tcp --port 53 --cidr ${VPC_CIDR} --region ${REGION}
$ aws ec2 authorize-security-group-ingress --group-id ${SG_ID} --protocol udp --port 53 --cidr ${VPC_CIDR} --region ${REGION}
----
+
. Create an Amazon Route 53 Inbound Resolver in your VPC:
+
[source,terminal]
----
$ RESOLVER_ID=$(aws route53resolver create-resolver-endpoint \
  --name rosa-inbound-resolver \
  --creator-request-id rosa-$(date '+%Y-%m-%d') \
  --security-group-ids ${SG_ID} \
  --direction INBOUND \
  --ip-addresses $(aws ec2 describe-subnets --filter Name=vpc-id,Values=${VPC_ID} --region ${REGION} | jq -jr '.Subnets | map("SubnetId=\(.SubnetId) ") | .[]') \
  --region ${REGION} \
  --output text \
  --query 'ResolverEndpoint.Id')
----
+
[NOTE]
====
The above command attaches Amazon Route 53 Inbound Resolver endpoints to _all subnets_ in the provided VPC using dynamically allocated IP addresses. If you prefer to manually specify the subnets and/or IP addresses, run the following command instead:

[source,terminal]
----
$ RESOLVER_ID=$(aws route53resolver create-resolver-endpoint \
  --name rosa-inbound-resolver \
  --creator-request-id rosa-$(date '+%Y-%m-%d') \
  --security-group-ids ${SG_ID} \
  --direction INBOUND \
  --ip-addresses SubnetId=<subnet_ID>,Ip=<endpoint_IP> SubnetId=<subnet_ID>,Ip=<endpoint_IP> \// <1>
  --region ${REGION} \
  --output text \
  --query 'ResolverEndpoint.Id')
----
<1> Replace `<subnet_ID>` with the subnet IDs and `<endpoint_IP>` with the static IP addresses you want inbound resolver endpoints added to.
====
+
. Get the IP addresses of your inbound resolver endpoints to configure in your DNS server configuration:
+
[source,terminal]
----
$ aws route53resolver list-resolver-endpoint-ip-addresses \
  --resolver-endpoint-id ${RESOLVER_ID} \
  --region=${REGION} \
  --query 'IpAddresses[*].Ip'
----
+
.Example output
+
[source,text]
----
[
    "10.0.45.253",
    "10.0.23.131",
    "10.0.148.159"
]
----

[id="cloud-experts-custom-dns-resolver-configure-dns-server"]
== Configure your DNS server

Use the following procedure to configure your DNS server to forward the necessary private hosted zones to your Amazon Route 53 Inbound Resolver. 

ifdef::openshift-rosa-hcp[]
=== {product-title}
{product-title} clusters require you to configure DNS forwarding for two private hosted zones:

* `<cluster-name>.hypershift.local`
* `rosa.<domain-prefix>.<unique-ID>.p3.openshiftapps.com`

These Amazon Route 53 private hosted zones are created during cluster creation. The `cluster-name` and `domain-prefix` are customer-specified values, but the `unique-ID` is randomly generated during cluster creation and cannot be preselected. As such, you must wait for the cluster creation process to begin before configuring forwarding for the `p3.openshiftapps.com` private hosted zone. 

. Before the cluster is created, configure your DNS server to forward all DNS requests for `<cluster-name>.hypershift.local` to your Amazon Route 53 Inbound Resolver endpoints. For BIND DNS servers, edit your `/etc/named.conf` file in your favorite text editor and add a new zone using the below example: 
+
.Example
[source,terminal]
----
zone "<cluster-name>.hypershift.local" { <1>
  type forward;
  forward only;
  forwarders { <2>
    10.0.45.253;
    10.0.23.131;
    10.0.148.159;
  };
};
----
<1> Replace `<cluster-name>` with your {product-title} cluster name.
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.
+
. xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-hcp-sts-creating-a-cluster-quickly[Create your cluster].
+
. Once your cluster has begun the creation process, locate the newly created private hosted zone:
+
[source,terminal]
----
$ aws route53 list-hosted-zones-by-vpc \
  --vpc-id ${VPC_ID} \
  --vpc-region ${REGION} \
  --query 'HostedZoneSummaries[*].Name' \
  --output table
----
+
.Example output
+
[source,text]
----
--------------------------------------------------
|             ListHostedZonesByVPC               |
+------------------------------------------------+
|  rosa.domain-prefix.lkmb.p3.openshiftapps.com. |
|  cluster-name.hypershift.local.                |
+------------------------------------------------+
----
+
[NOTE]
====
It may take a few minutes for the cluster creation process to create the private hosted zones in Route 53. If you do not see an `p3.openshiftapps.com` domain, wait a few minutes and run the command again.
====
+
. Once you know the unique ID of the cluster domain, configure your DNS server to forward all DNS requests for `rosa.<domain-prefix>.<unique-ID>.p3.openshiftapps.com` to your Amazon Route 53 Inbound Resolver endpoints. For BIND DNS servers, edit your `/etc/named.conf` file in your favorite text editor and add a new zone using the below example: 
+
.Example
[source,terminal]
----
zone "rosa.<domain-prefix>.<unique-ID>.p3.openshiftapps.com" { <1>
  type forward;
  forward only;
  forwarders { <2>
    10.0.45.253;
    10.0.23.131;
    10.0.148.159;
  };
};
----
<1> Replace `<domain-prefix>` with your cluster domain prefix and `<unique-ID>` with your unique ID collected above.
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.
endif::openshift-rosa-hcp[]

ifdef::openshift-rosa[]
=== {product-title}
{product-title} clusters require you to configure DNS forwarding for one private hosted zones:

* `<domain-prefix>.<unique-ID>.p1.openshiftapps.com`

This Amazon Route 53 private hosted zones is created during cluster creation. The `domain-prefix` is a customer-specified value, but the `unique-ID` is randomly generated during cluster creation and cannot be preselected. As such, you must wait for the cluster creation process to begin before configuring forwarding for the `p1.openshiftapps.com` private hosted zone. 

ifndef::openshift-rosa-hcp[]
. xref:../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-quickly.adoc#rosa-sts-creating-account-wide-sts-roles-and-policies_rosa-sts-creating-a-cluster-quickly[Create your cluster].
endif::openshift-rosa-hcp[]
+
. Once your cluster has begun the creation process, locate the newly created private hosted zone:
+
[source,terminal]
----
$ aws route53 list-hosted-zones-by-vpc \
  --vpc-id ${VPC_ID} \
  --vpc-region ${REGION} \
  --query 'HostedZoneSummaries[*].Name' \
  --output table
----
+
.Example output
+
[source,text]
----
----------------------------------------------
|           ListHostedZonesByVPC             |
+--------------------------------------------+
|  domain-prefix.agls.p3.openshiftapps.com.  |
+--------------------------------------------+
----
+
[NOTE]
====
It may take a few minutes for the cluster creation process to create the private hosted zones in Route 53. If you do not see an `p1.openshiftapps.com` domain, wait a few minutes and run the command again.
====
+
. Once you know the unique ID of the cluster domain, configure your DNS server to forward all DNS requests for `<domain-prefix>.<unique-ID>.p1.openshiftapps.com` to your Amazon Route 53 Inbound Resolver endpoints. For BIND DNS servers, edit your `/etc/named.conf` file in your favorite text editor and add a new zone using the below example: 
+
.Example
[source,terminal]
----
zone "<domain-prefix>.<unique-ID>.p1.openshiftapps.com" { <1>
  type forward;
  forward only;
  forwarders { <2>
    10.0.45.253;
    10.0.23.131;
    10.0.148.159;
  };
};
----
<1> Replace `<domain-prefix>` with your cluster domain prefix and `<unique-ID>` with your unique ID collected above.
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.
endif::openshift-rosa[]