Skip to content

Commit cc0297e

Browse files
skopacz1skopacz1
authored
Merge pull request #77817 from michaelryanmcneill/OSDOCS-10982
OSDOCS-10982: updating external DNS tutorial to remove references to CDO
2 parents 53e7d0e + d09e5dd commit cc0297e

File tree

1 file changed

+117
-68
lines changed

1 file changed

+117
-68
lines changed

‎cloud_experts_tutorials/cloud-experts-external-dns.adoc

Lines changed: 117 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,7 @@ toc::[]
1818
// - Dustin Scott
1919
//---
2020

21-
[WARNING]
22-
====
23-
Starting with {product-title} 4.14, the Custom Domain Operator is deprecated. To manage Ingress in {product-title} 4.14, use the Ingress Operator. The functionality is unchanged for {product-title} 4.13 and earlier versions.
24-
====
25-
26-
Configuring the xref:../applications/deployments/rosa-config-custom-domains-applications.adoc[Custom Domain Operator] requires a wildcard CNAME DNS record in your Amazon Route 53 hosted zone. If you do not want to use a wildcard record, you can use the `External DNS` Operator to create individual entries for routes.
27-
28-
Use this tutorial to deploy and configure the `External DNS` Operator with a custom domain in {product-title} (ROSA).
21+
The External DNS Operator deploys and manages `ExternalDNS` to provide the name resolution for services and routes from the external DNS provider, like Amazon Route 53, to {product-title} (ROSA) clusters. In this tutorial, we will deploy and configure the External DNS Operator with a secondary ingress controller to manage DNS records in Amazon Route 53.
2922

3023
[IMPORTANT]
3124
====
@@ -35,100 +28,115 @@ The `External DNS` Operator does not support STS using IAM Roles for Service Acc
3528
[id="cloud-experts-external-dns-prerequisites"]
3629
== Prerequisites
3730

38-
* A ROSA cluster
39-
* A user account with `dedicated-admin` privileges
31+
* A ROSA Classic cluster
32+
+
33+
[NOTE]
34+
====
35+
ROSA with HCP is not supported at this time.
36+
====
37+
+
38+
* A user account with `cluster-admin` privileges
4039
* The OpenShift CLI (`oc`)
4140
* The Amazon Web Services (AWS) CLI (`aws`)
42-
* A unique domain, such as `*.apps.<company_name>.io`
41+
* A unique domain, such as `apps.example.com`
4342
* An Amazon Route 53 public hosted zone for the above domain
4443

4544
[id="cloud-experts-external-dns-environment-setup"]
4645
== Setting up your environment
4746

48-
. Configure the following environment variables, replacing `CLUSTER_NAME` with the name of your cluster:
47+
. Configure the following environment variables:
4948
+
5049
[source,terminal]
5150
----
52-
$ export DOMAIN=apps.<company_name>.io <1>
51+
$ export DOMAIN=<apps.example.com> <1>
5352
$ export AWS_PAGER=""
54-
$ export CLUSTER_NAME=$(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}$//')
53+
$ export CLUSTER=$(oc get infrastructure cluster -o=jsonpath="{.status.infrastructureName}" | sed 's/-[a-z0-9]\{5\}$//')
5554
$ export REGION=$(oc get infrastructure cluster -o=jsonpath="{.status.platformStatus.aws.region}")
5655
$ export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
57-
$ export SCRATCH="/tmp/${CLUSTER_NAME}/external-dns"
56+
$ export SCRATCH="/tmp/${CLUSTER}/external-dns"
5857
$ mkdir -p ${SCRATCH}
5958
----
60-
<1> The custom domain.
59+
<1> Replace with the custom domain you want to use for the `IngressController`.
60+
+
6161
. Ensure all fields output correctly before moving to the next section:
6262
+
6363
[source,terminal]
6464
----
65-
$ echo "Cluster: ${CLUSTER_NAME}, Region: ${REGION}, AWS Account ID: ${AWS_ACCOUNT_ID}"
65+
$ echo "Cluster: ${CLUSTER}, Region: ${REGION}, AWS Account ID: ${AWS_ACCOUNT_ID}"
6666
----
67+
+
68+
[NOTE]
69+
====
70+
The "Cluster" output from the previous command may be the name of your cluster, the internal ID of your cluster, or the cluster's domain prefix. If you prefer to use another identifier, you can manually set this value by running the following command:
71+
72+
[source,terminal]
73+
----
74+
$ export CLUSTER=my-custom-value
75+
----
76+
====
6777

68-
[id="cloud-experts-external-dns-custom-domain-setup"]
69-
== Setting up your custom domain
78+
[id="secondary_ingress_controller_setup_{context}"]
79+
== Secondary ingress controller setup
7080

