diff --git a/cloud_experts_tutorials/cloud-experts-external-dns.adoc b/cloud_experts_tutorials/cloud-experts-external-dns.adoc index f9a095fcd9..6a47da4263 100644 --- a/cloud_experts_tutorials/cloud-experts-external-dns.adoc +++ b/cloud_experts_tutorials/cloud-experts-external-dns.adoc @@ -20,25 +20,27 @@ toc::[] Configuring the xref:../applications/deployments/osd-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. -This tutorial guides you through deploying and configuring the External DNS Operator with a custom domain in {product-title} (ROSA). +Use this tutorial to deploy and configure the `External DNS` Operator with a custom domain in {product-title} (ROSA). [IMPORTANT] ==== -The External DNS Operator does not support IRSA/STS and uses long-lived IAM credentials. This tutorial will be updated once STS is supported. +The `External DNS` Operator does not support STS using IAM Roles for Service Accounts (IRSA) and uses long-lived Identity Access Management (IAM) credentials instead. This tutorial will be updated when the Operator supports STS. ==== [id="cloud-experts-external-dns-prerequisites"] == Prerequisites * A ROSA cluster -* You have access to the OpenShift CLI (`oc`) -* You have access to the AWS CLI (`aws`) -* A unique domain, such as *.apps..io +* A user account with `dedicated-admin` privileges +* The OpenShift CLI (`oc`) +* The Amazon Web Services (AWS) CLI (`aws`) +* A unique domain, such as `*.apps..io` * An Amazon Route 53 public hosted zone for the above domain -=== Environment setup +[id="cloud-experts-external-dns-environment-setup"] +== Setting up your environment -* Prepare the environment variables: +. Configure the following environment variables, replacing `CLUSTER_NAME` with the name of your cluster: + [source,terminal] ---- @@ -49,14 +51,19 @@ $ export REGION=$(oc get infrastructure cluster -o=jsonpath="{.status.platformSt $ export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) $ export SCRATCH="/tmp/${CLUSTER_NAME}/external-dns" $ mkdir -p ${SCRATCH} -$ echo "Cluster: ${CLUSTER_NAME}, Region: ${REGION}, AWS Account ID: ${AWS_ACCOUNT_ID}" ---- <1> The custom domain. +. Ensure all fields output correctly before moving to the next section: ++ +[source,terminal] +---- +$ echo "Cluster: ${CLUSTER_NAME}, Region: ${REGION}, AWS Account ID: ${AWS_ACCOUNT_ID}" +---- [id="cloud-experts-external-dns-custom-domain-setup"] -== Custom domain setup +== Setting up your custom domain -ROSA manages secondary Ingress Controllers using the Custom Domain Operator. The following procedure outlines how to deploy a secondary Ingress Controller using a custom domain. +ROSA manages secondary Ingress Controllers using the `Custom Domain` Operator. Use the following procedure to deploy a secondary Ingress Controller using a custom domain. .Prerequisites @@ -65,16 +72,15 @@ ROSA manages secondary Ingress Controllers using the Custom Domain Operator. The .Procedure -. Create a new project +. Create a new project: + [source,terminal] ---- $ oc new-project external-dns-operator ---- -. 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. +. 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: + -.Example [source,terminal] ---- $ oc -n external-dns-operator create secret tls external-dns-tls --cert=fullchain.pem --key=privkey.pem @@ -101,13 +107,12 @@ spec: . Apply the CR: + -.Example [source,terminal] ---- $ oc apply -f external-dns-custom-domain.yaml ---- -. Verify that your custom domain Ingress Controller has been deployed and is `Ready`: +. Verify that your custom domain Ingress Controller has been deployed and has a `Ready` status: + [source,terminal] ---- @@ -122,7 +127,7 @@ external-dns xxrywp..cluster-01.opln.s1.openshiftapps.com * ---- [id="cloud-experts-external-dns-prepare-aws-account"] -== Prepare AWS account +== Preparing your AWS account . Retrieve the Amazon Route 53 public hosted zone ID: + @@ -132,7 +137,7 @@ $ export ZONE_ID=$(aws route53 list-hosted-zones-by-name --output json \ --dns-name "${DOMAIN}." --query 'HostedZones[0]'.Id --out text | sed 's/\/hostedzone\///') ---- + -. Create an AWS IAM Policy document that allows the External DNS Operator to update _only_ the custom domain public hosted zone: +. Create an AWS IAM Policy document that allows the `External DNS` Operator to update _only_ the custom domain public hosted zone: + [source,terminal] ---- @@ -208,9 +213,9 @@ EOF ---- [id="cloud-experts-external-dns-install-external-dns-operator"] -== Install the External DNS Operator +== Installing the External DNS Operator -. Install the External DNS Operator from OperatorHub: +. Install the `External DNS` Operator from OperatorHub: + [source,terminal] ---- @@ -238,7 +243,7 @@ spec: EOF ---- + -. Wait until the External DNS Operator is running: +. Wait until the `External DNS` Operator is running: + [source,terminal] ---- @@ -252,7 +257,7 @@ $ oc rollout status deploy external-dns-operator --timeout=300s $ oc -n external-dns-operator create secret generic external-dns \ --from-file "${SCRATCH}/credentials" ---- -. Deploy the ExternalDNS controller: +. Deploy the `ExternalDNS` controller: + [source,terminal] ---- @@ -287,9 +292,11 @@ $ oc rollout status deploy external-dns-${DOMAIN} --timeout=300s ---- [id="cloud-experts-external-dns-deploy-a-sample-application"] -== Deploy a sample application +== Deploying a sample application -. Create a new project for our sample application: +Now that the `ExternalDNS` controller is running, you can deploy a sample application to confirm that the custom domain is configured and trusted when you expose a new route. + +. Create a new project for your sample application: + [source,terminal] ---- @@ -305,8 +312,6 @@ $ oc new-app -n hello-world --image=docker.io/openshift/hello-openshift + . Create a route for the application specifying your custom domain name: + -.Example -+ [source,terminal] ---- $ oc -n hello-world create route edge --service=hello-openshift hello-openshift-tls \ @@ -324,14 +329,14 @@ It can take a few minutes for the record to appear in Amazon Route 53. $ aws route53 list-resource-record-sets --hosted-zone-id ${ZONE_ID} \ --query "ResourceRecordSets[?Type == 'CNAME']" | grep hello-openshift ---- -. You can also view the TXT records that indicate they were created by ExternalDNS: +. Optional: You can also view the TXT records that indicate they were created by ExternalDNS: + [source,terminal] ---- $ aws route53 list-resource-record-sets --hosted-zone-id ${ZONE_ID} \ --query "ResourceRecordSets[?Type == 'TXT']" | grep ${DOMAIN} ---- -. Navigate to your custom console domain in the browser where you see the OpenShift login. +. Navigate to your custom console domain in the browser where you see the OpenShift login: + [source,terminal] ----