From 59a0777ff193e504597412a8af6df6c24ea5b44d Mon Sep 17 00:00:00 2001 From: michaelryanmcneill Date: Fri, 6 Sep 2024 11:48:25 -0400 Subject: [PATCH] OSDOCS-11886: Adding tutorial for custom dhcp option sets --- _topic_maps/_topic_map_rosa.yml | 2 + .../cloud-experts-custom-dns-resolver.adoc | 255 ++++++++++++++++++ 2 files changed, 257 insertions(+) create mode 100644 cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index 7bec3ce166..edccc2dabc 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_topic_maps/_topic_map_rosa.yml @@ -117,6 +117,8 @@ Topics: File: cloud-experts-rosa-with-hcp-private-offer-acceptance-and-sharing - Name: Verifying Permissions for a ROSA STS Deployment File: rosa-mobb-verify-permissions-sts-deployment +- Name: Deploying ROSA with a Custom DNS Resolver + File: cloud-experts-custom-dns-resolver - Name: Using AWS WAF and Amazon CloudFront to protect ROSA workloads File: cloud-experts-using-cloudfront-and-waf - Name: Using AWS WAF and AWS ALBs to protect ROSA workloads diff --git a/cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc b/cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc new file mode 100644 index 0000000000..ce4df8e6cf --- /dev/null +++ b/cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc @@ -0,0 +1,255 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-experts-custom-dns-resolver"] += Tutorial: Deploying ROSA 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} (ROSA) clusters support using custom DHCP option sets. By default, ROSA 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 ROSA 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 ROSA 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`) +* A xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-hcp-vpc-manual_rosa-hcp-sts-creating-a-cluster-quickly[manually created AWS VPC] +* 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= <1> +$ export REGION= <2> +$ export VPC_CIDR= <3> +---- +<1> Replace `` with the ID of the VPC you want to install your cluster into. +<2> Replace `` with the AWS region you want to install your cluster into. +<3> Replace `` 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=,Ip= SubnetId=,Ip= \// <1> + --region ${REGION} \ + --output text \ + --query 'ResolverEndpoint.Id') +---- +<1> Replace `` with the subnet IDs and `` 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. + +=== ROSA with HCP + +ROSA with HCP clusters require you to configure DNS forwarding for two private hosted zones: + +* `.hypershift.local` +* `rosa...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 `.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 ".hypershift.local" { <1> + type forward; + forward only; + forwarders { <2> + 10.0.45.253; + 10.0.23.131; + 10.0.148.159; + }; +}; +---- +<1> Replace `` with your ROSA HCP 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-sts-creating-account-wide-sts-roles-and-policies_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...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...p3.openshiftapps.com" { <1> + type forward; + forward only; + forwarders { <2> + 10.0.45.253; + 10.0.23.131; + 10.0.148.159; + }; +}; +---- +<1> Replace `` with your cluster domain prefix and `` 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 `;`. + +=== ROSA Classic + +ROSA Classic clusters require you to configure DNS forwarding for one private hosted zones: + +* `..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. + +. 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]. ++ +. 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 `..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 "..p1.openshiftapps.com" { <1> + type forward; + forward only; + forwarders { <2> + 10.0.45.253; + 10.0.23.131; + 10.0.148.159; + }; +}; +---- +<1> Replace `` with your cluster domain prefix and `` 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 `;`. \ No newline at end of file