diff --git a/.spelling b/.spelling index 17697568cc2..c0cb9afbb79 100644 --- a/.spelling +++ b/.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 diff --git a/content/en/docs/installation/upgrading/remove-deprecated-apis.md b/content/en/docs/installation/upgrading/remove-deprecated-apis.md index ae366d89051..837ac94749f 100644 --- a/content/en/docs/installation/upgrading/remove-deprecated-apis.md +++ b/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 -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). diff --git a/content/en/docs/usage/cmctl.md b/content/en/docs/usage/cmctl.md index 2bca236ca96..328d76da144 100644 --- a/content/en/docs/usage/cmctl.md +++ b/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 `.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 +```