Skip to content

Commit 3afde62

Browse files
michaelryanmcneillmichaelryanmcneill
committed
OSDOCS-11886: Adding tutorial for custom dhcp option sets
1 parent ceef524 commit 3afde62

File tree

2 files changed

+257
-0
lines changed

2 files changed

+257
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,8 @@ Topics:
117117
File: cloud-experts-rosa-with-hcp-private-offer-acceptance-and-sharing
118118
- Name: Verifying Permissions for a ROSA STS Deployment
119119
File: rosa-mobb-verify-permissions-sts-deployment
120+
- Name: Deploying ROSA with a Custom DNS Resolver
121+
File: cloud-experts-custom-dns-resolver
120122
- Name: Using AWS WAF and Amazon CloudFront to protect ROSA workloads
121123
File: cloud-experts-using-cloudfront-and-waf
122124
- Name: Using AWS WAF and AWS ALBs to protect ROSA workloads

‎cloud_experts_tutorials/cloud-experts-custom-dns-resolver.adoc

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cloud-experts-custom-dns-resolver"]
3+
= Tutorial: Deploying ROSA with a Custom DNS Resolver
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: cloud-experts-custom-dns-resolver
6+
7+
toc::[]
8+
9+
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.
10+
11+
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].
12+
13+
[NOTE]
14+
====
15+
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.
16+
====
17+
18+
[id="cloud-experts-custom-dns-resolver-prerequisites"]
19+
== Prerequisites
20+
21+
* ROSA CLI (`rosa`)
22+
* AWS CLI (`aws`)
23+
* 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]
24+
* A DHCP option set configured to point to a custom DNS server and set as the default for your VPC
25+
26+
[id="cloud-experts-custom-dns-resolver-environment-setup"]
27+
== Setting up your environment
28+
29+
. Configure the following environment variables:
30+
+
31+
[source,terminal]
32+
----
33+
$ export VPC_ID=<vpc_ID> <1>
34+
$ export REGION=<region> <2>
35+
$ export VPC_CIDR=<vpc_CIDR> <3>
36+
----
37+
<1> Replace `<vpc_ID>` with the ID of the VPC you want to install your cluster into.
38+
<2> Replace `<region>` with the AWS region you want to install your cluster into.
39+
<3> Replace `<vpc_CIDR>` with the CIDR range of your VPC.
40+
+
41+
. Ensure all fields output correctly before moving to the next section:
42+
+
43+
[source,terminal]
44+
----
45+
$ echo "VPC ID: ${VPC_ID}, VPC CIDR Range: ${VPC_CIDR}, Region: ${REGION}"
46+
----
47+
48+
[id="cloud-experts-custom-dns-resolver-create-inbound-resolver"]
49+
== Create an Amazon Route 53 Inbound Resolver
50+
51+
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.
52+
53+
[WARNING]
54+
====
55+
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.
56+
====
57+
58+
. Create a security group and allow access to ports `53/tcp` and `53/udp` from the VPC:
59+
+
60+
[source,terminal]
61+
----
62+
$ 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)
63+
$ aws ec2 authorize-security-group-ingress --group-id ${SG_ID} --protocol tcp --port 53 --cidr ${VPC_CIDR} --region ${REGION}
64+
$ aws ec2 authorize-security-group-ingress --group-id ${SG_ID} --protocol udp --port 53 --cidr ${VPC_CIDR} --region ${REGION}
65+
----
66+
+
67+
. Create an Amazon Route 53 Inbound Resolver in your VPC:
68+
+
69+
[source,terminal]
70+
----
71+
$ RESOLVER_ID=$(aws route53resolver create-resolver-endpoint \
72+
--name rosa-inbound-resolver \
73+
--creator-request-id rosa-$(date '+%Y-%m-%d') \
74+
--security-group-ids ${SG_ID} \
75+
--direction INBOUND \
76+
--ip-addresses $(aws ec2 describe-subnets --filter Name=vpc-id,Values=${VPC_ID} --region ${REGION} | jq -jr '.Subnets | map("SubnetId=\(.SubnetId) ") | .[]') \
77+
--region ${REGION} \
78+
--output text \
79+
--query 'ResolverEndpoint.Id')
80+
----
81+
+
82+
[NOTE]
83+
====
84+
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:
85+
86+
[source,terminal]
87+
----
88+
$ RESOLVER_ID=$(aws route53resolver create-resolver-endpoint \
89+
--name rosa-inbound-resolver \
90+
--creator-request-id rosa-$(date '+%Y-%m-%d') \
91+
--security-group-ids ${SG_ID} \
92+
--direction INBOUND \
93+
--ip-addresses SubnetId=<subnet_ID>,Ip=<endpoint_IP> SubnetId=<subnet_ID>,Ip=<endpoint_IP> \// <1>
94+
--region ${REGION} \
95+
--output text \
96+
--query 'ResolverEndpoint.Id')
97+
----
98+
<1> Replace `<subnet_ID>` with the subnet IDs and `<endpoint_IP>` with the static IP addresses you want inbound resolver endpoints added to.
99+
====
100+
+
101+
. Get the IP addresses of your inbound resolver endpoints to configure in your DNS server configuration:
102+
+
103+
[source,terminal]
104+
----
105+
$ aws route53resolver list-resolver-endpoint-ip-addresses \
106+
--resolver-endpoint-id ${RESOLVER_ID} \
107+
--region=${REGION} \
108+
--query 'IpAddresses[*].Ip'
109+
----
110+
+
111+
.Example output
112+
+
113+
[source,text]
114+
----
115+
[
116+
"10.0.45.253",
117+
"10.0.23.131",
118+
"10.0.148.159"
119+
]
120+
----
121+
122+
[id="cloud-experts-custom-dns-resolver-configure-dns-server"]
123+
== Configure your DNS server
124+
125+
Use the following procedure to configure your DNS server to forward the necessary private hosted zones to your Amazon Route 53 Inbound Resolver.
126+
127+
=== ROSA with HCP
128+
129+
ROSA with HCP clusters require you to configure DNS forwarding for two private hosted zones:
130+
131+
* `<cluster-name>.hypershift.local`
132+
* `rosa.<domain-prefix>.<unique-ID>.p3.openshiftapps.com`
133+
134+
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.
135+
136+
. 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:
137+
+
138+
.Example
139+
[source,terminal]
140+
----
141+
zone "<cluster-name>.hypershift.local" { <1>
142+
type forward;
143+
forward only;
144+
forwarders { <2>
145+
10.0.45.253;
146+
10.0.23.131;
147+
10.0.148.159;
148+
};
149+
};
150+
----
151+
<1> Replace `<cluster-name>` with your ROSA HCP cluster name.
152+
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.
153+
+
154+
. 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].
155+
+
156+
. Once your cluster has begun the creation process, locate the newly created private hosted zone:
157+
+
158+
[source,terminal]
159+
----
160+
$ aws route53 list-hosted-zones-by-vpc \
161+
--vpc-id ${VPC_ID} \
162+
--vpc-region ${REGION} \
163+
--query 'HostedZoneSummaries[*].Name' \
164+
--output table
165+
----
166+
+
167+
.Example output
168+
+
169+
[source,text]
170+
----
171+
--------------------------------------------------
172+
| ListHostedZonesByVPC |
173+
+------------------------------------------------+
174+
| rosa.domain-prefix.lkmb.p3.openshiftapps.com. |
175+
| cluster-name.hypershift.local. |
176+
+------------------------------------------------+
177+
----
178+
+
179+
[NOTE]
180+
====
181+
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.
182+
====
183+
+
184+
. 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:
185+
+
186+
.Example
187+
[source,terminal]
188+
----
189+
zone "rosa.<domain-prefix>.<unique-ID>.p3.openshiftapps.com" { <1>
190+
type forward;
191+
forward only;
192+
forwarders { <2>
193+
10.0.45.253;
194+
10.0.23.131;
195+
10.0.148.159;
196+
};
197+
};
198+
----
199+
<1> Replace `<domain-prefix>` with your cluster domain prefix and `<unique-ID>` with your unique ID collected above.
200+
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.
201+
202+
=== ROSA Classic
203+
204+
ROSA Classic clusters require you to configure DNS forwarding for one private hosted zones:
205+
206+
* `<domain-prefix>.<unique-ID>.p1.openshiftapps.com`
207+
208+
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.
209+
210+
. 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].
211+
+
212+
. Once your cluster has begun the creation process, locate the newly created private hosted zone:
213+
+
214+
[source,terminal]
215+
----
216+
$ aws route53 list-hosted-zones-by-vpc \
217+
--vpc-id ${VPC_ID} \
218+
--vpc-region ${REGION} \
219+
--query 'HostedZoneSummaries[*].Name' \
220+
--output table
221+
----
222+
+
223+
.Example output
224+
+
225+
[source,text]
226+
----
227+
----------------------------------------------
228+
| ListHostedZonesByVPC |
229+
+--------------------------------------------+
230+
| domain-prefix.agls.p3.openshiftapps.com. |
231+
+--------------------------------------------+
232+
----
233+
+
234+
[NOTE]
235+
====
236+
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.
237+
====
238+
+
239+
. 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:
240+
+
241+
.Example
242+
[source,terminal]
243+
----
244+
zone "<domain-prefix>.<unique-ID>.p1.openshiftapps.com" { <1>
245+
type forward;
246+
forward only;
247+
forwarders { <2>
248+
10.0.45.253;
249+
10.0.23.131;
250+
10.0.148.159;
251+
};
252+
};
253+
----
254+
<1> Replace `<domain-prefix>` with your cluster domain prefix and `<unique-ID>` with your unique ID collected above.
255+
<2> Replace with the IP addresses of your inbound resolver endpoints collected above, ensuring that following each IP address there is a `;`.

0 commit comments

Comments
 (0)