After you install vSphere Container Storage Plug-in in a native Kubernetes cluster, you can upgrade the plug-in to a newer version.

This procedure applies only to native, also called vanilla, Kubernetes clusters deployed in vSphere environment. To upgrade vSphere with Tanzu, see vSphere with Tanzu Configuration and Management.
Note: If you use the Beta topology feature in your current version of vSphere Container Storage Plug-in, do not upgrade to version 2.4. Wait for the next patch release.

vSphere Container Storage Plug-in Upgrade Considerations and Guidelines

When you perform an upgrade, follow these guidelines:
  • Be familiar with installation prerequisites and procedures for vSphere Container Storage Plug-in. See Prerequisites for Installing the vSphere Container Storage Plug-in and Deploy the vSphere Container Storage Plug-in on a Native Kubernetes Cluster.
  • Ensure that roles and privileges in your vSphere environment are updated. For more information, see vSphere Roles and Privileges.
  • To upgrade to vSphere Container Storage Plug-in v2.3.0, you require DNS forwarding configuration in CoreDNS ConfigMap to help resolve vSAN file share hostname. For more information, see Configure CoreDNS for vSAN File Share Volumes.
  • vSAN file share volumes (Read-Write-Many/Read-Only-Many vSphere CSI Volumes) become inaccessible after you upgrade vSphere Container Storage Plug-in. This issue is present in vSphere Container Storage Plug-in v2.0.0 to v2.2.1. For more information, see vSphere Container Storage Plug-in release notes.
  • New pods with file share volumes created using vSphere Container Storage Plug-in v2.3.0 will not have this issue. The workaround for this issue is to remount vSAN file service volumes used by the application pods at the same location from the Node VM Guest OS directly.
  • If you have RWM volumes backed by file service deployed using vSphere Container Storage Plug-in, remount the volumes before you upgrade vSphere Container Storage Plug-in.

Remount ReadWriteMany Volumes Backed by vSAN File Service

If you have RWM volumes backed by vSAN file service, use this procedure to remount the volumes before you upgrade vSphere Container Storage Plug-in.

This procedure is required if you upgrade from v2.0.1 to v2.3.0. If you upgrade from 2.3.0 to 2.4.0, you do not need to perform these steps. In addition, upgrades from v2.2.2, v2.1.2, and v2.0.2 to v2.3.0 or v2.4.0 do not require this procedure.

When you perform the following steps in a maintenance window, it might disrupt active IOs on the file share volumes used by application pods. If you have multiple replicas of the pod that access the same file share volume, it is recommended to perform the following steps on each mount point serially to minimize downtime and disruptions.

Procedure

  1. Find all RWM volumes on the cluster.
    # kubectl get pv -o wide | grep 'RWX\|ROX'
     pvc-7e43d1d3-2675-438d-958d-41315f97f42e   1Gi        RWX            Delete           Bound    default/www-web-0   file-sc                 107m   Filesystem
  2. Find all nodes where RWM volume is attached. In the below example, the volume is attached and mounted on the k8s-worker3 node.
    # kubectl get volumeattachment | grep pvc-7e43d1d3-2675-438d-958d-41315f97f42e
     csi-3afe670705e55e0679cba3f013c78ff9603333fdae6566745ea5f0cb9d621b20   csi.vsphere.vmware.com   pvc-7e43d1d3-2675-438d-958d-41315f97f42e   k8s-worker3   true       22s
  3. Log in to the k8s-worker3 node VM, and execute the following command to know where the volume is mounted.
    root@k8s-worker3:~# mount | grep pvc-7e43d1d3-2675-438d-958d-41315f97f42e
     10.83.28.38:/52d7e15c-d282-3bae-f64d-8851ad9d352c on /var/lib/kubelet/pods/43686ba4-d765-4378-807a-74049fca39ee/volumes/kubernetes.io~csi/pvc-7e43d1d3-2675-438d-958d-41315f97f42e/mount type nfs4 (rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=10.244.3.134,local_lock=none,addr=10.83.28.38)
  4. Unmount and remount volume at the same location with the same mount options used for mounting volume. For this step, you need to pre-install the nfs-common package on the worker VMs.
    1. Use the unmount -fl command to unmount the volume.
      root@k8s-worker3:~# umount -fl /var/lib/kubelet/pods/43686ba4-d765-4378-807a-74049fca39ee/volumes/kubernetes.io~csi/pvc-7e43d1d3-2675-438d-958d-41315f97f42e/mount
    2. Remount the volume with the same mount options used originally.
      root@k8s-worker3:~# mount -t nfs4 -o sec=sys,minorversion=1  10.83.28.38:/52d7e15c-d282-3bae-f64d-8851ad9d352c /var/lib/kubelet/pods/43686ba4-d765-4378-807a-74049fca39ee/volumes/kubernetes.io~csi/pvc-7e43d1d3-2675-438d-958d-41315f97f42e/mount
  5. Confirm mount point is accessible from the Node VM.
    root@k8s-worker3:~# mount | grep pvc-7e43d1d3-2675-438d-958d-41315f97f42e
     10.83.28.38:/52d7e15c-d282-3bae-f64d-8851ad9d352c on /var/lib/kubelet/pods/43686ba4-d765-4378-807a-74049fca39ee/volumes/kubernetes.io~csi/pvc-7e43d1d3-2675-438d-958d-41315f97f42e/mount type nfs4 (rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=10.83.26.244,local_lock=none,addr=10.83.28.38)
    
     root@k8s-worker3:~# ls -la /var/lib/kubelet/pods/43686ba4-d765-4378-807a-74049fca39ee/volumes/kubernetes.io~csi/pvc-7e43d1d3-2675-438d-958d-41315f97f42e/mount
     total 4
     drwxrwxrwx 3 root root    0 Aug  9 16:48 .
     drwxr-x--- 3 root root 4096 Aug  9 18:40 ..
     -rw-r--r-- 1 root root    6 Aug  9 16:48 test

