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

<br />

As part of the upgrade procedure, ensure that your Kf
installation uses the latest version of the Kf operator:

- Confirm your current Kf version can upgrade to Kf v2.11.31.
- Upgrade to Kf v2.11.31.
- Upgrade dependencies (if needed).

## Before you begin

> [!WARNING]
> **Warning:** The steps on this page are for upgrading Kf v2.10.x (or Kf v2.8.x) to Kf v2.11.31. If your current version is not Kf v2.10.x, you must first upgrade incrementally until your current version is v2.10.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.)

You will need:

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

## Prepare for the upgrade

### Connect to your target cluster

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

### Confirm that your current Kf CLI and server versions match

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.11.30
      Server version:                   v1.31.1-gke.2105000
      kf\["app.kubernetes.io/version"\]: v2.11.30
    ...

If the Kf client and Kf server
values **do not** match, but the server version is v2.10.x, [install](https://docs.cloud.google.com/migrate/kf/docs/2.11/upgrade.md.txt#upgrade-the-cli) the Kf v2.11.31 CLI before you continue.

If the Kf server value is older than v2.10.x, you must first incrementally upgrade to Kf v2.10.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](https://docs.cloud.google.com/migrate/kf/docs/2.11/support/troubleshooting.md.txt) to resolve the issue and retry the command
until it is successful.

## Upgrade the operator

The Kf operator performs upgrades for you.

1. Apply the operator yaml:

   > [!NOTE]
   > **Note:** This operation starts immediately, and is not reversible.

   ```
   kubectl apply -f "https://storage.googleapis.com/kf-releases/v2.11.31/operator.yaml"
   ```

## Upgrade Kf dependencies

1. Upgrade Tekton:


   ```
   kubectl apply -f "https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.68.0/release.yaml"
   ```

   <br />

2. Upgrade to Cloud Service Mesh v1.23.3-asm.1+config1:

   1. Follow the steps in the [Cloud Service Mesh upgrade guide](https://docs.cloud.google.com/service-mesh/v1.11/docs/unified-install/upgrade).

<!-- -->

1. Upgrade/Install Config Connector:

   For upgrading from Kf v2.11:
   Please follow the steps in the 'Install Config Connector' step in [Kf Install](https://docs.cloud.google.com/migrate/kf/docs/2.11/install.md.txt)

   For upgrading from Kf v2.7:
   1. [Download](https://storage.googleapis.com/configconnector-operator/1.129.2/release-bundle.tar.gz) the required Config Connector Operator tar file.

      > [!NOTE]
      > **Note:** Keep a copy of the installation bundle as you need this bundle to uninstall Config Connector.

   2. Extract the tar file.

      ```bash
      tar zxvf release-bundle.tar.gz
      ```
   3. Install the Config Connector operator on your cluster.

      ```bash
      kubectl apply -f operator-system/configconnector-operator.yaml
      ```

      <br />

## Upgrade to the Kf v2.11.31 CLI

1. Install the CLI:

   ### Linux

   This command installs the Kf CLI for all users on the system. Follow the
   instructions in the Cloud Shell tab to install it just for yourself.

   ```bash
   gcloud storage cp gs://kf-releases/v2.11.31/kf-linux /tmp/kf
   chmod a+x /tmp/kf
   sudo mv /tmp/kf /usr/local/bin/kf
   ```

   ### Mac

   This command installs `kf` for all users on the system.

   ```bash
   gcloud storage cp gs://kf-releases/v2.11.31/kf-darwin /tmp/kf
   chmod a+x /tmp/kf
   sudo mv /tmp/kf /usr/local/bin/kf
   ```

   ### Cloud Shell

   This command installs `kf` on your Cloud Shell instance if you use `bash`,
   the instructions may need to be modified for other shells.

   ```bash
   mkdir -p ~/bin
   gcloud storage cp gs://kf-releases/v2.11.31/kf-linux ~/bin/kf
   chmod a+x ~/bin/kf
   echo "export PATH=$HOME/bin:$PATH" >> ~/.bashrc
   source ~/.bashrc
   ```

   ### Windows

   This downloads `kf` to current directory. Add it to the path if you
   want to call if from anywhere other than the current directory.

   ```bash
   gcloud storage cp gs://kf-releases/v2.11.31/kf-windows.exe kf.exe
   ```
2. 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.11.31
         Server version:                   v1.31.1-gke.2105000
         kf\["app.kubernetes.io/version"\]: v2.11.31
       ...

## Verify that Kf upgraded successfully

1. Run `doctor` to ensure the newly installed version is healthy:

   ```bash
   kf doctor --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](https://docs.cloud.google.com/migrate/kf/docs/2.11/support.md.txt) page for guidance.