The Rancher Application Catalog represents a curated list of applications that we use ourselves, and we’ve taken the steps to extend their Helm charts into the question and answer form that makes them so easy to deploy and upgrade. The App Catalog strives to be a one-click upgrade solution, where if no answers have changed, upgrades are quick and painless.
Occasionally an application makes a change that isn’t backwards compatible, or the deployment architecture changes into one that requires manual steps outside of what one can do from within Helm or the Application Catalog. This happens most often with alpha software, which we all know that we aren’t really supposed to be using in production. It’s just so tempting, and when it works well enough, it’s easy to forget that alpha software means that changes between versions may not be backwards or forwards compatible.
Jetstack has been developing cert-manager actively, rolling out new features at a pace that they have started deploying through their own Helm repository instead of the Helm stable repository.
We use cert-manager via Helm for certificate management of the Rancher Server itself, and we’ve also made it available in the App Catalog for installation in downstream clusters.
Because of the changes that Jetstack is rolling out between versions, it is, unfortunately, not possible to adhere to the “one-click upgrade” objectives of the App Catalog. This is not a negative reflection of Jetstack; if anything, it’s a byproduct of their success. All the same, we’re going to temporarily remove cert-manager from the App Catalog. You’ll still be able to deploy it directly, either via Helm or through standard manifests, both of which are clearly explained in their documentation.
Jetstack also does a fantastic job of outlining the specific instructions for upgrading from each version, calling out special instructions when necessary, and you’ll find their dev team in #cert-manager on the Kubernetes Slack.
How to Migrate
If the version that you’re running is from the App Catalog, you’ll need to remove the app and install the chart or manifests from Jetstack. Most of the steps are outlined in a YouTube video from Adrian Goins, but essentially consist of:
- Make a backup of all cert-manager resources. This will back up the ClusterIssuer and Certificates.
- On the Apps page in Rancher delete the cert manager app. This will not remove any certificates or affect any running workloads.
- Install the latest version of cert-manager using either Helm or direct manifests.
- Restore your backup - this will recreate the ClusterIssuer and any other resources. If you are upgrading to 0.11.0 or newer, you will need to follow the additional steps outlined here and here to update your ClusterIssuer/Issuer(s) and any annotations.
- If necessary, perform an upgrade of cert-manager according to the instructions.
- Test your new installation.
Take care to observe any changes between versions when you upgrade. A safe method is to upgrade through each version and test along the way, instead of making a leap over several versions.
What Next?
Jetstack is rapidly approaching a 1.0 release of cert-manager, after which the pace of changes will hopefully subside. When we’re able to ensure that your experience with cert-manager in the App Catalog is easy and painless, we’ll look into bringing it back into the App Catalog.
Until then, you’ll be totally fine working directly with the upstream version. There’s nothing better for automatic certificate management than cert-manager, and the Jetstack team is truly fantastic. We’re looking forward to continuing to use cert-manager long into the future.