Project

General

Profile

Bug #53125

[doc] --pool is deprecated for import command

Added by Sofia Enriquez over 2 years ago. Updated about 2 years ago.

Status:
Need More Info
Priority:
Normal
Assignee:
Target version:
-
% Done:

0%

Source:
Tags:
Backport:
Regression:
No
Severity:
3 - minor
Reviewed:
Affected Versions:
ceph-qa-suite:
Pull request ID:
Crash signature (v1):
Crash signature (v2):

Description

Greetings,
While using the import command, I'm facing the next warning message 'rbd: -p [ --pool ] is deprecated, use --dest-pool'. However, the documentation still recommends the use of --pool [1].
Should the documentation be updated?
Regards

[1 ]https://docs.ceph.com/en/pacific/man/8/rbd/

@devstack$ rbd help import
usage: rbd import [--path <path>] [--dest-pool <dest-pool>]
[--dest-namespace <dest-namespace>] [--dest <dest>]
[--image-format <image-format>] [--new-format]
[--order <order>] [--object-size <object-size>]
[--image-feature <image-feature>] [--image-shared]
[--stripe-unit <stripe-unit>]
[--stripe-count <stripe-count>] [--data-pool <data-pool>]
[--mirror-image-mode <mirror-image-mode>]
[--journal-splay-width <journal-splay-width>]
[--journal-object-size <journal-object-size>]
[--journal-pool <journal-pool>]
[--sparse-size <sparse-size>] [--no-progress]
[--export-format <export-format>] [--pool <pool>]
[--image <image>]
<path-name> <dest-image-spec>

Import image from file.

Optional arguments
--path arg import file (or '-' for stdin)
--dest-pool arg destination pool name

devstack$ ceph --version
ceph version 16.2.6 (ee28fb57e47e9f88813e24bbf4c14496ca299d31) pacific (stable)@

History

#1 Updated by Neha Ojha over 2 years ago

  • Project changed from Ceph to rbd

#2 Updated by Ilya Dryomov about 2 years ago

  • Status changed from New to Need More Info
  • Assignee set to Ilya Dryomov

Hi Sofia,

I don't see where https://docs.ceph.com/en/pacific/man/8/rbd/ recommends to use -p/--pool for "rbd import".

In the beginning it says

-p pool-name, --pool pool-name
Interact with the given pool. Required by most commands.

and that is true. "rbd import" is one of the few exceptions.

The entry for "rbd import" says

import [–export-format format (1 or 2)] [–image-format format-id] [–object-size size-in-B/K/M] [–stripe-unit size-in-B/K/M –stripe-count num] [–image-feature feature-name]… [–image-shared] src-path [image-spec]

Note that it ends with image-spec. And below, the "Image, snap, group and journal specs" section says
image-spec is [pool-name/[namespace-name/]]image-name
...
You may specify each name individually, using --pool, --namespace, --image, and --snap options, but this is discouraged in favor of the above spec syntax.

Could you please point me at the paragraph that needs to be updated?

#3 Updated by Brian Rosmaita about 2 years ago

Hi Ilya,

I think the problem is that the rbd CLI gives you a deprecation notice when you use --pool (see the output Sofia posted above) and says that --dest-pool is preferred, but if you search https://docs.ceph.com/en/pacific/man/8/rbd/ , the string 'dest-pool' is not found. There are a few questions the docs don't answer:

1. --pool is deprecated, is there a removal schedule?

2. Is --pool deprecated completely (that is, for all 'rbd' subcommands), or is it deprecated specifically for use with the 'rbd import' command?

3. As you pointed out, the documentation for 'image-spec' currently say: "You may specify each name individually, using --pool, --namespace, --image, and --snap options, but this is discouraged in favor of the above spec syntax." Although the docs don't state this, the CLI output for 'rbd help import' implies that we should be using "--dest-pool" and not "--pool", but the "this is discouraged" statement makes it sound like "--dest-pool" may also be deprecated. In other words, how strongly is using --pool, --namespace, --image discouraged?

Hope this helps!

#4 Updated by Ilya Dryomov about 2 years ago

Brian Rosmaita wrote:

Hi Ilya,

I think the problem is that the rbd CLI gives you a deprecation notice when you use --pool (see the output Sofia posted above) and says that --dest-pool is preferred, but if you search https://docs.ceph.com/en/pacific/man/8/rbd/ , the string 'dest-pool' is not found. There are a few questions the docs don't answer:

1. --pool is deprecated, is there a removal schedule?

Hi Brian,

No, there is no removal schedule.

2. Is --pool deprecated completely (that is, for all 'rbd' subcommands), or is it deprecated specifically for use with the 'rbd import' command?

Just for "rbd import" command.

3. As you pointed out, the documentation for 'image-spec' currently say: "You may specify each name individually, using --pool, --namespace, --image, and --snap options, but this is discouraged in favor of the above spec syntax." Although the docs don't state this, the CLI output for 'rbd help import' implies that we should be using "--dest-pool" and not "--pool", but the "this is discouraged" statement makes it sound like "--dest-pool" may also be deprecated. In other words, how strongly is using --pool, --namespace, --image discouraged?

--dest-pool is specific to "rbd import" and a couple of other commands. For the vast majority of commands, it's --pool.

The option syntax (--pool, --namespace, etc or --dest-pool, --dest-namespace, etc for "rbd import") isn't going away. The spec syntax is just more compact and subjectively nicer to use.

Also available in: Atom PDF