What to do next

After you have remounted all the vSAN file share volumes on the worker VMs, upgrade the vSphere Container Storage Plug-in by reinstalling its YAML files.

Upgrade vSphere Container Storage Plug-in of a Version Earlier than 2.3.0

If you use vSphere Container Storage Plug-in of a version earlier than 2.3.0, to perform an upgrade, you first need to uninstall the earlier version. You then install a version of your choice.

The following example illustrates an upgrade of vSphere Container Storage Plug-in from v2.2.0 to v2.3.0.

Procedure

  1. Uninstall the existing version of vSphere Container Storage Plug-in using https://github.com/kubernetes-sigs/vsphere-csi-driver/tags.
    kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.2.0/manifests/v2.2.0/deploy/vsphere-csi-controller-deployment.yaml
    kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.2.0/manifests/v2.2.0/deploy/vsphere-csi-node-ds.yaml
    kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.2.0/manifests/v2.2.0/rbac/vsphere-csi-controller-rbac.yaml
    kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.2.0/manifests/v2.2.0/rbac/vsphere-csi-node-rbac.yaml
    After you run the above commands, wait for the vSphere Container Storage Plug-in controller pod and vSphere Container Storage Plug-in node pods to be deleted completely.
  2. Install vSphere Container Storage Plug-in of your choice, for example, v2.3.0.
    1. Create a new namespace for vSphere Container Storage Plug-in.
      kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.3.0/manifests/vanilla/namespace.yaml
    2. Copy vsphere-config-secret secret from kube-system namespace to the new namespace vmware-system-csi.
      kubectl get secret vsphere-config-secret --namespace=kube-system -o yaml | sed 's/namespace: .*/namespace: vmware-system-csi/' | kubectl apply -f -
    3. Delete vsphere-config-secret secret from kube-system namespace.
      kubectl delete secret vsphere-config-secret --namespace=kube-system
    4. Install vSphere Container Storage Plug-in.
      kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.3.0/manifests/vanilla/vsphere-csi-driver.yaml

Upgrade vSphere Container Storage Plug-in 2.3.0 to a Later Version

vSphere Container Storage Plug-in supports rolling upgrades from version 2.3.0 to any later version.

Follow this procedure to upgrade vSphere Container Storage Plug-in from 2.3.0 to a later version.

Procedure

  1. If need, apply changes to vsphere-config-secret in the vmware-system-csi namespace.
  2. Apply any necessary changes to the manifest pertaining to the release that you wish to use.
    For example, adjust the replica count in the vsphere-csi-controller deployment depending upon the number of master nodes in the cluster.
  3. To upgrade vSphere Container Storage Plug-in v2.3.0 to v2.4.0, run the following command.
    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/vsphere-csi-driver/v2.4.0/manifests/vanilla/vsphere-csi-driver.yaml