Chapter 4. Pools

To manage pools, you can list, create, and remove pools. You can also view the utilization statistics for each pool.

To list your cluster’s pools, execute:

ceph osd lspools

Before creating pools, see the Pool, PG and CRUSH Configuration Reference chapter in the Configuration Guide for Red Hat Ceph Storage 3.

It is better to adjust the default value for the number of placement groups in the Ceph configuration file, as the default value does not have to suit your needs. For example:

osd pool default pg num = 100
osd pool default pgp num = 100

To create a replicated pool, execute:

ceph osd pool create <pool-name> <pg-num> <pgp-num> [replicated] \
         [crush-rule-name] [expected-num-objects]

To create an erasure-coded pool, execute:

ceph osd pool create <pool-name> <pg-num> <pgp-num> erasure \
         [erasure-code-profile] [crush-rule-name] [expected-num-objects]

Where:

When you create a pool, set the number of placement groups to a reasonable value (for example to 100). Consider the total number of placement groups per OSD too. Placement groups are computationally expensive, so performance will degrade when you have many pools with many placement groups, for example, 50 pools with 100 placement groups each. The point of diminishing returns depends upon the power of the OSD host.

See the Placement Groups section and Ceph Placement Groups (PGs) per Pool Calculator for details on calculating an appropriate number of placement groups for your pool.

You can set pool quotas for the maximum number of bytes or the maximum number of objects per pool or for both.

ceph osd pool set-quota <pool-name> [max_objects <obj-count>] [max_bytes <bytes>]

For example:

ceph osd pool set-quota data max_objects 10000

To remove a quota, set its value to 0.

To delete a pool, execute:

ceph osd pool delete <pool-name> [<pool-name> --yes-i-really-really-mean-it]

If a pool has its own rule, consider removing it after deleting the pool. If a pool has users strictly for its own use, consider deleting those users after deleting the pool.

To rename a pool, execute:

ceph osd pool rename <current-pool-name> <new-pool-name>

If you rename a pool and you have per-pool capabilities for an authenticated user, you must update the user’s capabilities (i.e., caps) with the new pool name.

To show a pool’s utilization statistics, execute:

rados df

To make a snapshot of a pool, execute:

ceph osd pool mksnap <pool-name> <snap-name>

To remove a snapshot of a pool, execute:

ceph osd pool rmsnap <pool-name> <snap-name>

To set a value to a pool, execute the following command:

ceph osd pool set <pool-name> <key> <value>

The Pool Values section lists all key-values pairs that you can set.

To get a value from a pool, execute the following command:

ceph osd pool get <pool-name> <key>

The Pool Values section lists all key-values pairs that you can get.

RHCS 3 and later releases provide additional protection for pools to prevent unauthorized types of clients from writing data to the pool. This means that system administrators must expressly enable pools to receive I/O operations from Ceph Block Device, Ceph Object Gateway, Ceph Filesystem or for a custom application.

To enable a client application to conduct I/O operations on a pool, execute the following:

[root@host ~]# ceph osd pool application enable <poolname> <app> {--yes-i-really-mean-it}

Where <app> is:

{
    "checks": {
        "POOL_APP_NOT_ENABLED": {
            "severity": "HEALTH_WARN",
            "summary": {
                "message": "application not enabled on 1 pool(s)"
            },
            "detail": [
                {
                    "message": "application not enabled on pool '<pool-name>'"
                },
                {
                    "message": "use 'ceph osd pool application enable <pool-name> <app-name>', where <app-name> is 'cephfs', 'rbd', 'rgw', or freeform for custom applications."
                }
            ]
        }
    },
    "status": "HEALTH_WARN",
    "overall_status": "HEALTH_WARN",
    "detail": [
        "'ceph health' JSON format has changed in luminous. If you see this your monitoring system is scraping the wrong fields. Disable this with 'mon health preluminous compat warning = false'"
    ]
}

To disable a client application from conducting I/O operations on a pool, execute the following:

[root@host ~]# ceph osd pool application disable <poolname> <app> {--yes-i-really-mean-it}

Where <app> is:

RHCS 3 and later releases provide functionality to set key-value pairs describing attributes of the client application.

To set client application metadata on a pool, execute the following:

[root@host ~]# ceph osd pool application set <poolname> <app> <key> <value>

Where <app> is:

To remove client application metadata on a pool, execute the following:

[root@host ~]# ceph osd pool application set <poolname> <app> <key>

Where <app> is:

To set the number of object replicas on a replicated pool, execute the following command:

ceph osd pool set <poolname> size <num-replicas>

For example:

ceph osd pool set data size 3

You can execute this command for each pool.

ceph osd pool set data min_size 2

To get the number of object replicas, execute the following command:

ceph osd dump | grep 'replicated size'

Ceph will list the pools, with the replicated size attribute highlighted. By default, Ceph creates two replicas of an object, that is a total of three copies, or a size of 3.

The following list contains key-values pairs that you can set or get. For further information, see the Set Pool Values and Get Pool Values sections.

nodeep-scrub