Docs: Upgrading a Kubeflow Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading from Kubeflow v0.7.0 or later

Alpha

This Kubeflow component has alpha status with limited support. See the Kubeflow versioning policies. The Kubeflow team is interested in your feedback about the usability of the feature.

Upgrading your Kubeflow deployment is supported if your deployment is v0.7.0 or later.

Prerequisites

Download the latest kfctl binary from the Kubeflow releases page.
Ensure that your Kubeflow namespace is annotated with the control-plane: kubeflow label. You can verify this by doing:
```
kubectl get namespace $NAMESPACE -o yaml
```
You should see something like:
```
metadata:
  labels:
    control-plane: kubeflow
```
If the label is not present, you can patch the namespace by doing
```
kubectl label namespace $NAMESPACE control-plane=kubeflow
```
You must have a local Kubeflow application directory matching your current deployment. We’ll call this ${KF_DIR}.
- This should be present if you deployed Kubeflow using the kfctl tool.
- If you deployed Kubeflow using some other method (e.g. the Deployment UI), you will need to first create a local deployment directory:
  1. Follow the instructions for environment preparations.
    - Make sure that the ${PROJECT}, ${ZONE}, and ${KF_NAME} variables match exactly with your deployment.
    - For ${CONFIG_URI}, use the appropriate YAML configuration file.
  2. Create your local deployment files:
```
mkdir -p ${KF_DIR}
cd ${KF_DIR}
kfctl build -V -f ${CONFIG_URI}
```

Upgrade instructions

Prepare your upgrade specification:

Create an upgrade specification in the parent directory of your ${KF_DIR} directory. Base your upgrade specification on one of the specifications supplied in the kubeflow/manifests repository. For example, to upgrade a v0.7.0 deployment to v0.7.1 on GCP, use the kfctl_upgrade_gcp_iap_0.7.1.yaml specification. Your directory structure should look like this:
```
your-parent-directory
|----${KF_DIR}
|----<your-upgrade-specification.yaml>
```
For convenience, set the environment variable ${UPGRADE_SPEC} to the name of your upgrade specification:
```
export UPGRADE_SPEC=<your-upgrade-specification.yaml>
```

Modify the contents of the upgrade specification to suit your deployment:

apiVersion: kfupgrade.apps.kubeflow.org/v1alpha1
kind: KfUpgrade
metadata:
  name: kf-upgrade-v0.7.1
spec:
  currentKfDef:
    # Replace with the name of your Kubeflow app
    name: kubeflow-app
    version: v0.7.0
  newKfDef:
    # Replace with the name of your kubeflow app
    name: kubeflow-app
    version: v0.7.1
  # Replace this with the path to the KfDef that you are upgrading to
  baseConfigPath: https://raw.githubusercontent.com/kubeflow/manifests/v0.7-branch/kfdef/kfctl_gcp_iap.0.7.1.yaml

If you don’t need to change any kustomize parameter values in your configuration, run the apply command now to upgrade your deployment:

kfctl apply -f ${UPGRADE_SPEC} -V

Alternatively you can follow these steps to change the configuration before applying the upgrade:

Run a build command:
```
kfctl build -f ${UPGRADE_SPEC} -V
```
The above command creates a new Kubeflow application under the same parent directory as your ${KF_DIR}. The new Kubeflow application has a name in the form of a 7-character long hash value. The directory structure should look like this, where ${UPGRADE_DIR} indicates the new Kubeflow application:
```
your-parent-directory
|----${KF_DIR}
|----${UPGRADE_DIR}
|----<your-upgrade-specification.yaml>
```
You can examine and change the kustomize parameter values in the ${UPGRADE_DIR} directory.
Run the apply command to upgrade the deployment:
```
kfctl apply -f ${UPGRADE_SPEC} -V
```

Upgrades from earlier versions of Kubeflow

For earlier versions, Kubeflow makes no promises of backwards compatibility or upgradeability. Nonetheless, here are some instructions for updating your deployment:

Check your Kubeflow configuration directory (${KF_DIR}) into source control as a backup.
Delete your existing Kubeflow cluster:
```
kfctl delete -V 
```
Download the kfctl v1.0.2 release from the Kubeflow releases page.

Unpack the tar ball:

tar -xvf kfctl_<release tag>_<platform>.tar.gz

Update your kustomize manifests:
```
export CONFIG_FILE=<the path to your Kubeflow config file>
kfctl build -V -f ${CONFIG_FILE}
```
The ${CONFIG_FILE} environment variable must contain the path to the Kubeflow configuration file in your ${KF_DIR} directory. For example, ${KF_DIR}/kfctl_k8s_istio.v1.0.2.yaml or ${KF_DIR}/kfctl_istio_dex.yaml
Re-apply any customizations that you need.
Update the deployment:
```
kfctl apply -V -f ${CONFIG_FILE}
```

Upgrading Kubeflow Pipelines

See the Kubeflow Pipelines upgrade guide.