From: Jason Dillaman Date: Mon, 21 Dec 2020 19:40:13 +0000 (-0500) Subject: doc/rbd: incorporate external data source support for live-migration X-Git-Tag: v17.0.0~181^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=c2bf642ecf141753088eb3dbf88c65ab600268d5;p=ceph-ci.git doc/rbd: incorporate external data source support for live-migration Signed-off-by: Jason Dillaman --- diff --git a/doc/rbd/rbd-live-migration.rst b/doc/rbd/rbd-live-migration.rst index 10a80280ff3..a0ba991fd6c 100644 --- a/doc/rbd/rbd-live-migration.rst +++ b/doc/rbd/rbd-live-migration.rst @@ -4,20 +4,33 @@ .. index:: Ceph Block Device; live-migration -RBD images can be live-migrated between different pools within the same cluster -or between different image formats and layouts. When started, the source image -will be deep-copied to the destination image, pulling all snapshot history and -optionally preserving any link to the source image's parent to preserve -sparseness. - -This copy process can safely run in the background while the new target image is -in use. There is currently a requirement to temporarily stop using the source -image before preparing a migration. This helps to ensure that the client using -the image is updated to point to the new target image. +RBD images can be live-migrated between different pools within the same cluster; +between different image formats and layouts; or from external data sources. +When started, the source will be deep-copied to the destination image, pulling +all snapshot history while preserving the sparse allocation of data where +possible. + +By default, when live-migrating RBD images within the same Ceph cluster, the +source image will be marked read-only and all clients will instead redirect +IOs to the new target image. In addition, this mode can optionally preserve the +link to the source image's parent to preserve sparseness, or it can flatten the +image during the migration to remove the dependency on the source image's +parent. + +The live-migration process can also be used in an import-only mode where the +source image remains unmodified and the target image can be linked to an +external data source such as a backing file, HTTP(s) file, or S3 object. + +The live-migration copy process can safely run in the background while the new +target image is in use. There is currently a requirement to temporarily stop +using the source image before preparing a migration when not using the +import-only mode of operation. This helps to ensure that the client using the +image is updated to point to the new target image. .. note:: - Image live-migration requires the Ceph Nautilus release or later. The ``krbd`` - kernel module does not support live-migration at this time. + Image live-migration requires the Ceph Nautilus release or later. Support for + external data sources requires the Ceph Pacific release of later. The + ``krbd`` kernel module does not support live-migration at this time. .. ditaa:: @@ -36,11 +49,14 @@ the image is updated to point to the new target image. The live-migration process is comprised of three steps: #. **Prepare Migration:** The initial step creates the new target image and - cross-links the source and target images. Similar to `layered images`_, - attempts to read uninitialized extents within the target image will - internally redirect the read to the source image, and writes to - uninitialized extents within the target will internally deep-copy the - overlapping source image block to the target image. + links the target image to the source. When not configured in the import-only + mode, the source image will also be linked to the target image and marked + read-only. + + Similar to `layered images`_, attempts to read uninitialized data extents + within the target image will internally redirect the read to the source + image, and writes to uninitialized extents within the target will internally + deep-copy the overlapping source image block to the target image. #. **Execute Migration:** This is a background operation that deep-copies all @@ -51,14 +67,15 @@ The live-migration process is comprised of three steps: #. **Finish Migration:** Once the background migration process has completed, the migration can be committed or aborted. Committing the migration will remove the cross-links between the source and target images, and will - remove the source image. Aborting the migration will remove the cross-links, - and will remove the target image. + remove the source image if not configured in the import-only mode. Aborting + the migration will remove the cross-links, and will remove the target image. Prepare Migration ================= -The live-migration process is initiated by running the `rbd migration prepare` -command, providing the source and target images:: +The default live-migration process for images within the same Ceph cluster is +initiated by running the `rbd migration prepare` command, providing the source +and target images:: $ rbd migration prepare migration_source [migration_target] @@ -91,6 +108,183 @@ usage during the migration process:: 5e2cba2f62e migration_source +Prepare Import-Only Migration +============================= + +The import-only live-migration process is initiated by running the same +`rbd migration prepare` command, but adding the `--import-only` optional +and providing a JSON-encoded ``source-spec`` to describe how to access +the source image data. This ``source-spec`` can either be passed +directly via the `--source-spec` optional, or via a file or STDIN via the +`--source-spec-file` optional:: + + $ rbd migration prepare --import-only --source-spec "" migration_target + +The `rbd migration prepare` command accepts all the same layout optionals as the +`rbd create` command. + +The `rbd status` command will show the current state of the live-migration:: + + $ rbd status migration_target + Watchers: none + Migration: + source: {"stream":{"file_path":"/mnt/image.raw","type":"file"},"type":"raw"} + destination: rbd/migration_target (ac69113dc1d7) + state: prepared + +The general format for the ``source-spec`` JSON is as follows:: + + { + "type": "", + + "stream": { + "type": "", + + } + } + +The following formats are currently supported: ``native`` and ``raw``. The +following streams are currently supported: ``file``, ``http``, and ``s3``. + +Formats +~~~~~~~ + +The ``native`` format can be used to describe a native RBD image within a +Ceph cluster as the source image. Its ``source-spec`` JSON is encoded +as follows:: + + { + "type": "native", + "pool_name": "", + ["pool_id": ,] (optional alternative to "pool_name") + ["pool_namespace": "", + ["image_id": "",] (optional if image in trash) + "snap_name": "", + ["snap_id": "",] (optional alternative to "snap_name") + } + +Note that the ``native`` format does not include the ``stream`` object since +it utilizes native Ceph operations. For example, to import from the image +``rbd/ns1/image1@snap1``, the ``source-spec`` could be encoded as:: + + { + "type": "native", + "pool_name": "rbd", + "pool_namespace": "ns1", + "image_name": "image1", + "snap_name": "snap1" + } + +The ``raw`` format can be used to describe a thick-provisioned, raw block device +export (i.e. `rbd export --export-format 1 `). The ``raw`` format +data can be linked to any supported stream source described below. For example, +its base ``source-spec`` JSON is encoded as follows:: + + { + "type": "raw", + "stream": { + + }, + "snapshots": [ + { + "type": "raw", + "name": "", + "stream": { + + } + }, + ] (optional oldest to newest ordering of snapshots) + } + +The inclusion of the ``snapshots`` array is optional and currently only supports +thick-provisioned ``raw`` snapshot exports. + +Additional formats such as QCOW2, RBD export-format v2, and RBD export-diff +snapshots will be added in a future release. + +Streams +~~~~~~~ + +The ``file`` stream can be used to import from a locally accessible POSIX file +source. Its ``source-spec`` JSON is encoded as follows:: + + { + + "stream": { + "type": "file", + "file_path": "" + } + } + +For example, to import a raw-format image from a file located at +"/mnt/image.raw", its ``source-spec`` JSON is encoded as follows:: + + { + "type": "raw", + "stream": { + "type": "file", + "file_path": "/mnt/image.raw" + } + } + +The ``http`` stream can be used to import from a remote HTTP or HTTPS web +server. Its ``source-spec`` JSON is encoded as follows:: + + { + + "stream": { + "type": "http", + "url": "" + } + } + +For example, to import a raw-format image from a file located at +``http://download.ceph.com/image.raw``, its ``source-spec`` JSON is encoded +as follows:: + + { + "type": "raw", + "stream": { + "type": "http", + "url": "http://download.ceph.com/image.raw" + } + } + +The ``s3`` stream can be used to import from a remote S3 bucket. Its +``source-spec`` JSON is encoded as follows:: + + { + + "stream": { + "type": "s3", + "url": "", + "access_key": "", + "secret_key": "" + } + } + +For example, to import a raw-format image from a file located at +`http://s3.ceph.com/bucket/image.raw`, its ``source-spec`` JSON is encoded +as follows:: + + { + "type": "raw", + "stream": { + "type": "s3", + "url": "http://s3.ceph.com/bucket/image.raw", + "access_key": "NX5QOQKC6BH2IDN8HC7A", + "secret_key": "LnEsqNNqZIpkzauboDcLXLcYaWwLQ3Kop0zAnKIn" + } + } + +.. note:: + The ``access_key`` and ``secret_key`` parameters support storing the keys in + the MON config-key store by prefixing the key values with ``config://`` + followed by the path in the MON config-key store to the value. Values can be + stored in the config-key store via ``ceph config-key set `` + (e.g. ``ceph config-key set rbd/s3/access_key NX5QOQKC6BH2IDN8HC7A``). + Execute Migration =================