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.

Motivation

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/v1 instead of apiVersion: networking.k8s.io/v1beta1)

Method

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 commit in order to use a git diff later)
  • run okctl apply application to 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.

Steps

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 initialDelaySeconds from 3 to 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.

okctl

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.