Managing namespaces

As a system administrator, you can manage NVMe-oF subsystem namespaces by using ceph nvmeof commands. Use this information to add, delete, resize, and list namespaces. You can also get I/O statistics, change load-balancing groups, and set Quality of Service (QoS) limits for namespaces.

About this task

Use this information to manage namespaces with no masking. To manage masked namespaces, use the commands that are detailed in Managing masked namespaces with nvmeof-cli.

Namespace location and placement control in stretch cluster deployments are described in Managing namespace placement.

Namespaces are automatically load balanced across gateways in a gateway group during namespace addition and namespace deletion. For more information about load balancing, see Using load balancing with scale-up and scale-down with nvmeof-cli.

Important: Namespaces might not be visible if an initiator is connected to two different gateway groups with the same NQN.

Adding a namespace

Use the namespace add command to add a namespace to an NVMe-oF subsystem.

ceph nvmeof namespace add --nqn NQN [--rbd_image_name IMAGE_NAME] [--rbd_pool POOL_NAME] [--create-image] [--size POOL_SIZE] [--rbd_image_size IMAGE_SIZE] [--location LOCATION] [--rados_namespace RADOS_NAMESPACE]

For example,

[root@host01 ~]# ceph nvmeof namespace add --nqn nqn.2016-06.io.spdk:cnode1.group1 --rbd_pool pool1 --rbd_image_name image1 --location DC2
Success

Note: Use the --location parameter for stretch-clusters. For more information, see NVMe-oF in a stretch cluster.

You can optionally add the following parameters to the command:

--uuid
block_size<int>
--nsid
--block_size<int>
--size
--create-image
--force
Use the --force parameter to create a namespace even if its image is already used by another namespace.
--rbd-trash-image-on-delete
Instructs the gateway to automatically delete the Ceph Block Device (RBD) image that is created for the namespace when the namespace is deleted.
--force
Use the --force parameter to create a namespace even if its image is already used by another namespace.

This parameter only applies to Ceph Block Device images created when adding a namespace. If the namespace was added by using an existing Ceph Block Device image, this image will not be deleted with the namespace.
Note: The --rbd-trash-image-on-delete parameter can only be used together with the --create-image parameter.
--no-auto-visible
Makes the namespace visible only to specific hosts. For more information and instructions, see Managing masked namespaces.
--read-only
Use to create a namespace that cannot be modified. Use read-only namespaces to prevent namespace changes during operations such as during disaster recovery tests. The Read-Only or Read-Write status can be seen in the namespace list output.
Important: Once a namespace is flagged as read-only it cannot be modified to read-write.
--rados-namespace
Specifies the RADOS namespace within the pool where the Ceph Block Device image is created. Use RADOS namespaces with NVMe-oF gateways to isolate Ceph Block Device (RBD) images within a pool for multitenancy and improved scalability.
Note: The RADOS namespace must already exist.
```
rbd namespace create POOL_NAME/RADOS_NAMESPACE
```
For more information about Ceph Block Device namespaces, see Managing Ceph Block Device namespaces.

Examples

Add a namespace while creating a Ceph Block Device (RBD) image and pool, while setting the image to automatically delete during the namespace deletion.

[root@host01 ~]# ceph nvmeof namespace add --nqn nqn.2016-06.io.spdk:cnode1.group1 --rbd_image image1 --rbd_pool pool1 --create-image --rbd-trash-image-on-delete

Add a namespace with an already created Ceph Block Device (RBD) image in pool.

[root@host01 ~]# ceph nvmeof namespace add --nqn nqn.2016-06.io.spdk:cnode1.group1 --rbd_image image1 --rbd_pool pool1
Success

Add a namespace using an existing RADOS namespace.

[root@host01 ~]# ceph nvmeof namespace add --nqn nqn.2016-06.io.spdk:cnode1.group1 --rbd_pool pool1 --create-image --size 100MB --rados-namespace rbd_namespace
Success

Listing namespaces for a specific NVMe-oF subsystem

Use the namespace list command to list namespaces of an NVMe-oF subsystem.

ceph nvmeof namespace list --nqn NQN [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]

The following is an example output for two namespaces on a subsystem.

