Managing namespaces

Edit online

As a system administrator, you can manage NVMe-oF subsystem namespaces by using the command-line interface (CLI). Use this information to add, delete, resize, and list namespaces. You can also get I/O statistics, change load-balancing groups, and set QoS limits for namespaces.

Before you begin

Managing NVMe-oF subsystem namespaces with the CLI requires the nvmeof-cli alias setup. For more information about defining the alias, see step 1 of Defining an NVMe-oF subsystem.

About this task

At any point, you can use the -h or --help parameters for command help.
The following parameters are interchangeable:
  • --subsystem and -n
  • --uuid and -u
  • --rpd-pool and -p
  • --rbd-image and -i
  • --rbd-create-image and -c
  • --block-size and -s
  • --load-balancing-group and -l
Use the commands listed here to manage your namespaces.

Adding a namespace

Edit online
Use the namespace add command to add a namespace to an NVMe-oF subsystem.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace add --subsystem SUBSYSTEM_NQN --rbd-pool POOL_NAME --rbd-image IMAGE_NAME
For example,
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1 --rbd-pool pool1 --rbd-image image1
The following parameters can optionally be added to the command:
--UUID
Enter the UUID of the subsystem.
Note: This parameter is optional. Do not use together with --nsid.
--NSID
Enter the namespace ID of the subsystem.
Note: This parameter is optional. Do not use together with --uuid.
--block-size
Enter the namespace block size.
--load-balancing-group
Add the --load-balancing-group parameter name to force the default active gateway to use this namespace. Automatic load-balancing makes sure that each namespace receives an assigned load-balancing group. For more information about manual load balancing, see Managing load balancing with scale-up and scale-down.

During a namespace addition, a load-balancing group is automatically assigned to the NVMe-oF namespace with any available NVMe-oF gateway load-balancing group.

--size
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.
--rbd-create-image

Create an image within any RADOS Block Device (RBD) application-enabled pool.

--force
Use the --force parameter to create a namespace even if its image is already used by another namespace.

Examples

  • Create a RADOS Block Device (RBD) application-enabled pool.
    [root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1 --rbd-pool pool1 --rbd-create-image --rbd-image image1 --size 1024
  • Add a namespace with an already created RADOS Block Device (RBD) image in pool.
    [root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1 --rbd-image image1 --rbd-pool rbd --nsid 1
  • Simultaneously allocate a load balancing group and adding a namespace.
    Note: For changing a load balancing group for an existing namespace, see Changing load balancing groups.
    [root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1 --rbd-image image1 --rbd-pool rbd --nsid 1 --load-balancing-group 1
    It is recommended to allow the NVMe-oF gateway to set the active gateway automatically, and not to force the namespace. The gateway load-balancing group ID of a gateway can be retrieved at any time by running the gw info command. For example:
    nvmeof-cli gw info --server-address NODE_IP
    nvmeof-cli --server-address NODE_IP --server-port SERVER_PORT namespace add --subsystem SUBSYSTEM_NQN --rbd-pool RBD_POOL --rbd-image RBD_IMAGE
    Note: For more information see, Expanding a block device image.

Listing namespaces

Edit online
Use the namespace list command to list namespaces of an NVMe-oF subsystem.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace list --subsystem SUBSYSTEM [--uuid UUID|--nsid NSID]
The following is an example output for two namespaces on a subsystem.
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace list --subsystem nqn.2016-06.io.spdk:cnode1
Namespaces in subsystem nqn.2016-06.io.spdk:cnode1:
NSID| Bdev                    | RBD   | RBD    | Image    | Block | UUID                | Load            | R/W IOs    | R/W MB     | Read MBs   | Write MBs
    | Name                    | Pool  | Image  | Size     | Size  |                     | Balancing Group | per second | per second | per second | per second    
==============================================================================================================================================================
1   | bdev-32c94dd8-8754-     | pool1 | image1 | 1024 MiB | 512 B | 32c94dd8-8754-442f- | 2               | unlimited  | unlimited  | unlimited  | unlimited  
    | 442f-a12c-123abc456789  |       |        |          |       | a12c-123abc456789   |                 |            |            |            |            
--------------------------------------------------------------------------------------------------------------------------------------------------------------
2   | bdev-45c94ee8-ab56-     | pool1 | image2 | 1024 MiB | 512 B | 45c94ee8-ab56-332f- | 1               | unlimited  | unlimited  | unlimited  | unlimited  
    | 332f-a24c-abc123ae7890  |       |        |          |       | a24c-abc123ae7890   |                 |            |            |            |
The following parameters can optionally be added to the command:
--UUID
Enter the UUID of the subsystem.
Note: This parameter is optional. Do not use together with --nsid.
--NSID
Enter the namespace ID of the subsystem.
Note: This parameter is optional. Do not use together with --uuid.

Deleting a namespace

Edit online
Use the namespace del command to delete a namespace from an NVMe-oF subsystem.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace del --subsystem SUBSYSTEM_NQN [--uuid UUID|--nsid NSID]

Use either the --uuid or --nsid parameters

For example,
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace del --subsystem nqn.2016-06.io.spdk:cnode1 --nsid 1

Resizing a namespace

Edit online
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.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace resize --subsystem SUBSYSTEM [--uuid UUID | --nsid NSID] --size SIZE

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 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace resize --subsystem nqn.2016-06.io.spdk:cnode1 --nsid 2 --size 1536
In this example, the size of NSID 2 on the nqn.2016-06.io.spdk:cnode1 subsystem is being increased to 1536 bytes.

Getting I/O statistics

Edit online
Use the namespace get_io_stats command to retrieve I/O statistics for a namespace on a subsystem.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace get_io_stats --subsystem SUBSYSTEM_NQN [--uuid UUID|--nsid NSID]
For example,
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace get_io_stats --subsystem nqn.2016-06.io.spdk:cnode1 --nsid 1

Changing load balancing groups

Edit online
Use the change_load_balancing_group command to change the load balancing group for an existing namespace.
Note: To specify the load balance group while creating a namespace, see Adding a namespace.
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT change_load_balancing_group --subsystem SUBSYSTEM [--uuid UUID | --nsid NSID] --load-balancing-group LOAD_BALANCING_GROUP
For example,
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 change_load_balancing_group --subsystem nqn.2016-06.io.spdk:cnode1 --nsid 1 --load-balancing-group 2
It is recommended to allow the NVMe-oF gateway to set the active gateway automatically, and not to force the namespace. The gateway load-balancing group ID of a gateway can be retrieved at any time by running the gw info command. For example:
nvmeof-cli gw info --server-address NODE_IP
nvmeof-cli --server-address NODE_IP --server-port SERVER_PORT namespace add --subsystem SUBSYSTEM_NQN --rbd-pool RBD_POOL --rbd-image RBD_IMAGE
Note: For more information see, Expanding a block device image.