71-
ROSA manages secondary Ingress Controllers using the `Custom Domain` Operator. Use the following procedure to deploy a secondary Ingress Controller using a custom domain.
81+
Use the following procedure to deploy a secondary ingress controller using a custom domain.
7282

7383
.Prerequisites
7484

75-
* A unique domain, such as `*.apps.<company_name>.io`
76-
* A custom SAN or wildcard certificate, such as `CN=*.apps.<company_name>.io`
85+
* A unique domain, such as `apps.example.com`
86+
* A wildcard or SAN TLS certificate configured with the custom domain selected above (`CN=*.apps.example.com`)
7787

7888
.Procedure
7989

80-
. Create a new project:
81-
+
82-
[source,terminal]
83-
----
84-
$ oc new-project external-dns-operator
85-
----
86-
8790
. Create a new TLS secret from a private key and a public certificate, where `fullchain.pem` is your full wildcard certificate chain (including any intermediaries) and `privkey.pem` is your wildcard certificate's private key:
8891
+
8992
[source,terminal]
9093
----
91-
$ oc -n external-dns-operator create secret tls external-dns-tls --cert=fullchain.pem --key=privkey.pem
94+
$ oc -n openshift-ingress create secret tls external-dns-tls --cert=fullchain.pem --key=privkey.pem
9295
----
9396

94-
. Create a new `CustomDomain` custom resource (CR):
97+
. Create a new `IngressController` resource:
9598
+
96-
.Example `external-dns-custom-domain.yaml`
97-
[source,yaml]
99+
[source,terminal]
98100
----
99-
apiVersion: managed.openshift.io/v1alpha1
100-
kind: CustomDomain
101+
$ cat << EOF | oc apply -f -
102+
apiVersion: operator.openshift.io/v1
103+
kind: IngressController
101104
metadata:
102-
name: external-dns
105+
name: external-dns-ingress
106+
namespace: openshift-ingress-operator
103107
spec:
104-
domain: apps.<company_name>.io <1>
105-
scope: External
106-
loadBalancerType: NLB
107-
certificate:
108+
domain: ${DOMAIN}
109+
defaultCertificate:
108110
name: external-dns-tls
109-
namespace: external-dns-operator
111+
endpointPublishingStrategy:
112+
loadBalancer:
113+
dnsManagementPolicy: Unmanaged
114+
providerParameters:
115+
aws:
116+
type: NLB
117+
type: AWS
118+
scope: External
119+
type: LoadBalancerService
120+
EOF
110121
----
111-
<1> The custom domain.
112-
113-
. Apply the CR:
114122
+
115-
[source,terminal]
116-
----
117-
$ oc apply -f external-dns-custom-domain.yaml
118-
----
119-
120-
. Verify that your custom domain Ingress Controller has been deployed and has a `Ready` status:
123+
[WARNING]
124+
====
125+
This `IngressController` example will create an internet accessible Network Load Balancer (NLB) in your AWS account. To provision an internal NLB instead, set the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter to `Internal` before creating the `IngressController` resource.
126+
====
127+
+
128+
. Verify that your custom domain IngressController has successfully created an external load balancer:
121129
+
122130
[source,terminal]
123131
----
124-
$ oc get customdomains
132+
$ oc -n openshift-ingress get service/router-external-dns-ingress
125133
----
126134
+
127135
.Example output
128136
[source,terminal]
129137
----
130-
NAME ENDPOINT DOMAIN STATUS
131-
external-dns xxrywp.<company_name>.cluster-01.opln.s1.openshiftapps.com *.apps.<company_name>.io Ready
138+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
139+
router-external-dns-ingress LoadBalancer 172.30.71.250 a4838bb991c6748439134ab89f132a43-aeae124077b50c01.elb.us-east-1.amazonaws.com 80:32227/TCP,443:30310/TCP 43s
132140
----
133141

