Update instructions for upgrading cert-manager resources and CRDs

.spelling

@@ -56,6 +56,7 @@ DataDog
 Dean-Coakley
 DigitalOcean
 Distroless
+etcd
 EC2
 ECDSA
 EKS
@@ -245,6 +246,7 @@ manual-rotation-private-key
 mechanism
 metadata
 middleware
+migrate-api-version
 misconfiguration
 misconfigured
 mixin

content/en/docs/installation/upgrading/remove-deprecated-apis.md

@@ -1,11 +1,11 @@
 ---
-title: "Removing Deprecated API Resources"
-linkTitle: "Removing Deprecated API Resources"
+title: "Migrating Deprecated API Resources"
+linkTitle: "Migrating Deprecated API Resources"
 weight: 20
 type: "docs"
 ---
 
-We have deprecated the following cert-manager APIs: 
+The following cert-manager APIs were deprecated in cert-manager `v1.4`:
 
 - `cert-manager.io/v1alpha2`
 - `cert-manager.io/v1alpha3`
@@ -14,37 +14,18 @@ We have deprecated the following cert-manager APIs:
 - `acme.cert-manager.io/v1alpha3`
 - `acme.cert-manager.io/v1beta1`
 
-These APIs were removed in cert-manager `v1.6.0`. If you have a cert-manager installation that is using or has previously used these deprecated APIs you'll need to upgrade your cert-manager custom resources and CRDs. This needs to be done before upgrading to cert-manager `v1.6.0`.
+These APIs are no longer served in cert-manager 1.6 and are fully removed in cert-manager 1.7. If you have a cert-manager installation that is using or has previously used these deprecated APIs you might need to upgrade your cert-manager custom resources and CRDs. This should be done before upgrading to cert-manager 1.6 or later.
 
-## Upgrading existing cert-manager resources
+{{% alert title="Note" color="warning" %}}
+An earlier version of this document listed a number of kubectl commands to run to migrate resources. These steps have now been encoded in [`cmctl upgrade migrate-api-version` command](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version). If you have already run the kubectl commands, your resources should have been migrated and there should be no need to also run the `cmctl` command. However, if you are not sure, you can still run the `cmctl` command as well- it will be a no-op if no actions are needed.
+{{% /alert %}}
 
-1. Familiarize yourself with the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects) on CRD versioning.
-2. Make sure your installed cert-manager deployment is `v1.0.0` or later.
-
-3. Make sure any version-controlled cert-manager custom resource config files that still use the deprecated APIs are updated to use the `cert-manager.io/v1` API and re-applied. This should update stored versions of the given resources.
-
-After that, follow the official Kubernetes documentation [here](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version):
-
-1. If there are other resources (e.g. `Certificate`s created by ingress-shim, `CertificateRequest`s, etc.) that are not version controlled and may have been created using the deprecated APIs, run
-   ```bash
-   kubectl get <resource_name> -oyaml | kubectl apply -f -
-   ```
-   to force the resources to be stored in `etcd` at the current storage version.
-
-2. To remove legacy API versions from cert-manager CRDs run the following `curl` commands:
+# Upgrading existing cert-manager resources
 
-```bash
-kubectl proxy &
-
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/certificates.cert-manager.io/status
-
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/certificaterequests.cert-manager.io/status
-
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/issuers.cert-manager.io/status
+1. Familiarize yourself with the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects) on CRD versioning.
 
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/clusterissuers.cert-manager.io/status
+2. Make sure your cert-manager deployment is currently at version `v1.0` or later.
 
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/orders.acme.cert-manager.io/status
+3. Make sure that any cert-manager custom resource manifests that refer to the deprecated APIs are updated to use the `cert-manager.io/v1` API and re-applied. You can use the [cmctl convert command](https://cert-manager.io/docs/usage/cmctl/#convert)to convert manifests.
 
-curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json"  -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/challenges.acme.cert-manager.io/status
-```
+4. Run the command [`cmctl upgrade migrate-api-version`](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version). It automates the steps described in [Upgrade existing objects to a new stored version](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version).

content/en/docs/usage/cmctl.md

@@ -49,6 +49,7 @@ Available Commands:
   inspect      Get details on certificate related resources
   renew        Mark a Certificate for manual renewal
   status       Get details on current status of cert-manager resources
+  upgrade      Tools that assist in upgrading cert-manager
   version      Print the cert-manager CLI version and the deployed cert-manager version
 
 Flags:
@@ -250,3 +251,22 @@ signed certificate to the local file `<name>.crt`, or specified by `-c,
 ```bash
 $ cmctl x create csr -f my-cert.yaml my-req -w
 ```
+
+#### Upgrade
+
+Tools that assist in upgrading cert-manager
+
+```bash
+$ cmctl upgrade --help
+```
+##### Migrate API version
+
+This command can be used to prepare a cert-manager installation that was created
+before cert-manager `v1` for upgrading to a cert-manager version `v1.6` or later.
+It ensures that any cert-manager custom resources that may have been stored in etcd at
+a deprecated API version get migrated to `v1`. See [Migrating Deprecated API
+Resources](https://cert-manager.io/docs/installation/upgrading/remove-deprecated-apis) for more context.
+
+```bash
+$ cmctl upgrade migrate-api-version --qps 5 --burst 10
+```