From 7d3055a8a819d6a1e46a42198a3cfdcef35b7872 Mon Sep 17 00:00:00 2001 From: Erik Stidham Date: Wed, 20 Dec 2017 19:35:30 -0600 Subject: [PATCH] Downgrade updates after testing - Add steps to delete v3.0 KDD CRDs after downgrade --- .../kubernetes/upgrade/delete.md | 61 ++++++++++++- .../kubernetes/upgrade/downgrade.md | 88 ++++++++++++------- .../kubernetes/upgrade/delete.md | 61 ++++++++++++- .../kubernetes/upgrade/downgrade.md | 88 ++++++++++++------- 4 files changed, 228 insertions(+), 70 deletions(-) diff --git a/master/getting-started/kubernetes/upgrade/delete.md b/master/getting-started/kubernetes/upgrade/delete.md index 557894a2b17..da6962708ec 100644 --- a/master/getting-started/kubernetes/upgrade/delete.md +++ b/master/getting-started/kubernetes/upgrade/delete.md @@ -14,8 +14,12 @@ 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 are using the Kubernetes API datastore and upgraded to Calico v3.0 but + then downgraded to v2.6.4. You want to clean the Calico v3.0 data out of + the Kubernetes API datastore. If you plan to attempt another upgrade to + Calico v3.0, this is required.](#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade). + ## Deleting Calico data from etcdv2 after a successful migration and upgrade ### Prerequisite @@ -104,4 +108,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. \ No newline at end of file +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 index 316e75b92b0..77ca2946c61 100644 --- 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 index 03d0c201491..64f4ac15e82 100644 --- a/v3.0/getting-started/kubernetes/upgrade/delete.md +++ b/v3.0/getting-started/kubernetes/upgrade/delete.md @@ -14,8 +14,12 @@ 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 are using the Kubernetes API datastore and upgraded to Calico v3.0 but + then downgraded to v2.6.4. You want to clean the Calico v3.0 data out of + the Kubernetes API datastore. If you plan to attempt another upgrade to + Calico v3.0, this is required.](#deleting-calico-data-from-the-kubernetes-api-datastore-after-a-downgrade). + ## Deleting Calico data from etcdv2 after a successful migration and upgrade ### Prerequisite @@ -104,4 +108,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. \ No newline at end of file +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 index f394c05d33c..f4ef315cac3 100644 --- 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 redirect_from: latest/getting-started/kubernetes/upgrade/downgrade --- +## 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}