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.
Download the Kf release YAML file and save it as
kf-release.yaml.
Download the version of Kf for your OS and name
it kf-next.
Run chmod to make kf-next executable:
chmod+xkf-next
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:
Run kubectl diff -f kf-release.yaml and inspect the changes the upgrade
would make to your cluster.
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.
In the version dropdown, pick the version of Cloud Service Mesh listed in
the Kf dependency matrix.
Follow the guide to upgrade ASM.
Upgrade and verify Kf
Install the upgraded Kf components using the modified
release configuration:
kubectlapply-fkf-release.yaml
Run doctor to ensure the newly installed version is healthy:
kf-nextdoctor--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+xkf-nextmvkf-next$(whichkf)
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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Upgrade Kf\n\nThis document describes how to upgrade an existing Kf installation and its dependencies.\n\n\u003cbr /\u003e\n\nBefore you begin\n----------------\n\nYou will need:\n\n- An existing cluster with Kf installed.\n- Access to a machine with `gcloud`, `kf`, and `kubectl` installed.\n\nValidate the existing Kf installation\n-------------------------------------\n\n1. Get authentication credentials to interact with the cluster:\n\n gcloud container clusters get-credentials \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --zone \u003cvar translate=\"no\"\u003eCLUSTER_ZONE\u003c/var\u003e \\\n --project \u003cvar translate=\"no\"\u003eCLUSTER_PROJECT_ID\u003c/var\u003e\n\n2. Run `kf debug` and validate the Kf CLI and\n Kf server versions match.\n\n - The CLI version is listed under `Kf Client`.\n - The Kf server version is listed under `kf[\"app.kubernetes.io/version\"]`.\n\n $ kf debug\n ...\n Version:\n Kf Client: v2.0.0\n Server version: v1.17.13-gke.1401\n kf\\[\"app.kubernetes.io/version\"\\]: v2.0.0\n ...\n\n If the Kf client and Kf server\n values **do not** match, [download](/migrate/kf/docs/2.3/downloads)\n and [install](#install-kf) the version of the Kf CLI\n that matches the server version then repeat the check with the new CLI. The\n CLI version **must** match the server version before you continue.\n3. Run `kf doctor` to check the state of your cluster. Ensure all tests pass\n before you continue.\n\n $ kf doctor\n ...\n === RUN doctor/user\n === RUN doctor/user/ContainerRegistry\n --- PASS: doctor/user\n --- PASS: doctor/user/ContainerRegistry\n ...\n\n If you see the message `Error: environment failed checks`, follow the\n guidance in the `doctor` output to resolve the issue and retry the command\n until it is successful.\n\nUpgrade\n-------\n\nTo upgrade Kf perform the following steps:\n\n- Prepare the local environment and the upgrade.\n- Upgrade Kf's dependencies.\n- Upgrade Kf and verify that the upgrade was a success.\n\n### Prepare the upgrade\n\n1. Run `kf version` to get the current version of Kf.\n\n $ kf version\n kf version v2.0.0 linux\n\n2. Find the next newest version of Kf from the\n [downloads page](/migrate/kf/docs/2.3/downloads).\n\n | **Warning:** Kf currently only supports upgrading one minor version at a time. For example v2.0.0 to v2.1.0.\n 1. Download the Kf release YAML file and save it as\n `kf-release.yaml`.\n\n 2. Download the version of Kf for your OS and name\n it `kf-next`.\n\n 3. Run `chmod` to make `kf-next` executable:\n\n chmod +x kf-next\n\n 4. Run `kf-next version` to ensure the downloaded version matches the version of\n Kf you want to install:\n\n $ kf-next version\n kf version v2.1.0 linux\n\n3. Make a backup of the `config-defaults` configmap by running:\n\n kubectl get configmap config-defaults -o yaml -n kf \u003e config-defaults-backup.yaml\n\n | **Note:** This backup is for reference only and should not be directly applied.\n4. Run `kubectl diff -f kf-release.yaml` and inspect the changes the upgrade\n would make to your cluster.\n\n | **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.\n5. Edit `kf-release.yaml` and modify it to keep any changes you want to maintain.\n\n For example, if you set the `config-defaults` configmap property\n `spaceDefaultToV3Stack` to false in `v2.0.0` of Kf,\n the `v2.1.0` release would have the default value of `true`.\n6. Run `kubectl diff -f kf-release.yaml` again to ensure any changes you made\n produce the expected output.\n\n### Upgrade Kf dependencies\n\n1. Open the [downloads page](/migrate/kf/docs/2.3/downloads) and find the dependency matrix for the\n version of Kf you're upgrading to.\n\n2. Upgrade Tekton:\n\n 1. Open the [Tekton Release page](https://github.com/tektoncd/pipeline/releases).\n\n 2. Find the version of Tekton listed in the Kf\n dependency matrix.\n\n 3. Run the command under the \"Installation one-liner\" heading to upgrade Tekton.\n\n3. Upgrade Cloud Service Mesh:\n\n 1. Open the [Cloud Service Mesh upgrade guide](/service-mesh/docs/gke-on-prem-upgrading).\n\n 2. In the version dropdown, pick the version of Cloud Service Mesh listed in\n the Kf dependency matrix.\n\n 3. Follow the guide to upgrade ASM.\n\n### Upgrade and verify Kf\n\n1. Install the upgraded Kf components using the modified\n release configuration:\n\n kubectl apply -f kf-release.yaml\n\n2. Run `doctor` to ensure the newly installed version is healthy:\n\n kf-next doctor --retries=12 --delay=5s\n\n The command will run cluster checks several times. It's normal for a few of\n the attempts to fail while the new controllers are starting.\n\n If the command fails with the message `Error: environment failed checks`,\n follow the guidance in the `doctor` output to resolve the issue and retry the\n command until it is successful.\n3. Replace the existing `kf` CLI on your system with the `kf-next` CLI.\n\n chmod +x kf-next\n mv kf-next $(which kf)\n\n | **Note:** You might have to run this command as a super user using `sudo` if Kf is installed globally.\n4. Compare the `config-defaults-backup.yaml` file with\n `kubectl diff -f config-defaults-backup.yaml` to ensure your cluster is still\n configured correctly.\n\n For example, if you kept all changes from your old Kf\n version, and approved use of a new buildpack bundled with the next version\n of Kf: \n\n $ kubectl diff -f config-defaults-backup.yaml\n diff -u -N /tmp/LIVE/v1.ConfigMap.kf.config-defaults /tmp/MERGED/v1.ConfigMap.kf.config-defaults\n --- /tmp/LIVE/v1.ConfigMap.kf.config-defaults\n +++ /tmp/MERGED/v1.ConfigMap.kf.config-defaults\n @@ -131,6 +131,8 @@\n enable_route_services: false\n spaceBuildpacksV2: |\n - - name: new_buildpack\n - url: https://github.com/cloudfoundry/new-buildpack\n - name: staticfile_buildpack\n url: https://github.com/cloudfoundry/staticfile-buildpack\n - name: java_buildpack\n exit status 1"]]
