From bb519664cdcf3406a91945c537c4caa95e7ce928 Mon Sep 17 00:00:00 2001
From: Shane McDonald <me@shanemcd.com>
Date: Thu, 18 Mar 2021 12:31:24 -0400
Subject: [PATCH] Add seperate docs for migration

---
 README.md         | 23 +------------------
 docs/migration.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 22 deletions(-)
 create mode 100644 docs/migration.md

diff --git a/README.md b/README.md
index dcc5b4bb..560b326b 100644
--- a/README.md
+++ b/README.md
@@ -181,28 +181,7 @@ type: Opaque
 
 #### Migrating data from an old AWX instance
 
-To migrate data from an older AWX installation, the Custom Resource needs to know about the connection details. Those connection details should be stored as a secret and specified as `tower_old_postgres_configuration_secret` at the CR spec level.
-
-
-The secret should be formatted as follows:
-
-```yaml
----
-apiVersion: v1
-kind: Secret
-metadata:
-  name: <resourcename>-old-postgres-configuration
-  namespace: <target namespace>
-stringData:
-  host: <external ip or url resolvable by the cluster>
-  port: <external port, this usually defaults to 5432>
-  database: <desired database name>
-  username: <username to connect as>
-  password: <password to connect with>
-type: Opaque
-```
-
-> For `host`, a URL resolvable by the cluster could look something like `postgresql.<namespace>.svc.cluster.local`, where `<namespace>` is filled in with the namespace of the AWX deployment you are migrating data from.  
+For instructions on how to migrate from an older version of AWX, see [migration.md](./docs/migration.md).
 
 #### Managed PostgreSQL Service
 
diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 00000000..5431c51c
--- /dev/null
+++ b/docs/migration.md
@@ -0,0 +1,58 @@
+# Migrating data from an old AWX instance
+
+To migrate data from an older AWX installation, you must provide some information via Secrets.
+
+## Creating Secrets for Migration
+
+### Secret Key
+
+You can find your old secret key in the inventory file you used to deploy AWX in releases prior to version 18. 
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <resourcename>-secret-key
+  namespace: <target namespace>
+stringData:
+  secret_key: <old-secret-key>
+type: Opaque
+```
+
+**Note**: `<resourcename>` must match the `name` of the AWX object you are creating. In our example below, it is `awx`.
+
+### Old Databse Credentials
+
+The secret should be formatted as follows:
+
+```yaml
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <resourcename>-old-postgres-configuration
+  namespace: <target namespace>
+stringData:
+  host: <external ip or url resolvable by the cluster>
+  port: <external port, this usually defaults to 5432>
+  database: <desired database name>
+  username: <username to connect as>
+  password: <password to connect with>
+type: Opaque
+```
+
+> For `host`, a URL resolvable by the cluster could look something like `postgresql.<namespace>.svc.cluster.local`, where `<namespace>` is filled in with the namespace of the AWX deployment you are migrating data from.
+
+## Deploy AWX
+
+When you apply your AWX object, you must specify the name to the database secret you created above:
+
+```yaml
+apiVersion: awx.ansible.com/v1beta1
+kind: AWX
+metadata:
+  name: awx
+spec:
+  tower_old_postgres_configuration_secret: <resourcename>-old-postgres-configuration
+  ...
+```