WIP: docs/user/aws/install_upi: Document bring-your-own-DNS

Some users want to provide their own *.apps DNS records instead of delegating that to the ingress operator [1]. With this commit, we tell the ingress operator not to worry about managing any hosted zones, and walk users through how they can create the expected records [2] themselves. [1]: https://bugzilla.redhat.com/show_bug.cgi?id=1715635 [2]: https://github.com/openshift/cluster-ingress-operator/blob/9ce86811e6aeea58d3b2b8955591d50cd9311885/pkg/operator/controller/ingress/dns.go#L75-L115
openshift · Aug 14, 2019 · 2e64f89 · 2e64f89
1 parent 8f972b4
commit 2e64f89
Showing 1 changed file with 91 additions and 7 deletions.
diff --git a/docs/user/aws/install_upi.md b/docs/user/aws/install_upi.md
@@ -4,11 +4,9 @@ The steps for performing a UPI-based install are outlined here. Several [CloudFo
 provided to assist in completing these steps or to help model your own.  You are also free to create the required
 resources through other methods; the CloudFormation templates are just an example.
 
-## Create Ignition Configs
+## Create Configuration
 
-The machines will be started manually.
-Therefore, it is required to generate the bootstrap and machine Ignition configs and store them for later steps.
-Use [a staged install](../overview.md#multiple-invocations) to remove the control-plane Machines and compute MachineSets, because we'll be providing those ourselves and don't want to involve [the machine-API operator][machine-api-operator].
+Create an install configuration as for [the usual approach](install.md#create-configuration):
 
 ```console
 $ openshift-install create install-config
@@ -20,26 +18,48 @@ $ openshift-install create install-config
 ? Pull Secret [? for help]
 ```
 
-Edit the resulting `openshift-install.yaml` to set `replicas` to 0 for the `compute` pool:
+### Empty Compute Pools
+
+We'll be providing the control-plane and compute machines ourselves, so edit the resulting `openshift-install.yaml` to set `replicas` to 0 for the `compute` pool:
 
 ```console
 $ sed -i '1,/replicas: / s/replicas: .*/replicas: 0/' install-config.yaml
 ```
 
-Create manifests to get access to the control-plane Machines and compute MachineSets:
+## Edit Manifests
+
+Use [a staged install](../overview.md#multiple-invocations) to make some adjustments which are not exposed via the install configuration.
 
 ```console
 $ openshift-install create manifests
 INFO Consuming "Install Config" from target directory
 ```
 
-From the manifest assets, remove the control-plane Machines and the compute MachineSets:
+### Remove Machines and MachineSets
+
+Remove the control-plane Machines and compute MachineSets, because we'll be providing those ourselves and don't want to involve [the machine-API operator][machine-api-operator]:
 
 ```console
 $ rm -f openshift/99_openshift-cluster-api_master-machines-*.yaml openshift/99_openshift-cluster-api_worker-machinesets-*.yaml
 ```
 
 You are free to leave the compute MachineSets in if you want to create compute machines via the machine API, but if you do you may need to update the various references (`subnet`, etc.) to match your environment.
+
+### Remove DNS Zones
+
+If you don't want the ingress operator to create DNS records on your behalf, remove the `privateZone` and `publicZone` sections from the DNS configuration:
+
+```console
+$ FIXME testing/manifests/cluster-dns-02-config.yml
+```
+
+If you do so, you'll need to [add](#add-the-ingress-dns-records) the following records to your private and public zones:
+
+* `*.apps.{baseDomain}.`, which should point at the ingress load balancer.
+    You can use C, CNAME, ALIAS, etc. records, as you see fit.
+
+## Create Ignition Configs
+
 Now we can create the bootstrap Ignition configs:
 
 ```console
@@ -241,6 +261,70 @@ openshift-service-catalog-apiserver-operator            openshift-service-catalo
 openshift-service-catalog-controller-manager-operator   openshift-service-catalog-controller-manager-operator-b78cr2lnm     1/1       Running     0          31m
 ```
 
+## Add the Ingress DNS Records
+
+If you removed the DNS Zone configuration [earlier](#remove-dns-zones), retrieve the ingress load balancer status:
+
+```console
+$ oc -n openshift-ingress get service router-default
+...
+FIXME: based on https://storage.googleapis.com/origin-ci-test/pr-logs/pull/openshift_cluster-ingress-operator/289/pull-ci-openshift-cluster-ingress-operator-master-e2e-aws/1318/artifacts/e2e-aws/must-gather/namespaces/openshift-ingress/core/services.yaml
+
+ spec:
+    clusterIP: 172.30.157.126
+ status:
+    loadBalancer:
+      ingress:
+      - hostname: a2d4f63c2bece11e9bd20124ecfdc509-918677574.us-east-1.elb.amazonaws.com
+
+$ oc -n openshift-ingress get service router-internal-default
+....
+  spec:
+    clusterIP: 172.30.61.20
+  status:
+    loadBalancer: {}
+```
+
+And create the required zones now:
+
+```console
+$ aws route53 change-resource-record-sets --hosted-zone-id "${YOUR_PRIVATE_ZONE}" --change-batch '{
+>   "Changes": [
+>     {
+>       "Action": "CREATE",
+>       "ResourceRecordSet": {
+>         "Name": "\\052.apps.your.cluster.domain.example.com",
+>         "Type": "A",
+>         "AliasTarget":{
+>           "HostedZoneId": "Z1H1FL5HABSF5",
+>           "DNSName": "a2d4f63c2bece11e9bd20124ecfdc509-918677574.us-east-1.elb.amazonaws.com.",
+>           "EvaluateTargetHealth": false
+>         }
+>       }
+>     }
+>   ]
+> }'
+$ aws route53 change-resource-record-sets --hosted-zone-id "${YOUR_PUBLIC}" --change-batch '{
+>   "Changes": [
+>     {
+>       "Action": "CREATE",
+>       "ResourceRecordSet": {
+>         "Name": "\\052.apps.your.cluster.domain.example.com",
+>         "Type": "A",
+>         "AliasTarget":{
+>           "HostedZoneId": "Z35SXDOTRQ7X7K",
+>           "DNSName": "a4fe19109bee011e984b9123229d5a72-845930010.us-east-1.elb.amazonaws.com.",
+>           "EvaluateTargetHealth": false
+>         }
+>       }
+>     }
+>   ]
+> }'
+```
+
+FIXME: do they need to monitor for other [`DNSRecord`][DNSRecord] objects and fullful them as they show up?
+
 [cloudformation]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
 [delete-stack]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html
 [machine-api-operator]: https://github.com/openshift/machine-api-operator
+[DNSRecord]: https://github.com/openshift/cluster-ingress-operator/blob/d115a146611871c47f44f239346ecea0015993d9/pkg/api/v1/types.go#L18-L25