1
0
mirror of https://github.com/ceph/ceph-csi.git synced 2024-12-18 19:10:21 +00:00

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 <hchiramm@redhat.com>
This commit is contained in:
Humble Chirammal 2021-11-02 17:28:14 +05:30 committed by mergify[bot]
parent 3686b6da8b
commit 5a4bf4d151

View File

@ -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 <<<
"<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](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)