update TNG docs on manual external access migration (quay#107)

Author: alecmerdler

modules/proc_deploy-quay-openshift-operator-tng.adoc

@@ -133,7 +133,7 @@ If any of these considerations are unacceptable for your environment, it would b
 
 ==== Using Existing (Un-Managed) Components With the Quay Operator
 
-If you have an existing components such as Postgres, Redis or object storage that you would like to use with Quay, you first configure then within the Quay configuration bundle (`config.yaml`) and then reference the bundle in your `QuayRegistry` (as a Kubernetes `secret`) while indicating which Components are unmanaged.
+If you have existing components such as Postgres, Redis or object storage that you would like to use with Quay, you first configure them within the Quay configuration bundle (`config.yaml`) and then reference the bundle in your `QuayRegistry` (as a Kubernetes `Secret`) while indicating which components are unmanaged.
 
 For example, to use an existing Postgres database:
 
@@ -232,13 +232,13 @@ metadata:
 
 . Create the `QuayRegistry` in your namespace:
 
-```
+```sh
 $ oc create -n <your-namespace> -f quay.yaml
 ```
 
 . Wait until the `status.registryEndpoint` is populated.
 
-```
+```sh
 $ oc get -n <your-namespace> quayregistry my-registry -o jsonpath="{.status.registryEndpoint}" -w
 ```
 
@@ -269,7 +269,9 @@ When the Quay Operator starts up, it immediately looks for any `QuayRegistries`
 
 Upgrades are supported from previous versions of the Operator which used the `QuayEcosystem` API for a limited set of configurations. To ensure that migrations do not happen unexpectedly, a special label needs to be applied to the `QuayEcosystem` for it to be migrated. A new `QuayRegistry` will be created for the Operator to manage, but the old `QuayEcosystem` will remain until manually deleted to ensure that you can roll back and still access Quay in case anything goes wrong. To migrate an existing `QuayEcosystem` to a new `QuayRegistry`, follow these steps:
 
-. If using an Operator-managed database, ensure that the password is set for the `postgres` root admin user (not set by default). This allows remote access to the database for migration. The Operator looks for this password in the `Secret` referenced by `spec.quay.database.credentialsSecretKey` under the `database-root-password` key.
+==== Preparing Managed Database for Migration
+
+If using an external database not deployed by the Quay Operator, skip this step. Otherwise, ensure that the password is set for the `postgres` root admin user (not set by default). This allows remote access to the database for migration. The Operator looks for this password in the `Secret` referenced by `spec.quay.database.credentialsSecretKey` under the `database-root-password` key.
 
 To set/change the password, use either the OpenShift console or `kubectl` to [open an SSH terminal connection](https://kubernetes.io/docs/tasks/debug-application-cluster/get-shell-running-container/) to the Postgres pod:
 ```sh
@@ -285,9 +287,11 @@ Type "help" for help.
 postgres=# \password
 ```
 
+==== Performing QuayEcosystem Upgrade
+
 . Add `"quay-operator/migrate": "true"` to the `metadata.labels` of the `QuayEcosystem`.
 
-. Wait for a `QuayRegistry` to be created with the same `metadata.name` as your `QuayEcosystem`.
+. Wait for a `QuayRegistry` to be created with the same `metadata.name` as your `QuayEcosystem`. The `QuayEcosystem` will be marked with the label `"quay-operator/migration-complete": "true"`.
 
 . Once the `status.registryEndpoint` of the new `QuayRegistry` is set, access Quay and confirm all data and settings were migrated successfully.
 
@@ -297,40 +301,50 @@ postgres=# \password
 
 If something goes wrong during the automatic upgrade from `QuayEcosystem` to `QuayRegistry`, follow these steps to revert back to using the `QuayEcosystem`:
 
-. Delete the `QuayRegistry` using either the UI or `kubectl`:
+* Delete the `QuayRegistry` using either the UI or `kubectl`:
 ```sh
 $ kubectl delete -n <namespace> quayregistry <quayecosystem-name>
 ```
 
-. If external access was provided using a `Route`, change the `Route` to point back to the original `Service` using the UI or `kubectl`.
+* If external access was provided using a `Route`, change the `Route` to point back to the original `Service` using the UI or `kubectl`.
 
 [NOTE]
 ====
-If your `QuayEcosystem` was managing the {productname} Postgres database, the upgrade process will migrate your data to a new Postgres database managed by the upgraded Operator.  Your old database will not be changed or removed but Quay will no longer use it once the migration is completed.  If there are issues during the data migration, the upgrade process will exit and it is recommended that you continue with your database as an unmanaged component.
+If your `QuayEcosystem` was managing the Postgres database, the upgrade process will migrate your data to a new Postgres database managed by the upgraded Operator.  Your old database will not be changed or removed but Quay will no longer use it once the migration is completed.  If there are issues during the data migration, the upgrade process will exit and it is recommended that you continue with your database as an unmanaged component.
 ====
 
 ==== Supported QuayEcosystem Configurations for Upgrades
 
 The Quay Operator will report errors in its logs and in `status.conditions` if migrating a `QuayEcosystem` component fails or is unsupported. All unmanaged components should migrate successfully because no Kubernetes resources need to be adopted and all the necessary values are already provided in Quay's `config.yaml`.
 
 *Database*
+
 Ephemeral database not supported (`volumeSize` field must be set). The `postgres` user must have a password set and referenced in `credentialsSecretName` (instructions above).
 
 *Redis*
+
 Nothing special needed.
 
 *External Access*
-Only `Route` access supported. 
 
-If using `LoadBalancer` (which the Operator will mark as an unmanaged component), ensure that you delete the `metadata.ownerReferences` field from existing `Service` _before_ deleting the `QuayEcosystem` to prevent Kubernetes from garbage collecting the `Service` and removing the load balancer. This can be achieved using the OpenShift UI or CLI.
+Only `Route` access supported for automatic migration. Manual migration required for other methods.
+
+* `LoadBalancer` without custom hostname:
+After the `QuayEcosystem` is marked with label `"quay-operator/migration-complete": "true"`, delete the `metadata.ownerReferences` field from existing `Service` _before_ deleting the `QuayEcosystem` to prevent Kubernetes from garbage collecting the `Service` and removing the load balancer. A new `Service` will be created with `metadata.name` format `<QuayEcosystem-name>-quay-app`. Edit the `spec.selector` of the existing `Service` to match the `spec.selector` of the new `Service` so traffic to the old load balancer endpoint will now be directed to the new pods. You are now responsible for the old `Service`; the Quay Operator will not manage it.
+
+* `LoadBalancer`/`NodePort`/`Ingress` with custom hostname:
+A new `Service` of type `LoadBalancer` will be created with `metadata.name` format `<QuayEcosystem-name>-quay-app`. Change your DNS settings to point to the `status.loadBalancer` endpoint provided by the new `Service`.
 
 *Clair*
+
 Nothing special needed.
 
 *Object Storage*
+
 `QuayEcosystem` did not have a managed object storage component, so object storage will always be marked as unmanaged. Local storage is not supported.
 
 *Repository Mirroring*
+
 Nothing special needed.
 
 = Advanced Concepts