Upgrade Kf

This document describes how to upgrade an existing Kf installation and its dependencies.

Before you begin

You will need:

An existing cluster with Kf installed.
Access to a machine with gcloud, kf, and kubectl installed.

Validate the existing Kf installation

Get authentication credentials to interact with the cluster:

gcloud container clusters get-credentials CLUSTER_NAME \
  --zone CLUSTER_ZONE \
  --project CLUSTER_PROJECT_ID

Run kf debug and validate the Kf CLI and Kf server versions match.
- The CLI version is listed under Kf Client.
- The Kf server version is listed under kf["app.kubernetes.io/version"].
```
$ kf debug
...
Version:
  Kf Client:                        v2.0.0
  Server version:                   v1.17.13-gke.1401
  kf["app.kubernetes.io/version"]:  v2.0.0
...
```
If the Kf client and Kf server values do not match, download and install the version of the Kf CLI that matches the server version then repeat the check with the new CLI. The CLI version must match the server version before you continue.
Run kf doctor to check the state of your cluster. Ensure all tests pass before you continue.
```
$ kf doctor
...
=== RUN doctor/user
=== RUN doctor/user/ContainerRegistry
--- PASS: doctor/user
   --- PASS: doctor/user/ContainerRegistry
...
```
If you see the message Error: environment failed checks, follow the guidance in the doctor output to resolve the issue and retry the command until it is successful.

Upgrade

To upgrade Kf perform the following steps:

Prepare the local environment and the upgrade.
Upgrade Kf's dependencies.
Upgrade Kf and verify that the upgrade was a success.

Prepare the upgrade

Run kf version to get the current version of Kf.
```
$ kf version
kf version v2.0.0 linux
```
Find the next newest version of Kf from the downloads page.

Warning: Kf currently only supports upgrading one minor version at a time. For example v2.0.0 to v2.1.0.
1. Download the Kf release YAML file and save it as kf-release.yaml.
2. Download the version of Kf for your OS and name it kf-next.
3. Run chmod to make kf-next executable:
```
chmod +x kf-next
```
4. Run kf-next version to ensure the downloaded version matches the version of Kf you want to install:
```
$ kf-next version
kf version v2.1.0 linux
```
Make a backup of the config-defaults configmap by running:
```
kubectl get configmap config-defaults -o yaml -n kf > config-defaults-backup.yaml
```
Note: This backup is for reference only and should not be directly applied.
Run kubectl diff -f kf-release.yaml and inspect the changes the upgrade would make to your cluster.

Note: Pay close attention to the config-defaults configmap. Kf uses that configmap to store cluster wide customizations like domains, feature flags, and container registries.
Edit kf-release.yaml and modify it to keep any changes you want to maintain.

For example, if you set the config-defaults configmap property spaceDefaultToV3Stack to false in v2.0.0 of Kf, the v2.1.0 release would have the default value of true.
Run kubectl diff -f kf-release.yaml again to ensure any changes you made produce the expected output.

Upgrade Kf dependencies

Open the downloads page and find the dependency matrix for the version of Kf you're upgrading to.
Upgrade Tekton:
1. Open the Tekton Release page.
2. Find the version of Tekton listed in the Kf dependency matrix.
3. Run the command under the "Installation one-liner" heading to upgrade Tekton.
Upgrade Cloud Service Mesh:
1. Open the Cloud Service Mesh upgrade guide.
2. In the version dropdown, pick the version of Cloud Service Mesh listed in the Kf dependency matrix.
3. Follow the guide to upgrade ASM.

Upgrade and verify Kf

Install the upgraded Kf components using the modified release configuration:
```
kubectl apply -f kf-release.yaml
```
Run doctor to ensure the newly installed version is healthy:
```
kf-next doctor --retries=12 --delay=5s
```
The command will run cluster checks several times. It's normal for a few of the attempts to fail while the new controllers are starting.

If the command fails with the message Error: environment failed checks, follow the guidance in the doctor output to resolve the issue and retry the command until it is successful.
Replace the existing kf CLI on your system with the kf-next CLI.
```
chmod +x kf-next
mv kf-next $(which kf)
```
Note: You might have to run this command as a super user using sudo if Kf is installed globally.

Compare the config-defaults-backup.yaml file with kubectl diff -f config-defaults-backup.yaml to ensure your cluster is still configured correctly.

For example, if you kept all changes from your old Kf version, and approved use of a new buildpack bundled with the next version of Kf:

$ kubectl diff -f config-defaults-backup.yaml
diff -u -N /tmp/LIVE/v1.ConfigMap.kf.config-defaults /tmp/MERGED/v1.ConfigMap.kf.config-defaults
--- /tmp/LIVE/v1.ConfigMap.kf.config-defaults
+++ /tmp/MERGED/v1.ConfigMap.kf.config-defaults
@@ -131,6 +131,8 @@
     enable_route_services: false
   spaceBuildpacksV2: |
-    - name: new_buildpack
-      url: https://github.com/cloudfoundry/new-buildpack
     - name: staticfile_buildpack
       url: https://github.com/cloudfoundry/staticfile-buildpack
     - name: java_buildpack
exit status 1