Before you begin
You will need:
- An existing cluster with Kf installed.
- Access to a machine with
gcloud
,kf
, andkubectl
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.
- The CLI version is listed under
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 thedoctor
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 makekf-next
executable:chmod +x kf-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:kubectl get configmap config-defaults -o yaml -n kf > config-defaults-backup.yaml
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 propertyspaceDefaultToV3Stack
to false inv2.0.0
of Kf, thev2.1.0
release would have the default value oftrue
.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:
Open the Tekton Release page.
Find the version of Tekton listed in the Kf dependency matrix.
Run the command under the "Installation one-liner" heading to upgrade Tekton.
Upgrade Cloud Service Mesh:
Open the Cloud Service Mesh upgrade guide.
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:
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 thedoctor
output to resolve the issue and retry the command until it is successful.Replace the existing
kf
CLI on your system with thekf-next
CLI.chmod +x kf-next
mv kf-next $(which kf)
Compare the
config-defaults-backup.yaml
file withkubectl 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