As part of the upgrade procedure, you ensure that your Kf installation uses the latest version of the Kf operator:
- Confirm your current Kf version can upgrade to Kf v2.4.1.
- Upgrade to Kf v2.4.1.
- Upgrade dependencies (if needed).
Before you begin
You will need:
- An existing cluster with Kf installed.
- Access to a machine with
gcloud
,kf
, andkubectl
installed.
Preparing for the upgrade
Connect to your target cluster
gcloud container clusters get-credentials CLUSTER_NAME \
--zone CLUSTER_ZONE \
--project CLUSTER_PROJECT_ID
Confirm 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.3.2
Server version: v1.20.6-gke.1000
kf["app.kubernetes.io/version"]: v2.3.2
...
If the Kf client and Kf server values do not match, but the server version is v2.3.x, install the Kf v2.4.1 CLI before you continue.
If the Kf server value is older than v2.3.x, you must first incrementally upgrade to Kf v2.3.x to continue.
Confirm 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.
Optionally backup Kf configmaps if you have made customizations
Make a backup of the
config-defaults
configmap by running:kubectl get configmap config-defaults -o yaml -n kf > config-defaults-backup.yaml
Make a backup of the
config-secrets
configmap by running:kubectl get configmap config-secrets -o yaml -n kf > config-secrets-backup.yaml
Upgrade the Kf operator
The Kf operator was first released as part of versions 2.4.0:
If you have already installed the Kf operator as part of installing 2.4.0, then you only have to upgrade it as part of upgrading to 2.4.1.
If you are upgrading from 2.3.2, you must install the 2.4.1 version of the Kf operator to upgrade to operator managed Kf.
Upgrade the current Kf operator
The Kf operator performs upgrades for you.
Apply the operator yaml:
kubectl apply -f "https://storage.googleapis.com/kf-releases/v2.4.1/operator.yaml"
Install the Kf operator for the first time
Perform these steps to upgrade to operator managed Kf.
Apply the operator yaml:
kubectl apply -f "https://storage.googleapis.com/kf-releases/v2.4.1/operator.yaml"
Choose between using defaults or retaining customizations:
Prepare
kfsystem.yaml
for the upgrade using defaults:Download the
kfsystem.yaml
file, fill in the variables below, then run the commands in the same directory as the file to automatically preparekfsystem.yaml
for the upgrade.export CLUSTER_PROJECT_ID=YOUR_PROJECT_ID export CLUSTER_NAME=YOUR_CLUSTER_NAME export CONTAINER_REGISTRY=YOUR_CLUSTER_COMPUTE_REGION-docker.pkg.dev/${CLUSTER_PROJECT_ID}/${CLUSTER_NAME} kubectl apply -f kfsystem.yaml kubectl patch \ kfsystem kfsystem \ --type='json' \ -p="[{'op': 'replace', 'path': '/spec/kf', 'value': {'enabled': true, 'config': {'spaceContainerRegistry': '${CONTAINER_REGISTRY}', 'secrets':{'workloadidentity':{'googleserviceaccount':'${CLUSTER_NAME}-sa', 'googleprojectid':'${CLUSTER_PROJECT_ID}'}}}}}]"
Prepare
kfsystem.yaml
for the upgrade while preserving customizations:Download the
kfsystem.yaml
file.Make a backup of the
config-defaults
configmap by running:kubectl get configmap config-defaults -o yaml -n kf > config-defaults-backup.yaml
Make a backup of the
config-secrets
configmap by running:kubectl get configmap config-secrets -o yaml -n kf > config-secrets-backup.yaml
Inspect the current config-defaults and config-secrets configmaps, and find the corresponding settings in
kfsystem.yaml
.Copy over the existing settings from
config-secrets
andconfig-defaults
. All the settings inconfig-secrets
andconfig-defaults
can be found inkfsystem.yaml
. ThegoogleProjectId
field is now required.The
wi.googleServiceAccount
field is the full Service Account inconfig-secrets
, but forkfsystem
the suffix must be removed. For example,${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com
would become${CLUSTER_NAME}-sa
inkfsystem.yaml
.After the settings are copied over, change the field
enabled
inkfsystem
totrue
.Save your changes to
kfsystem.yaml
.Configure the operator for Kf:
kubectl apply -f kfsystem.yaml
Upgrade Kf dependencies
Upgrade Tekton:
kubectl apply -f "https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.23.0/release.yaml"
Upgrade Cloud Service Mesh:
- Follow the steps in the Cloud Service Mesh 1.9 upgrade guide.
Upgrade Config Connector.
Download the required Config Connector Operator tar file.
Extract the tar file.
tar zxvf release-bundle.tar.gz
Install the Config Connector operator on your cluster.
kubectl apply -f operator-system/configconnector-operator.yaml
Configure the Config Connector operator if installing Config Connector for the first time.
Copy the following YAML into a file named
configconnector.yaml
:# configconnector.yaml apiVersion: core.cnrm.cloud.google.com/v1beta1 kind: ConfigConnector metadata: # the name is restricted to ensure that there is only one # ConfigConnector resource installed in your cluster name: configconnector.core.cnrm.cloud.google.com spec: mode: cluster googleServiceAccount: "KF_SERVICE_ACCOUNT_NAME" # Replace with the full service account resolved from ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com
Apply the configuration to your cluster.
kubectl apply -f configconnector.yaml
Verify Config Connector is fully installed before continuing.
Config Connector runs all of its components in a namespace named
cnrm-system
. Verify the Pods are ready by running the following command:kubectl wait -n cnrm-system --for=condition=Ready pod --all
If Config Connector is installed correctly, the output is similar to the following:
pod/cnrm-controller-manager-0 condition met
Setup Workload Identity if installing Config Connector for the first time.
kubectl annotate serviceaccount \ --namespace cnrm-system \ --overwrite \ cnrm-controller-manager \ iam.gke.io/gcp-service-account=${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com
Upgrade to the Kf v2.4.1 CLI
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.
gcloud storage cp gs://kf-releases/v2.4.1/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.gcloud storage cp gs://kf-releases/v2.4.1/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 usebash
, the instructions may need to be modified for other shells.mkdir -p ~/bin
gcloud storage cp gs://kf-releases/v2.4.1/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.gcloud storage cp gs://kf-releases/v2.4.1/kf-windows.exe kf.exe
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.4.1 Server version: v1.20.6-gke.1000 kf["app.kubernetes.io/version"]: v2.4.1 ...
- The CLI version is listed under
Verify Kf upgraded successfully
If installing the Kf operator for the first time, confirm the operator installed:
kubectl get deployment -n appdevexperience appdevexperience-operator
If you do not see the operator like in the example output below, review the Install the Kf operator for the first time steps.
NAME READY UP-TO-DATE AVAILABLE AGE appdevexperience-operator 1/1 1 1 1h
Run
doctor
to ensure the newly installed version is healthy:kf doctor --retries=20
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.If you have made customizations to
config-defaults
orconfig-secrets
, verify they carried over: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
If the verification steps pass, your cluster has successfully been upgraded! If you have any issues, please review the support page for guidance.