134142
[id="cloud-experts-external-dns-prepare-aws-account"]
@@ -142,6 +150,40 @@ $ export ZONE_ID=$(aws route53 list-hosted-zones-by-name --output json \
142150
--dns-name "${DOMAIN}." --query 'HostedZones[0]'.Id --out text | sed 's/\/hostedzone\///')
143151
----
144152
+
153+
. Prepare a document with the necessary DNS changes to enable DNS resolution for the canonical domain of the Ingress Controller:
154+
+
155+
[source,terminal]
156+
----
157+
$ NLB_HOST=$(oc -n openshift-ingress get service/router-external-dns-ingress -ojsonpath="{.status.loadBalancer.ingress[0].hostname}")
158+
$ cat << EOF > "${SCRATCH}/create-cname.json"
159+
{
160+
"Comment":"Add CNAME to ingress controller canonical domain",
161+
"Changes":[{
162+
"Action":"CREATE",
163+
"ResourceRecordSet":{
164+
"Name": "router-external-dns-ingress.${DOMAIN}",
165+
"Type":"CNAME",
166+
"TTL":30,
167+
"ResourceRecords":[{
168+
"Value": "${NLB_HOST}"
169+
}]
170+
}
171+
}]
172+
}
173+
EOF
174+
----
175+
+
176+
The External DNS Operator uses this canonical domain as the target for CNAME records.
177+
+
178+
. Submit your changes to Amazon Route 53 for propagation:
179+
+
180+
[source,terminal]
181+
----
182+
aws route53 change-resource-record-sets \
183+
--hosted-zone-id ${ZONE_ID} \
184+
--change-batch file://${SCRATCH}/create-cname.json
185+
----
186+
+
145187
. Create an AWS IAM Policy document that allows the `External DNS` Operator to update _only_ the custom domain public hosted zone:
146188
+
147189
[source,terminal]
@@ -174,26 +216,17 @@ $ cat << EOF > "${SCRATCH}/external-dns-policy.json"
174216
EOF
175217
----
176218
+
177-
. Create an AWS IAM policy:
178-
+
179-
[source,terminal]
180-
----
181-
$ export POLICY_ARN=$(aws iam create-policy --policy-name "${CLUSTER_NAME}-AllowExternalDNSUpdates" \
182-
--policy-document file://${SCRATCH}/external-dns-policy.json \
183-
--query 'Policy.Arn' --output text)
184-
----
185-
+
186219
. Create an AWS IAM user:
187220
+
188221
[source,terminal]
189222
----
190-
$ aws iam create-user --user-name "${CLUSTER_NAME}-external-dns-operator"
223+
$ aws iam create-user --user-name "${CLUSTER}-external-dns-operator"
191224
----
192225
. Attach the policy:
193226
+
194227
[source,terminal]
195228
----
196-
$ aws iam attach-user-policy --user-name "${CLUSTER_NAME}-external-dns-operator" --policy-arn $POLICY_ARN
229+
$ aws iam attach-user-policy --user-name "${CLUSTER}-external-dns-operator" --policy-arn $POLICY_ARN
197230
----
198231
+
199232
[NOTE]
@@ -204,7 +237,7 @@ This will be changed to STS using IRSA in the future.
204237
+
205238
[source,terminal]
206239
----
207-
$ SECRET_ACCESS_KEY=$(aws iam create-access-key --user-name "${CLUSTER_NAME}-external-dns-operator")
240+
$ SECRET_ACCESS_KEY=$(aws iam create-access-key --user-name "${CLUSTER}-external-dns-operator")
208241
----
209242
. Create static credentials:
210243
+
@@ -220,6 +253,13 @@ EOF
220253
[id="cloud-experts-external-dns-install-external-dns-operator"]
221254
== Installing the External DNS Operator
222255

256+
. Create a new project:
257+
+
258+
[source,terminal]
259+
----
260+
$ oc new-project external-dns-operator
261+
----
262+
223263
. Install the `External DNS` Operator from OperatorHub:
224264
+
225265
[source,terminal]
@@ -262,6 +302,7 @@ $ oc rollout status deploy external-dns-operator --timeout=300s
262302
$ oc -n external-dns-operator create secret generic external-dns \
263303
--from-file "${SCRATCH}/credentials"
264304
----
305+
+
265306
. Deploy the `ExternalDNS` controller:
266307
+
267308
[source,terminal]
@@ -283,7 +324,7 @@ spec:
283324
type: AWS
284325
source:
285326
openshiftRouteOptions:
286-
routerName: external-dns
327+
routerName: external-dns-ingress
287328
type: OpenShiftRoute
288329
zones:
289330
- ${ZONE_ID}
@@ -341,9 +382,17 @@ $ aws route53 list-resource-record-sets --hosted-zone-id ${ZONE_ID} \
341382
$ aws route53 list-resource-record-sets --hosted-zone-id ${ZONE_ID} \
342383
--query "ResourceRecordSets[?Type == 'TXT']" | grep ${DOMAIN}
343384
----
344-
. Navigate to your custom console domain in the browser where you see the OpenShift login:
385+
+
386+
. Curl the newly created DNS record to your sample application to verify the hello world application is accessible:
345387
+
346388
[source,terminal]
347389
----
348-
$ echo console.${DOMAIN}
390+
$ curl https://hello-openshift.${DOMAIN}
349391
----
392+
+
393+
.Example output
394+
[source,terminal]
395+
----
396+
Hello OpenShift!
397+
----
398+

0 commit comments

Comments
 (0)