Update instructions for upgrading cert-manager resources and CRDs

[irbekrm]

Update the instructions how to ensure that cert-manager resources are stored in etcd at v1 and that the deprecated API versions are not recorded on CRD status fields to refer to the new cmctl upgrade migrate-api-version command

Testing the upgrade

1. Create a kind cluster with Kubernetes <= 1.21
2. helm install cert-manager jetstack/cert-manager -ncert-manager --create-namespace --set installCRDs=true --version v0.16
3. Create some legacy resources such these:

apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
  name: selfsigned-issuer-legacy
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
  name: test-old
spec:
  secretName: test-old
  dnsNames:
  - foo.bar
  issuerRef:
    name: selfsigned-issuer-legacy
    kind: Issuer
    group: cert-manager.io

These will be stored in etcd at v1beta1 which is the preferred storage version for cert-manager v0.16

7. Upgrade to cert-manager v1.6 (or any other cert-manager version that is v1 or higher)
   helm upgrade cert-manager jetstack/cert-manager -ncert-manager --create-namespace --set installCRDs=true --version v1.6.1
   8.Run cmctl upgrade migrate-api-version
8. Upgrade to cert-manager v1.7.0-alpha.0
9. Verify that the upgrade works and you can still retrieve all cert-manager resources

Signed-off-by: irbekrm irbekrm@gmail.com

/kind cleanup

[jetstack-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: irbekrm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [irbekrm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✔️ Deploy Preview for cert-manager-website ready!

🔨 Explore the source changes: 663378c

🔍 Inspect the deploy log: https://app.netlify.com/sites/cert-manager-website/deploys/61dddce188a8c000075b5088

😎 Browse the preview: https://deploy-preview-793--cert-manager-website.netlify.app/docs/installation/upgrading/remove-deprecated-apis

[irbekrm]

I've tried to add a wording that suggests that these instructions should be applied with caution and also some scripts to verify that things have been upgraded, but it does feel like this is now a bit verbose- happy to remove some of the verbosity or scripts if suggested :)

[irbekrm]

/hold

some related conversation here https://kubernetes.slack.com/archives/CDEQJ0Q8M/p1641311819078800

We might end up putting all those steps into a tool

[wallrj]

The cmctl tool has now merged, so we should reword this PR to explain how and when to use the tool

• Add 'cmctl upgrade migrate-api-version' tool to assist in v1.7 upgrade cert-manager#4711
• xref: Make it possible to upgrade cert-manager resources to v1 and old API versions from CRDs with cmctl cert-manager#4686

[maelvls]

I have tested the instructions performed:

• one upgrade from v1.6.1 to v1.7.0-alpha.0,
• one upgrade from v1.5.3 to v1.6.1.

Both went smoothly.

That said, could we give some indication to people who use a GitOps-like flow? The step (4) seems to indicate the command has to be run locally, which isn't possible for people using a GitOps flow (cc @jsoref)

[maelvls]

nit: Terminology uses the leading v to refer to cert-manager git tags (we also call these "patch releases" I think). I think by v1.6 you mean "release branch" which may be instead written "1.6" 😇 (I know I know I am way too picky)

Suggested change

	These APIs are no longer served in cert-manager `v1.6` and are fully removed in cert-manager `v1.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 `v1.6` or later.
	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.

[maelvls]

Suggested change

	4. Run [cmctl upgrade migrate-api-version command](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version) to migrate any resources that might be stored in `etcd` at the deprecated API versions and to patch the cert-manager CRDs.
	4. Run the command [`cmctl upgrade migrate-api-version`](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version) to migrate any resources that might be stored in `etcd` at the deprecated API versions and to patch the cert-manager CRDs.

[maelvls]

We should also propose or suggest a GitOps way to run this command. For example, we could suggest to create a Job and mention that an image of cmctl exists. What do you think @jsoref?

[irbekrm]

Job will not be able to act as a gate for upgrade - then we have to tell folks to check the job status etc. I think that running the tool from command line by default is probably safer and do it from a script in case of many clusters

[maelvls]

Ah right yes, that's a good point. I don't really know how people manage this, since sometimes the only possibility is to commit to a git repository (as opposed to manually running kubectl).

I pinged people on #argo-cd (CNCF slack) just to make sure I understand what people think about this upgrade path.

[irbekrm]

Yes, that's a good point, I imagine there is some approach for these kind of situations. I suppose in this case, the simplest solution would be to commit a Job that runs the command and check that it succeeded before upgrading.. but there might be a better solution

[irbekrm]

That said, could we give some indication to people who use a GitOps-like flow?

I think they should just run it from a script then, unless they use helm or something else that has a concept of pre-install hook.

[maelvls]

Thanks for writing this PR 🙏🙏

/lgtm

[maelvls]

/unhold

[maelvls]

@irbekrm Do you think we can remove WIP from the issue title?