[root@host01 ~]# ceph nvmeof namespace list --nqn nqn.2016-06.io.spdk:cnode1.group1
+-----------------------------------------+----------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+
|Bdev Name                                |Rbd Image |Rbd Pool|Lb Group|Rbd Image Size|Block Size|R/W Ios/Sec|R/W Mbs/Sec|Read Mbs/Sec|Write Mbs/Sec|Auto Visible|Hosts|Nsid|Uuid                                |Ns Subsystem Nqn                   |Trash Image|Disable Auto Resize|Read Only|
+-----------------------------------------+----------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+
|bdev_19040e4a-7d18-4e7c-80f1-db9fb98af602|myimage1  |mypool  |4       |200MB         |512B      |0          |0          |0           |0            |True        |[]   |1   |19040e4a-7d18-4e7c-80f1-db9fb98af602|nqn.2016-06.io.spdk:cnode1.mygroup1|False      |False              |False    |
|bdev_a0917249-5306-40c3-943c-20a5d19cd88b|myimage2  |mypool  |3       |200MB         |512B      |0          |0          |0           |0            |True        |[]   |2   |a0917249-5306-40c3-943c-20a5d19cd88b|nqn.2016-06.io.spdk:cnode1.mygroup1|False      |False              |False    |
|bdev_6d92f36a-dd95-481e-b99d-2f776bf868f1|myimage3  |mypool  |2       |200MB         |512B      |0          |0          |0           |0            |True        |[]   |3   |6d92f36a-dd95-481e-b99d-2f776bf868f1|nqn.2016-06.io.spdk:cnode1.mygroup1|False      |False              |False    |
|bdev_f98ebcce-8475-494e-b2e2-e9e2f60fce5d|myimage4  |mypool  |1       |200MB         |512B      |0          |0          |0           |0            |True        |[]   |4   |f98ebcce-8475-494e-b2e2-e9e2f60fce5d|nqn.2016-06.io.spdk:cnode1.mygroup1|False      |False              |False    |
+-----------------------------------------+----------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+

You can optionally add the following parameters to the command:

--uuid
--nsid

Listing namespaces for all NVMe-oF subsystems

Use the namespace list command to list namespaces from all connected NVMe-oF subsystems. To list all relevant namespaces from all subsystems, omit the --nqn parameter, or enter "*".

ceph nvmeof namespace list

You can optionally add the following parameters to the command:

--uuid
--nsid

Deleting a namespace

Use the namespace del_host command to delete a namespace from an NVMe-oF subsystem.

ceph nvmeof namespace del_host --nqn NQN --nsid NSID --host_nqn HOST_NQN [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS] [--i-am-sure]

The --i-am-sure parameter must be used when the namespace is set with --rbd-trash-image-on-delete.

Important: If the automatic deletion for Ceph Block Device (RBD) images on the namespace is set and the --i-am-sure parameter is not used the command fails.

For example,

[root@host01 ~]# ceph nvmeof namespace del_host --nqn nqn.2016-06.io.spdk:cnode1.group1 --nsid 1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3
Success

Resizing a namespace

Important: A block device image can be expanded but not reduced.

Use the namespace resize command to increase the size of a namespace.

For more information, see Expanding a block device image with nvmeof-cli.

ceph nvmeof namespace resize --nqn NQN --nsid NSID [--rbd_image_size IMAGE_SIZE] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]

The size is indicated in bytes, by default. To indicate a different size type, specify the unit. The supported size units are: KB, KiB, MB, MiB, GB, GiB, TB, and TiB.

For example,

[root@host01 ~]# ceph nvmeof namespace resize --nqn nqn.2016-06.io.spdk:cnode1.group1 --nsid 2 --rbd_image_size 1536
Success

In this example, the size of NSID 2 on the nqn.2016-06.io.spdk:cnode1.group1 subsystem is being increased to 1536 bytes.

Setting namespace automatic resizing

Enable or disable namespace automatic resizing of a namespace when a Ceph Block Device is resized.

Important: A block device image can be expanded but not reduced.

Use the set_auto_resize command to automatically resize a namespace when a Ceph Block Device image is resized.

For more information, see Expanding a block device image with nvmeof-cli.

ceph nvmeof namespace set_auto_resize --nqn NQN --nsid NSID --auto-resize-enabled <yes|no|true|false|1|0> [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]

Use either --auto-resize-enabled parameter to enable or disable the automatic resizing.

To enable automatic resizing, set with any of the following value inputs:
yes, true, or 1

For example, --auto-resize-enabled yes.

Note: When you use the --auto-resize-enabled option without specifying a value, the system assumes the default value of yes.
To disable automatic resizing, set with any of the following value inputs:
no, false, or 0

For example, --auto-resize-enabled no.

For example,

[root@host01 ~]# ceph nvmeof namespace set_auto_resize --nqn nqn.2016-06.io.spdk:cnode1.group1 --nsid 2 --auto-resize-enabled yes
Success

In this example, the nqn.2016-06.io.spdk:cnode1.group1 subsystem with NSID 2 is now enabled for automatic resizing.

Updating a namespace

Update an existing namespace, by using the namespace update command.

