ceph-csi/docs/design/proposals/intree-migrate.md

In-tree storage plugin to CSI Driver Migration

Prior to CSI, Kubernetes provided a powerful volume plugin system. These volume plugins were “in-tree” meaning their code was part of the core Kubernetes code and shipped with the core Kubernetes binaries. The CSI migration effort enables the replacement of existing in-tree storage plugins such as kubernetes.io/rbd with a corresponding CSI driver. For more information on CSI migration effort refer design doc

RBD in-tree plugin to CSI migration

This feature is tracked in Kubernetes for v1.23 as alpha under RBD in-tree migration KEP . Below are the changes identified in the design discussions to enable CSI migration for RBD plugin:

ClusterID field in the migration request

Considering the clusterID field is a required one for CSI, but in-tree StorageClass has monitors field as a required thing the clusterID will be sent from the migration library based on the monitors field, Kubernetes storage admin supposed to create a clusterID based on the monitors hash ( ex: #md5sum <<< "<monaddress:port>") in the CSI config map and keep the monitors under this configuration before enabling the migration. While CSI driver receive the volume ID it will look at the configmap and figure out the monitors to do the operations. Thus, CSI operations are unchanged or untouched wrt to the clusterID field.

New Volume ID for existing volume operations

The existing volume will have a volume ID passed in similar to the following format:

mig_mons-<monitors-hash>_image-<imageUUID>_<pool-hash>

Details on the hash values:

• Monitors Hash: this carry a hash value (md5sum) which will be acted as the clusterID for the operations in this context.

• ImageUUID: this is the unique UUID generated by Kubernetes for the created volume.

• PoolHash: this is an encoded string of pool name.

The existing in-tree volume's node operations should work without any issues as those will be tracked as static volumes for the CSI driver. From above volume ID, the CSI driver can also connect to the backend cluster and clean/delete the image. The migration volume ID carry the information like monitors, pool and image name which is good enough for the driver to identify and connect to the backend cluster for its operations. With above volume ID in place, we will be able to support mount, unmount, delete and resize operations.

Migration secret for CSI operations

The in-tree secret has a data field called key which is the base64 admin secret key. The ceph CSI driver currently expect the secret to contain data field UserKey for the equivalent. The CSI driver also expect the UserID field which is not available in the in-tree secret by default. This missing userID will be filled (if the username differ than admin) in the migration secret as adminId field in the migration request, ie:

key field value will be picked up from the migration secret to UserKey field. adminId field value will be picked up from the migration secret to UserID field

if adminId field is nil or not set, UserID field will be filled with default value ie admin.The above logic get activated only when the secret is a migration secret, otherwise skipped to the normal workflow as we have today.

CephFS in-tree plugin to CSI migration

This is yet to be done and tracked at CephFS in-tree migration KEP

Additional Reference

Kubernetes 1.17 Feature: Kubernetes In-Tree to CSI Volume Migration Moves to Beta

Tracker Issue in Ceph CSI

In-tree storage plugin to CSI Driver Migration KEP