diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index e8e35796a..6196b0faa 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -2,7 +2,8 @@ Get started =========== -The guides in this section will explain how to install and set up cert-manager. +The guides in this section will explain how to install, set up cert-manager, and +uninstall cert-manager. .. toctree:: :maxdepth: 2 diff --git a/docs/getting-started/install/kubernetes.rst b/docs/getting-started/install/kubernetes.rst index 730471c2b..1c19c5c18 100644 --- a/docs/getting-started/install/kubernetes.rst +++ b/docs/getting-started/install/kubernetes.rst @@ -42,8 +42,7 @@ As part of the installation, cert-manager also deploys a webhook deployment as an `APIService`_. This can cause issues when uninstalling cert-manager if the API service still exists but the webhook is no longer running as the API server is unable to reach the validating webhook. Ensure to follow the documentation -when uninstalling cert-manager. TODO (@joshvanl): add uninstalling documentation -link when this has been created. +when :doc:`uninstalling cert-manager <../../../tasks/uninstall/index>`. The webhook enables cert-manager to implement validation and mutating webhooks on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is diff --git a/docs/getting-started/install/openshift.rst b/docs/getting-started/install/openshift.rst index ae4f624f1..8b59a3a19 100644 --- a/docs/getting-started/install/openshift.rst +++ b/docs/getting-started/install/openshift.rst @@ -50,8 +50,7 @@ As part of the installation, cert-manager also deploys a webhook deployment as an `APIService`_. This can cause issues when uninstalling cert-manager if the API service still exists but the webhook is no longer running as the API server is unable to reach the validating webhook. Ensure to follow the documentation -when uninstalling cert-manager. TODO (@joshvanl): add uninstalling documentation -link when this has been created. +when :doc:`uninstalling cert-manager <../../../tasks/uninstall/index>`. The webhook enables cert-manager to implement validation and mutating webhooks on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is diff --git a/docs/tasks/index.rst b/docs/tasks/index.rst index 0b4270db2..603277951 100644 --- a/docs/tasks/index.rst +++ b/docs/tasks/index.rst @@ -9,6 +9,7 @@ want to configure. .. toctree:: :maxdepth: 2 + uninstall/index issuers/index issuing-certificates/index backup-restore-crds diff --git a/docs/tasks/uninstall/index.rst b/docs/tasks/uninstall/index.rst new file mode 100644 index 000000000..a71eefa55 --- /dev/null +++ b/docs/tasks/uninstall/index.rst @@ -0,0 +1,16 @@ +========================= +Uninstalling cert-manager +========================= + +cert-manager supports running on Kubernetes_ and OpenShift_. The uninstallation +process between the two platforms is similar, although there are a number of +extra notes to be aware of per-platform. + +.. toctree:: + :maxdepth: 1 + + kubernetes + openshift + +.. _Kubernetes: https://kubernetes.io +.. _OpenShift: https://www.openshift.com diff --git a/docs/tasks/uninstall/kubernetes.rst b/docs/tasks/uninstall/kubernetes.rst new file mode 100644 index 000000000..4783ee187 --- /dev/null +++ b/docs/tasks/uninstall/kubernetes.rst @@ -0,0 +1,85 @@ +========================== +Uninstalling on Kubernetes +========================== + +Below is the processes for uninstalling cert-manager on Kubernetes. There are +two processes to chose depending on which method you used to install +cert-manager - static manifests or ``helm``. + +.. warning:: + + To uninstall cert-manger you should always use the same process for installing + but in reverse. Deviating from the following process whether cert-manager has + been installed from static manifests or helm can cause issues and + potentially broken states. Please ensure you follow the below steps when + uninstalling to prevent this happening. + +Before continuing, ensure that all cert-manager resources that have been created +by users have been deleted. You can check for any existing resources with the +following command: + +.. code-block:: shell + + kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests --all-namespaces + +Once all these resources have been deleted you are ready to uninstall +cert-manager using the procedure determined by how you installed. + +Uninstalling with regular manifests +=================================== + +Uninstalling from an installation with regular manifests is a case of running +the installation process, *in reverse*, using the delete command of ``kubectl``. + +First delete the installation manifests using a link to your currently running +version vX.Y.Z like so: + +.. code-block:: shell + + kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.yaml + +Finally, delete the cert-manager namespace: + +.. code-block:: shell + + kubectl delete namespace cert-manager + +Uninstalling with Helm +====================== + +Uninstalling cert-manager from a ``helm`` installation is a case of running the +installation process, *in reverse*, using the delete command on both ``kubectl`` +and ``helm``. + +Firstly, delete the cert-manager installation using ``helm``. Ensure the +``--purge`` flag is applied. + +.. code-block:: shell + + helm delete cert-manager --purge + +Next, delete the cert-manager namespace: + +.. code-block:: shell + + kubectl delete namespace cert-manager + +Finally, delete the cert-manger `CustomResourceDefinitions`_ using the link to +the version vX.Y you installed: + +.. code-block:: shell + + kubectl delete -f https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml + +Namespace Stuck in Termination State +==================================== + +If the namespace has been marked for deletion without deleting the cert-manager +installation first, the namespace may become stuck in a terminating state. This +is typically due to the fact that the `APIService`_ resource still exists +however the webhook is no longer running so is no longer reachable. To resolve +this, follow the first step from the above procedures according to the method of +installation that was used. + +.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ +.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server diff --git a/docs/tasks/uninstall/openshift.rst b/docs/tasks/uninstall/openshift.rst new file mode 100644 index 000000000..4a6b99781 --- /dev/null +++ b/docs/tasks/uninstall/openshift.rst @@ -0,0 +1,65 @@ +========================= +Uninstalling on OpenShift +========================= + +Below is the processes for uninstalling cert-manager on OpenShift. + +.. warning:: + + To uninstall cert-manger you should always use the same process for installing + but in reverse. Deviating from the following process can cause issues and + potentially broken states. Please ensure you follow the below steps when + uninstalling to prevent this happening. + +Login to your OpenShift cluster +=============================== + +Before you can uninstall cert-manager, you must first ensure your local machine +is configured to talk to your OpenShift cluster using the ``oc`` tool. + +.. code-block:: shell + + # Login to the OpenShift cluster as the system:admin user + oc login -u system:admin + +Uninstalling with regular manifests +=================================== + +Before continuing, ensure that all cert-manager resources that have been created +by users have been deleted. You can check for any existing resources with the +following command: + +.. code-block:: shell + + oc get Issuers,ClusterIssuers,Certificates,CertificateRequests --all-namespaces + +Once all these resources have been deleted you are ready to uninstall +cert-manager. + +Uninstalling from an installation with regular manifests is a case of running +the installation process, *in reverse*, using the delete command of ``oc``. + +First delete the installation manifests using a link to your currently running +version vX.Y.Z like so: + +.. code-block:: shell + + oc delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager-openshift.yaml + +Finally, delete the cert-manager namespace: + +.. code-block:: shell + + oc delete namespace cert-manager + +Namespace Stuck in Termination State +==================================== + +If the namespace has been marked for deletion without deleting the cert-manager +installation first, the namespace may become stuck in a terminating state. This +is typically due to the fact that the `APIService`_ resource still exists +however the webhook is no longer running so is no longer reachable. To resolve +this, follow the steps from the above procedure in order. + +.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ +.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server