ceph nvmeof namespace update --nqn NQN [--nsid NSID] [--rbd_image_size IMAGE_SIZE] [--load_balancing_group LOAD_BALANCING_GROUP] [--rw_ios_per_second RW_IOS_PER_SECOND] [--rw_mbytes-per_second RW_MBYTES_PER_SECOND] [--r_mbytes-per_second READ_MBYTES_PER_SECOND] [--w_mbytes-per_second WRITE_MBYTES_PER_SECOND] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS] [--location LOCATION] [--trash-image]

For example,

[root@host01 ~]# ceph nvmeof namespace update --nqn nqn.2016-06.io.spdk:cnode1.group1 --nsid 1 --load_balancing_group 2
+-----------------------------------------+---------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+
|Bdev Name                                |Rbd Image|Rbd Pool|Lb Group|Rbd Image Size|Block Size|R/W Ios/Sec|R/W Mbs/Sec|Read Mbs/Sec|Write Mbs/Sec|Auto Visible|Hosts|Nsid|Uuid                                |Ns Subsystem Nqn                   |Trash Image|Disable Auto Resize|Read Only|
+-----------------------------------------+---------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+
|bdev_19040e4a-7d18-4e7c-80f1-db9fb98af602|myimage1 |mypool  |4       |200MB         |512B      |0          |0          |0           |0            |True        |[]   |1   |19040e4a-7d18-4e7c-80f1-db9fb98af602|nqn.2016-06.io.spdk:cnode1.mygroup1|False      |False              |False    |
+-----------------------------------------+---------+--------+--------+--------------+----------+-----------+-----------+------------+-------------+------------+-----+----+------------------------------------+-----------------------------------+-----------+-------------------+---------+

Getting I/O statistics

Use the namespace get_io_stats command to retrieve I/O statistics for a namespace on a subsystem.

ceph nvmeof namespace get_io_stats --nqn NQN [--nsid NSID] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]

For example,

[root@host01 ~]# ceph nvmeof namespace get_io_stats -nqn nqn.2016-06.io.spdk:cnode1.group1 --nsid 1
 +-----------------------------------+----+------------------------------------+-----------------------------------------+----------+---------------+----------+------------+-------------+-------------+--------------+-------------+------------------+----------------------+----------------------+-------------------+-----------------------+-----------------------+-------------------+-----------------------+-----------------------+------------------+----------------------+----------------------+--------+
|Subsystem Nqn                      |Nsid|Uuid                                |Bdev Name                                |Tick Rate |Ticks          |Bytes Read|Num Read Ops|Bytes Written|Num Write Ops|Bytes Unmapped|Num Unmap Ops|Read Latency Ticks|Max Read Latency Ticks|Min Read Latency Ticks|Write Latency Ticks|Max Write Latency Ticks|Min Write Latency Ticks|Unmap Latency Ticks|Max Unmap Latency Ticks|Min Unmap Latency Ticks|Copy Latency Ticks|Max Copy Latency Ticks|Min Copy Latency Ticks|Io Error|
+-----------------------------------+----+------------------------------------+-----------------------------------------+----------+---------------+----------+------------+-------------+-------------+--------------+-------------+------------------+----------------------+----------------------+-------------------+-----------------------+-----------------------+-------------------+-----------------------+-----------------------+------------------+----------------------+----------------------+--------+
|nqn.2016-06.io.spdk:cnode1.mygroup1|1   |19040e4a-7d18-4e7c-80f1-db9fb98af602|bdev_19040e4a-7d18-4e7c-80f1-db9fb98af602|2394300000|112116916620990|36.5KB    |3           |0B           |0            |0B            |0            |3557188           |1263188               |1098754               |0                  |0                      |0                      |0                  |0                      |0                      |0                 |0                     |0                     |[]      |
+-----------------------------------+----+------------------------------------+-----------------------------------------+----------+---------------+----------+------------+-------------+-------------+--------------+-------------+------------------+----------------------+----------------------+-------------------+-----------------------+-----------------------+-------------------+-----------------------+-----------------------+------------------+----------------------+----------------------+--------+

Changing the Ceph Block Device image delete policy for during a namespace deletion

If the Ceph Block Device (RBD) image was set to delete with a namespace, use the command namespace set_rbd_trash_image to keep it after the namespace deletion. Use this command to change an image that was created by using the --create-image parameter during the namespace creation.

The image status for automatic deletion can be changed at any time, until the namespace is deleted, only if the namespace was created with the --trash-image parameter. For more information, see Adding a namespace.

ceph nvmeof namespace set_rbd_trash_image --nqn NQN --nsid NSID --rbd-trash-image-on-delete <yes|no> [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]

Set the --rbd-trash-image-on-delete option to yes to set automatic image deletion and set to no to remove automatic deletion, keeping the image after deleting the namespace.