From 5a4bf4d151c15a0fce376bd89c1ec5644fba6368 Mon Sep 17 00:00:00 2001 From: Humble Chirammal Date: Tue, 2 Nov 2021 17:28:14 +0530 Subject: [PATCH] doc: add migration design documentation This commit adds migration design doc which carry information about the required changes and design for rbd intree to csi migration. Fixes https://github.com/ceph/ceph-csi/issues/2596 Updates https://github.com/ceph/ceph-csi/issues/2509 Signed-off-by: Humble Chirammal --- docs/design/proposals/intree-migrate.md | 85 +++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/design/proposals/intree-migrate.md diff --git a/docs/design/proposals/intree-migrate.md b/docs/design/proposals/intree-migrate.md new file mode 100644 index 000000000..9c525cd3a --- /dev/null +++ b/docs/design/proposals/intree-migrate.md @@ -0,0 +1,85 @@ +# 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](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/csi-migration.md) + +## RBD in-tree plugin to CSI migration + +This feature is tracked in Kubernetes for v1.23 as alpha under +[RBD in-tree migration KEP](https://github.com/kubernetes/enhancements/issues/2923) +. 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 <<< +""`) 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-_image-_ +``` + +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](https://github.com/kubernetes/enhancements/issues/2924) + +### Additional Reference + +[Kubernetes 1.17 Feature: Kubernetes In-Tree to CSI Volume Migration Moves to Beta](https://kubernetes.io/blog/2019/12/09/kubernetes-1-17-feature-csi-migration-beta/) + +[Tracker Issue in Ceph CSI](https://github.com/ceph/ceph-csi/issues/2509) + +[In-tree storage plugin to CSI Driver Migration KEP](https://github.com/kubernetes/enhancements/issues/625) \ No newline at end of file