Upgrading from v0.10 to v0.11
v0.11 release marks the removal of the
v1alpha1 API that was used in
previous versions of cert-manager, as well as our API group changing to be
cert-manager.io instead of
We have also removed support for the old configuration format that was
deprecated in the
v0.8 release. This means you must transition to using the
solvers style configuration format for your ACME issuers before
v0.11. For more information, see the
This makes for a fairly significant breaking change for users, as all cert-manager resources, or even Ingresses that reference cert-manager resources, will need to be updated to reflect these changes.
This upgrade should be performed in a few steps:
Back up existing cert-manager resources, as per the backup and restore guide.
Ensure the old cert-manager CRD resources have also been deleted:
kubectl get crd | grep certmanager.k8s.io
apiVersionon all your backed up resources from
Re-install cert-manager from scratch according to the installation guide.
You must be sure to properly backup, uninstall, re-install and restore your installation in order to ensure the upgrade is successful.
As well as changing the API group used by our CRDs, we have also changed the annotation-based configuration key to also reflect the new API group.
This means that if you use any cert-manager annotations on any of your other
resources (such as Ingresses,
you will need to update them to reflect the new API group.
A full table of annotations, including the old and new equivalents:
|Old Annotation||New Annotation|
You can use the following bash magic to print a list of Ingress resources that still contain an old annotation:
$ kubectl get ingress \--all-namespaces \-o json | \jq '.items | select(.metadata.annotations| to_entries | map(.key) | test("certmanager")) | "Ingress resource \(.metadata.namespace)/\(.metadata.name) contains old annotations: (\( .metadata.annotations | to_entries | map(.key) | select( . | test("certmanager") ) ))"'Ingress resource "demo/testcrt contains old annotations: (certmanager.k8s.io/cluster-issuer)"Ingress resource "example/ingress-resource contains old annotations: (certmanager.k8s.io/cluster-issuer)"
In order to help with this migration, the following CLI tool will automatically migrate these annotations for you. Note that it will not make any changes to your cluster for you.
Firstly, download the binary for your given platform
$ wget -O api-migration https://github.com/cert-manager/cert-manager/releases/download/v0.11.0/api-migration-linux
Or for Darwin
$ wget -O api-migration https://github.com/cert-manager/cert-manager/releases/download/v0.11.0/api-migration-darwin
Mark the binary as executable and run the binary against your cluster
$ chmod +x api-migration && ./api-migration --kubeconfig /path/to/my/kubeconfig.yaml
Follow the CLI output and check for the difference that has been made in files
$ diff ingress.yaml ingress-migrated.yaml
Finally, once the new ingress resources have been reviewed, apply the manifests
$ kubectl apply -f ingress-migrated.yaml --kubeconfig /path/to/my/kubeconfig.yaml
You should make sure to update all Ingress resources to ensure that your certificates continue to be kept up to date.
Support for the deprecated
spec.dns01 fields in
ClusterIssuer have been removed. Any
ClusterIssuer objects must
be converted to use the equivalent
spec.solvers.dns01 syntax. You can read more about the Issuer resource in
the configuration documentation.
Any issuers that haven't been converted will result the
cert-manager pod being
unable to find any solvers at the expected location. This will result in errors
like the following:
no configured challenge solvers can be used for this challenge