Docs: moved upgrade segment from readme (#1481)

ansible · Jul 27, 2023 · 3a1b763 · 3a1b763
1 parent fcc25b1
commit 3a1b763
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -19,12 +19,6 @@ NOTE:  we are in the process of moving this readme into official docs in the /do
 * [Table of Contents](#table-of-contents)
    * [Usage](#usage)
       * [Uninstall](#uninstall)
-      * [Upgrading](#upgrading)
-         * [Backup](#backup)
-         * [v0.14.0](#v0140)
-            * [Cluster-scope to Namespace-scope considerations](#cluster-scope-to-namespace-scope-considerations)
-            * [Project is now based on v1.x of the operator-sdk project](#project-is-now-based-on-v1x-of-the-operator-sdk-project)
-            * [Steps to upgrade](#steps-to-upgrade)
       * [Disable IPV6](#disable-ipv6)
       * [Add Execution Nodes](#adding-execution-nodes)
           * [Custom Receptor CA](#custom-receptor-ca)
@@ -51,62 +45,6 @@ Deleting an AWX instance will remove all related deployments and statefulsets, h
 
 **Note**: If you ever intend to recover an AWX from an existing database you will need a copy of the secrets in order to perform a successful recovery.
 
-### Upgrading
-
-To upgrade AWX, it is recommended to upgrade the awx-operator to the version that maps to the desired version of AWX.  To find the version of AWX that will be installed by the awx-operator by default, check the version specified in the `image_version` variable in `roles/installer/defaults/main.yml` for that particular release.
-
-Apply the awx-operator.yml for that release to upgrade the operator, and in turn also upgrade your AWX deployment.
-
-#### Backup
-
-The first part of any upgrade should be a backup. Note, there are secrets in the pod which work in conjunction with the database. Having just a database backup without the required secrets will not be sufficient for recovering from an issue when upgrading to a new version. See the [backup role documentation](https://github.com/ansible/awx-operator/tree/devel/roles/backup) for information on how to backup your database and secrets.
-
-In the event you need to recover the backup see the [restore role documentation](https://github.com/ansible/awx-operator/tree/devel/roles/restore). *Before Restoring from a backup*, be sure to:
-* delete the old existing AWX CR
-* delete the persistent volume claim (PVC) for the database from the old deployment, which has a name like `postgres-13-<deployment-name>-postgres-13-0`
-
-**Note**: Do not delete the namespace/project, as that will delete the backup and the backup's PVC as well.
-
-
-#### PostgreSQL Upgrade Considerations
-
-If there is a PostgreSQL major version upgrade, after the data directory on the PVC is migrated to the new version, the old PVC is kept by default.
-This provides the ability to roll back if needed, but can take up extra storage space in your cluster unnecessarily. You can configure it to be deleted automatically
-after a successful upgrade by setting the following variable on the AWX spec. 
-
-
-```yaml
-  spec:
-    postgres_keep_pvc_after_upgrade: False
-```
-
-
-#### v0.14.0
-
-##### Cluster-scope to Namespace-scope considerations
-
-Starting with awx-operator 0.14.0, AWX can only be deployed in the namespace that the operator exists in. This is called a namespace-scoped operator. If you are upgrading from an earlier version, you will want to
-delete your existing `awx-operator` service account, role and role binding.
-
-##### Project is now based on v1.x of the operator-sdk project
-
-Starting with awx-operator 0.14.0, the project is now based on operator-sdk 1.x. You may need to manually delete your old operator Deployment to avoid issues.
-
-##### Steps to upgrade
-
-Delete your old AWX Operator and existing `awx-operator` service account, role and role binding in `default` namespace first:
-
-```
-$ kubectl -n default delete deployment awx-operator
-$ kubectl -n default delete serviceaccount awx-operator
-$ kubectl -n default delete clusterrolebinding awx-operator
-$ kubectl -n default delete clusterrole awx-operator
-```
-
-Then install the new AWX Operator by following the instructions in [Basic Install](#basic-install-on-existing-cluster). The `NAMESPACE` environment variable have to be the name of the namespace in which your old AWX instance resides.
-
-Once the new AWX Operator is up and running, your AWX deployment will also be upgraded.
-
 ### Disable IPV6
 Starting with AWX Operator release 0.24.0,[IPV6 was enabled in ngnix configuration](https://github.com/ansible/awx-operator/pull/950) which causes
 upgrades and installs to fail in environments where IPv6 is not allowed. Starting in 1.1.1 release, you can set the `ipv6_disabled` flag on the AWX

diff --git a/docs/upgrade/upgrading.md b/docs/upgrade/upgrading.md
@@ -0,0 +1,55 @@
+### Upgrading
+
+To upgrade AWX, it is recommended to upgrade the awx-operator to the version that maps to the desired version of AWX.  To find the version of AWX that will be installed by the awx-operator by default, check the version specified in the `image_version` variable in `roles/installer/defaults/main.yml` for that particular release.
+
+Apply the awx-operator.yml for that release to upgrade the operator, and in turn also upgrade your AWX deployment.
+
+#### Backup
+
+The first part of any upgrade should be a backup. Note, there are secrets in the pod which work in conjunction with the database. Having just a database backup without the required secrets will not be sufficient for recovering from an issue when upgrading to a new version. See the [backup role documentation](https://github.com/ansible/awx-operator/tree/devel/roles/backup) for information on how to backup your database and secrets.
+
+In the event you need to recover the backup see the [restore role documentation](https://github.com/ansible/awx-operator/tree/devel/roles/restore). *Before Restoring from a backup*, be sure to:
+* delete the old existing AWX CR
+* delete the persistent volume claim (PVC) for the database from the old deployment, which has a name like `postgres-13-<deployment-name>-postgres-13-0`
+
+**Note**: Do not delete the namespace/project, as that will delete the backup and the backup's PVC as well.
+
+
+#### PostgreSQL Upgrade Considerations
+
+If there is a PostgreSQL major version upgrade, after the data directory on the PVC is migrated to the new version, the old PVC is kept by default.
+This provides the ability to roll back if needed, but can take up extra storage space in your cluster unnecessarily. You can configure it to be deleted automatically
+after a successful upgrade by setting the following variable on the AWX spec. 
+
+
+```yaml
+  spec:
+    postgres_keep_pvc_after_upgrade: False
+```
+
+
+#### v0.14.0
+
+##### Cluster-scope to Namespace-scope considerations
+
+Starting with awx-operator 0.14.0, AWX can only be deployed in the namespace that the operator exists in. This is called a namespace-scoped operator. If you are upgrading from an earlier version, you will want to
+delete your existing `awx-operator` service account, role and role binding.
+
+##### Project is now based on v1.x of the operator-sdk project
+
+Starting with awx-operator 0.14.0, the project is now based on operator-sdk 1.x. You may need to manually delete your old operator Deployment to avoid issues.
+
+##### Steps to upgrade
+
+Delete your old AWX Operator and existing `awx-operator` service account, role and role binding in `default` namespace first:
+
+```
+$ kubectl -n default delete deployment awx-operator
+$ kubectl -n default delete serviceaccount awx-operator
+$ kubectl -n default delete clusterrolebinding awx-operator
+$ kubectl -n default delete clusterrole awx-operator
+```
+
+Then install the new AWX Operator by following the instructions in [Basic Install](#basic-install-on-existing-cluster). The `NAMESPACE` environment variable have to be the name of the namespace in which your old AWX instance resides.
+
+Once the new AWX Operator is up and running, your AWX deployment will also be upgraded.