If the Kf client and Kf server
values do not match, but the server version is v2.7.x, install the Kf v2.9.0 CLI before you continue.
If the Kf server value is older than v2.7.x, you must first incrementally upgrade to Kf v2.7.x to continue.
Confirm that Kf is healthy before upgrading
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 any FAIL or Error: environment failed checks messages, follow the
guidance in the kf doctor output, or view the troubleshooting guide to resolve the issue and retry the command
until it is successful.
Run doctor to ensure the newly installed version is healthy:
kfdoctor--retries=20
The command runs 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.
If the verification steps pass, your cluster has successfully been upgraded! If you have any issues, please review the support page for guidance.
[[["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-29 UTC."],[],[],null,["# Upgrade Kf outside Google Cloud\n\nThis document describes how to upgrade an existing Kf installation and its dependencies.\n\n\u003cbr /\u003e\n\nAs part of the upgrade procedure, ensure that your Kf\ninstallation uses the latest version of the Kf operator:\n\n- Confirm your current Kf version can upgrade to Kf v2.9.0.\n- Upgrade to Kf v2.9.0.\n- Upgrade dependencies (if needed).\n\nBefore you begin\n----------------\n\n| **Warning:** The steps on this page are for upgrading Kf v2.7.x (or Kf v2.8.x) to Kf v2.9.0. If your current version is not Kf v2.7.x, you must first upgrade incrementally until your current version is v2.7.x (one minor version at a time). (For upgrading from v2.8.x on GKE clusters, please pay close attention to the 'Upgrade/Install Config Connector' part.)\n\nYou will need:\n\n- An existing cluster with Kf installed.\n- Access to a machine with `gcloud`, `kf`, and `kubectl` installed.\n\nPrepare for the upgrade\n-----------------------\n\n### Connect to your target cluster\n\n gcloud container hub memberships 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\n### Confirm that your current Kf CLI and server versions match\n\nRun `kf debug` and validate the Kf CLI and\nKf 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.7.3\n Server version: v1.21.6-gke.1500\n kf\\[\"app.kubernetes.io/version\"\\]: v2.7.3\n ...\n\nIf the Kf client and Kf server\nvalues **do not** match, but the server version is v2.7.x, [install](#upgrade-the-cli) the Kf v2.9.0 CLI before you continue.\n\nIf the Kf server value is older than v2.7.x, you must first incrementally upgrade to Kf v2.7.x to continue.\n\n### Confirm that Kf is healthy before upgrading\n\nRun `kf doctor` to check the state of your cluster. Ensure all tests pass\nbefore 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\nIf you see any `FAIL` or `Error: environment failed checks` messages, follow the\nguidance in the `kf doctor` output, or view the [troubleshooting guide](/migrate/kf/docs/2.9/support/troubleshooting) to resolve the issue and retry the command\nuntil it is successful.\n\nUpgrade the operator\n--------------------\n\nThe Kf operator performs upgrades for you.\n\n1. Apply the operator yaml:\n\n **Note:** This operation starts immediately, and is not reversible. \n\n ```\n kubectl apply -f \"https://storage.googleapis.com/kf-releases/v2.9.0/operator.yaml\"\n ```\n\nUpgrade Kf dependencies\n-----------------------\n\n1. Upgrade Tekton:\n\n\n ```\n kubectl apply -f \"https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.32.1/release.yaml\"\n ```\n\n \u003cbr /\u003e\n\n2. Upgrade to Cloud Service Mesh v1.12:\n\n 1. Follow the steps in the [Cloud Service Mesh upgrade guide](/service-mesh/v1.11/docs/unified-install/upgrade).\n\nUpgrade to the Kf v2.9.0 CLI\n----------------------------\n\n1. Install the CLI:\n\n ### Linux\n\n This command installs the Kf CLI for all users on the system. Follow the\n instructions in the Cloud Shell tab to install it just for yourself. \n\n gcloud storage cp gs://kf-releases/v2.9.0/kf-linux /tmp/kf\n chmod a+x /tmp/kf\n sudo mv /tmp/kf /usr/local/bin/kf\n\n ### Mac\n\n This command installs `kf` for all users on the system. \n\n gcloud storage cp gs://kf-releases/v2.9.0/kf-darwin /tmp/kf\n chmod a+x /tmp/kf\n sudo mv /tmp/kf /usr/local/bin/kf\n\n ### Cloud Shell\n\n This command installs `kf` on your Cloud Shell instance if you use `bash`,\n the instructions may need to be modified for other shells. \n\n mkdir -p ~/bin\n gcloud storage cp gs://kf-releases/v2.9.0/kf-linux ~/bin/kf\n chmod a+x ~/bin/kf\n echo \"export PATH=$HOME/bin:$PATH\" \u003e\u003e ~/.bashrc\n source ~/.bashrc\n\n ### Windows\n\n This downloads `kf` to current directory. Add it to the path if you\n want to call if from anywhere other than the current directory. \n\n gcloud storage cp gs://kf-releases/v2.9.0/kf-windows.exe kf.exe\n\n2. 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.9.0\n Server version: v1.21.6-gke.1500\n kf\\[\"app.kubernetes.io/version\"\\]: v2.9.0\n ...\n\nVerify that Kf upgraded successfully\n------------------------------------\n\n1. Run `doctor` to ensure the newly installed version is healthy:\n\n kf doctor --retries=20\n\n The command runs 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.\n\nIf the verification steps pass, your cluster has successfully been upgraded! If you have any issues, please review the [support](/migrate/kf/docs/2.9/support) page for guidance."]]