TL;DR: To upgrade an application, download the latest Okctl, run
okctl apply application, do a git diff to see changes, and merge manually with your existing files.
Sometimes newer versions of Okctl updates the way
okctl apply application works. For example, the latest Okctl version may create an application with better health checks than the old version.
To apply these changes, you will need to upgrade the application. This guide describes how to do this.
Some motivations to upgrade an application include:
- the newest Okctl has fixed a bug from a previous version
- you want to stay updated with how Okctl works
- Kubernetes manifests are being deprecated (for instance, newer versions of Kubernetes require Ingress versions to be
apiVersion: networking.k8s.io/v1instead of
okctl apply application writes Kubernetes manifests from scratch. It does not care about existing Kubernetes manifests, it simply overwrites any existing files. Since you probably have made some changes to these files, simply running
okctl apply application again would overwrite these changes.
In order to update the manifests, you need to:
- Backup your old manifest (use
git commitin order to use a git diff later)
okctl apply applicationto create manifests from scratch
- get updated values from the new version of Okctl, while also keeping values needed by your application (use a git diff tool)
In other words, you need to do a manual merge. You can do this in any way you want, but in the steps below, we describe how to do this with git. The principle is to keep your changes, but add the stuff that is new from Okctl.
In the following steps, we're assuming that your git repository contains existing Kubernetes manifests (YAML files) for your application, which have been generated the following way:
okctl scaffold application > my-app.yaml okctl -c my-cluster.yaml apply application -f my-app.yaml
If you don't have the application manifest (
my-app-yaml), you can attempt to re-create it by running
okctl scaffold application and edit the values to match your existing application.
Start by downloading the latest version of Okctl. See install instructions.
Ensure you have a clean git state:
git status -s # should return no output
Delete existing application manifests:
rm -rf infrastructure/applications/my-app
This ensures that we delete files that Okctl apply application doesn't produce anymore.
You can skip the above
rm command to get a simpler git diff below. However, you should only do so if you're certain
okctl apply application does not produce fewer files than it did last time you ran
okctl apply application. For instance, the old version of Okctl produced
some-deployment-patch.json but the new version doesn't.
Re-create application manifests from scratch:
okctl -c my-cluster.yaml apply application -f my-app.yaml
Running this command overwrites your existing files.
The next step is to use your favorite git diff tool to bring back what's specific for your application, while also keeping updated values from Okctl.
In the example screenshot below, we're using Intellij to do the diff. The newest version of Okctl has changed
5. So, we apply those two changes. Additionally, since
okctl apply application wrote this file from scratch, it didn't keep the environment variable
DSN that my application needs. So we'll apply that change as well.
When you have reapplied all files, all that's left to do is to commit and push the changes:
git add . git commit -m "Upgrade my-app to okctl 0.0.60"git push
You have now successfully upgraded your application to the latest version of Okctl.