Downgrade updates after testing

- Add steps to delete v3.0 KDD CRDs after downgrade
projectcalico · Dec 21, 2017 · c3ea326 · c3ea326
1 parent b19b644
commit c3ea326
Show file tree

Hide file tree

Showing 4 changed files with 222 additions and 66 deletions.
diff --git a/master/getting-started/kubernetes/upgrade/delete.md b/master/getting-started/kubernetes/upgrade/delete.md
@@ -14,6 +14,9 @@ following conditions.
 
 - [A data migration attempt failed partway through, leaving the etcdv3 datastore
   with some, but not all of your etcvd2 data](#deleting-calico-data-from-etcdv3-after-a-partial-migration).
+
+- [You upgraded to Calico v3.0 but then downgraded to your previous version
+  but need to clean up before upgrading again](#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade).
 
 
 ## Deleting Calico data from etcdv2 after a successful migration and upgrade
@@ -104,4 +107,55 @@ This procedure requires etcdctl v3. The etcdctl tool is installed along with etc
 ### Next steps
 
 Return to [Migrate your data](/{{page.version}}/getting-started/kubernetes/upgrade/migrate)
-to try again.
+to try again.
+
+## Deleting Calico data from the Kubernetes API datastore after a downgrade
+
+### Prerequisites
+
+- This procedure requires kubectl.
+- This procedure should only be done if you have upgraded to v3.0+ and then
+  downgraded to your previous version.
+
+### Deleting Calico data from the Kubernetes API datastore
+
+1. Check that the data exists in the Kubernetes API datastore. Issue the
+   following.
+
+   ```
+   kubectl get crd
+   ```
+
+1. Verify the output contains lines with the following:
+   - `bgpconfigurations.crd.projectcalico.org`
+   - `felixconfigurations.crd.projectcalico.org`
+   - `clusterinformations.crd.projectcalico.org`
+   - `networkpolicies.crd.projectcalico.org`
+
+
+1. Issue the following commands to delete the {{site.prodname}} data.
+
+   ```
+   kubectl delete crd bgpconfigurations.crd.projectcalico.org
+   kubectl delete crd felixconfigurations.crd.projectcalico.org
+   kubectl delete crd clusterinformations.crd.projectcalico.org
+   kubectl delete crd networkpolicies.crd.projectcalico.org
+   ```
+
+   It returns the number of keys it deleted.
+
+1. Issue the following command to confirm that the {{site.prodname}} data was deleted.
+   Verify the output does not contain the `crd`s deleted above.
+
+   ```
+   kubectl get crd
+   ```
+
+1. Congratulations! You've cleaned {{site.prodname}}'s Kuberentes API
+   datastore upgraded data.
+
+### Next steps
+
+Return to [Upgrading a self-hosted installation that uses the Kubernetes API
+datastore](upgrade#upgrading-a-self-hosted-installation-that-uses-the-kubernetes-api-datastore)
+to try again.
diff --git a/master/getting-started/kubernetes/upgrade/downgrade.md b/master/getting-started/kubernetes/upgrade/downgrade.md
@@ -3,61 +3,85 @@ title: Downgrading Calico
 no_canonical: true
 ---
 
+## About downgrading {{site.prodname}}
+
 Under some circumstances, you may need to perform a downgrade and return your
-cluster to the previous version of {{site.prodname}}. You may need to do this
-before running `calico-upgrade complete` or afterwards. If you need to downgrade 
-your cluster after running `calico-upgrade complete`, you should do so as soon
-as possible to avoid an outage. Any pods created after `calico-upgrade complete`
-and before downgrading will lose networking.
+cluster to the previous version of {{site.prodname}}. If you need to downgrade
+you should do so as soon as possible to avoid an outage.
+
+> **Important**: After downgrading or aborting the migration it is necessary
+> to delete the previously migrated
+> [etcd](delete#deleting-calico-data-from-etcdv2-after-a-successful-migration-and-upgrade)
+> or [Kubernetes API](delete#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade)
+> data before re-running the migration.
+{: .alert .alert-info}
+
+The downgrade procedure varies according to how you originally installed
+{{site.prodname}} and your datastore type.
+
+- Follow the steps to [Downgrade a self-hosted installation that uses the etcd
+  datastore](#downgrading-a-self-hosted-installation-that-uses-the-etcd-datastore)
+  when migration has been done and the {{site.prodname}} components have been
+  upgraded.
+  > **Important**: Any pods created after `calico-upgrade complete` and
+  > before downgrading will lose networking.
+  {: .alert .alert-danger}
+
+- To [Downgrade a self-hosted installation that uses the
+  Kubernetes API datastore](#downgrading-a-self-hosted-installation-that-uses-the-kubernetes-api-datastore)
+  follow these steps.
 
-## Downgrading a self-hosted installation
+
+- [Downgrading a custom installation](#downgrading-a-custom-installation)
+
+## Downgrading a self-hosted installation that uses the etcd datastore
 
 If you have upgraded {{site.prodname}} by deploying the latest manifest,
 follow the steps here to downgrade.
 
-1. Follow the steps in [Aborting the upgrade](#aborting-the-upgrade)
-   before downgrading the {{site.prodname}} components.
+1. Remove any upgraded `calicoctl` instances and install the previous `calicoctl`.
 
-1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
+> **Important**: Do not use versions of `calicoctl` v3.0+ after aborting the upgrade.
+> Doing so may result in unexpected behavior and data.
+{: .alert .alert-danger}
+
+1. Use the following command to re-enable the previous {{site.prodname}} components.
 
    ```
-   kubectl rollout undo ds/calico-node -n kube-system
-   kubectl rollout undo deployment/calico-kube-controllers -n kube-system
+   calico-upgrade abort
    ```
 
-1. Watch the status of the downgrade as follows.
+1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
 
    ```
-   watch kubectl get pods -n kube-system
+   kubectl rollout undo ds/calico-node -n kube-system
+   kubectl rollout undo deployment/calico-kube-controllers -n kube-system
    ```
-
-   Verify that the status of all {{site.prodname}} pods indicate `Running`.
+
+1. Watch the status of the downgrade as follows. When it reports complete and
+   successful, {{site.prodname}} is downgraded to the previous version.
 
    ```
-   calico-kube-controllers-6d4b9d6b5b-wlkfj   1/1       Running   0          3m
-   calico-node-hvvg8                          2/2       Running   0          3m
-   calico-node-vm8kh                          2/2       Running   0          3m
-   calico-node-w92wk                          2/2       Running   0          3m
+   kubectl rollout status deployment/calico-kube-controllers -n kube-system
+   kubectl rollout status ds/calico-node -n kube-system
    ```
 
-## Downgrading a custom installation
-
-_Docs for this coming soon!_
+## Downgrading a self-hosted installation that uses the Kubernetes API datastore
 
-## Aborting the upgrade
+1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
 
-If you have not upgraded the {{site.prodname}} components then follow
-the steps here to abort the upgrade and continue using your currently deployed
-version of {{site.prodname}}.
+   ```
+   kubectl rollout undo ds/calico-node -n kube-system
+   ```
 
-1. Abort the upgrade by running.
+1. Watch the status of the downgrade as follows. When it reports complete and
+   a successful, {{site.prodname}} is downgraded to the previous version.
 
    ```
-   calico-upgrade abort
+   kubectl rollout status ds/calico-node -n kube-system
    ```
 
-1. Remove any upgraded `calicoctl` instances and install the previous `calicoctl`.
+## Downgrading a custom installation
+
+_Docs for this coming soon!_
 
-> **Important**: Do not use versions of `calicoctl` v3.0+ after aborting the upgrade.
-> Doing so may result in unexpected behavior and data.
-{: .alert .alert-danger}
diff --git a/v3.0/getting-started/kubernetes/upgrade/delete.md b/v3.0/getting-started/kubernetes/upgrade/delete.md
@@ -14,6 +14,9 @@ following conditions.
 
 - [A data migration attempt failed partway through, leaving the etcdv3 datastore
   with some, but not all of your etcvd2 data](#deleting-calico-data-from-etcdv3-after-a-partial-migration).
+
+- [You upgraded to Calico v3.0 but then downgraded to your previous version
+  but need to clean up before upgrading again](#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade).
 
 
 ## Deleting Calico data from etcdv2 after a successful migration and upgrade
@@ -104,4 +107,55 @@ This procedure requires etcdctl v3. The etcdctl tool is installed along with etc
 ### Next steps
 
 Return to [Migrate your data](/{{page.version}}/getting-started/kubernetes/upgrade/migrate)
-to try again.
+to try again.
+
+## Deleting Calico data from the Kubernetes API datastore after a downgrade
+
+### Prerequisites
+
+- This procedure requires kubectl.
+- This procedure should only be done if you have upgraded to v3.0+ and then
+  downgraded to your previous version.
+
+### Deleting Calico data from the Kubernetes API datastore
+
+1. Check that the data exists in the Kubernetes API datastore. Issue the
+   following.
+
+   ```
+   kubectl get crd
+   ```
+
+1. Verify the output contains lines with the following:
+   - `bgpconfigurations.crd.projectcalico.org`
+   - `felixconfigurations.crd.projectcalico.org`
+   - `clusterinformations.crd.projectcalico.org`
+   - `networkpolicies.crd.projectcalico.org`
+
+
+1. Issue the following commands to delete the {{site.prodname}} data.
+
+   ```
+   kubectl delete crd bgpconfigurations.crd.projectcalico.org
+   kubectl delete crd felixconfigurations.crd.projectcalico.org
+   kubectl delete crd clusterinformations.crd.projectcalico.org
+   kubectl delete crd networkpolicies.crd.projectcalico.org
+   ```
+
+   It returns the number of keys it deleted.
+
+1. Issue the following command to confirm that the {{site.prodname}} data was deleted.
+   Verify the output does not contain the `crd`s deleted above.
+
+   ```
+   kubectl get crd
+   ```
+
+1. Congratulations! You've cleaned {{site.prodname}}'s Kuberentes API
+   datastore upgraded data.
+
+### Next steps
+
+Return to [Upgrading a self-hosted installation that uses the Kubernetes API
+datastore](upgrade#upgrading-a-self-hosted-installation-that-uses-the-kubernetes-api-datastore)
+to try again.
diff --git a/v3.0/getting-started/kubernetes/upgrade/downgrade.md b/v3.0/getting-started/kubernetes/upgrade/downgrade.md
@@ -3,61 +3,85 @@ title: Downgrading Calico
 no_canonical: true
 ---
 
+## About downgrading {{site.prodname}}
+
 Under some circumstances, you may need to perform a downgrade and return your
-cluster to the previous version of {{site.prodname}}. You may need to do this
-before running `calico-upgrade complete` or afterwards. If you need to downgrade 
-your cluster after running `calico-upgrade complete`, you should do so as soon
-as possible to avoid an outage. Any pods created after `calico-upgrade complete`
-and before downgrading will lose networking.
+cluster to the previous version of {{site.prodname}}. If you need to downgrade
+you should do so as soon as possible to avoid an outage.
+
+> **Important**: After downgrading or aborting the migration it is necessary
+> to delete the previously migrated
+> [etcd](delete#deleting-calico-data-from-etcdv2-after-a-successful-migration-and-upgrade)
+> or [Kubernetes API](delete#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade)
+> data before re-running the migration.
+{: .alert .alert-info}
+
+The downgrade procedure varies according to how you originally installed
+{{site.prodname}} and your datastore type.
+
+- Follow the steps to [Downgrade a self-hosted installation that uses the etcd
+  datastore](#downgrading-a-self-hosted-installation-that-uses-the-etcd-datastore)
+  when migration has been done and the {{site.prodname}} components have been
+  upgraded.
+  > **Important**: Any pods created after `calico-upgrade complete` and
+  > before downgrading will lose networking.
+  {: .alert .alert-danger}
+
+- To [Downgrade a self-hosted installation that uses the
+  Kubernetes API datastore](#downgrading-a-self-hosted-installation-that-uses-the-kubernetes-api-datastore)
+  follow these steps.
 
-## Downgrading a self-hosted installation
+
+- [Downgrading a custom installation](#downgrading-a-custom-installation)
+
+## Downgrading a self-hosted installation that uses the etcd datastore
 
 If you have upgraded {{site.prodname}} by deploying the latest manifest,
 follow the steps here to downgrade.
 
-1. Follow the steps in [Aborting the upgrade](#aborting-the-upgrade)
-   before downgrading the {{site.prodname}} components.
+1. Remove any upgraded `calicoctl` instances and install the previous `calicoctl`.
 
-1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
+> **Important**: Do not use versions of `calicoctl` v3.0+ after aborting the upgrade.
+> Doing so may result in unexpected behavior and data.
+{: .alert .alert-danger}
+
+1. Use the following command to re-enable the previous {{site.prodname}} components.
 
    ```
-   kubectl rollout undo ds/calico-node -n kube-system
-   kubectl rollout undo deployment/calico-kube-controllers -n kube-system
+   calico-upgrade abort
    ```
 
-1. Watch the status of the downgrade as follows.
+1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
 
    ```
-   watch kubectl get pods -n kube-system
+   kubectl rollout undo ds/calico-node -n kube-system
+   kubectl rollout undo deployment/calico-kube-controllers -n kube-system
    ```
-
-   Verify that the status of all {{site.prodname}} pods indicate `Running`.
+
+1. Watch the status of the downgrade as follows. When it reports complete and
+   successful, {{site.prodname}} is downgraded to the previous version.
 
    ```
-   calico-kube-controllers-6d4b9d6b5b-wlkfj   1/1       Running   0          3m
-   calico-node-hvvg8                          2/2       Running   0          3m
-   calico-node-vm8kh                          2/2       Running   0          3m
-   calico-node-w92wk                          2/2       Running   0          3m
+   kubectl rollout status deployment/calico-kube-controllers -n kube-system
+   kubectl rollout status ds/calico-node -n kube-system
    ```
 
-## Downgrading a custom installation
-
-_Docs for this coming soon!_
+## Downgrading a self-hosted installation that uses the Kubernetes API datastore
 
-## Aborting the upgrade
+1. Use the following commands to initiate a downgrade of the {{site.prodname}} components.
 
-If you have not upgraded the {{site.prodname}} components then follow
-the steps here to abort the upgrade and continue using your currently deployed
-version of {{site.prodname}}.
+   ```
+   kubectl rollout undo ds/calico-node -n kube-system
+   ```
 
-1. Abort the upgrade by running.
+1. Watch the status of the downgrade as follows. When it reports complete and
+   a successful, {{site.prodname}} is downgraded to the previous version.
 
    ```
-   calico-upgrade abort
+   kubectl rollout status ds/calico-node -n kube-system
    ```
 
-1. Remove any upgraded `calicoctl` instances and install the previous `calicoctl`.
+## Downgrading a custom installation
+
+_Docs for this coming soon!_
 
-> **Important**: Do not use versions of `calicoctl` v3.0+ after aborting the upgrade.
-> Doing so may result in unexpected behavior and data.
-{: .alert .alert-danger}