Skip to content

Instantly share code, notes, and snippets.

@yuvalif

yuvalif/radosgw-admin-gsoc-26.md

Last active February 27, 2026 16:04
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save yuvalif/4a077cef5063653f337337c9ca08094e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save yuvalif/4a077cef5063653f337337c9ca08094e to your computer and use it in GitHub Desktop.
Download ZIP
Raw
radosgw-admin-gsoc-26.md

radosgw-admin UX and documentation improvements

Background

Currently, documenting radosgw-admin commands is a manual and error-prone process. After implementing a new command, the "usage" string should be updated accordingly in the code, where there could be a mismatch between the actually command and its arguments and what is documented in the usage. After that the man page needs to be updated manually, as well as the admin guide. Any references to this command in other places in our documentation also need to be manually updated.

We would like to solve this program with a more programmatic approach:

  • Declare command & argument semantics explicitly in code using a cli/args framework that supports auto-generation of context-aware "usage" docs
  • Investigate how this can then be used to auto-generate the man page, admin guides and any other related documentation (maybe using some python code)
  • See if we can easily reference these command descriptions in other places in our documentation
  • All while maintaining backward compatibility with the existing behavior
  • Some more information is available on this issue.

Evaluation Stage

Step 1 - Build Ceph and Run Basic Test

First would be to have a Linux-based development environment. As a minimum you would need a 4-core CPU, with 8G RAM and 50GB of available disk space. Unless you already have a Linux distro you like, I would recommend choosing from:

  • Fedora (42/43) - my favorite!
  • Ubuntu (24.04 LTS)
  • WSL (Windows Subsystem for Linux), though it would probably take much longer...
  • RHEL9/Centos9
  • Other Linux distros - try at your own risk :-)

Once you have that up and running, you should clone the Ceph repo from github. If you don't know what github and git are, this is the right time to close these gaps :-) You should also have a github account, so you can later share your work on the project.

Before building, you can install any missing system dependencies with:

./install-deps.sh

Note that the first build may take a long time, so the following cmake parameters could be used to minimize the build time. With a fresh ceph clone use the following:

./do_cmake.sh -DBOOST_J=$(nproc) -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DWITH_MGR_DASHBOARD_FRONTEND=OFF \
  -DWITH_DPDK=OFF -DWITH_SPDK=OFF -DWITH_SEASTAR=OFF -DWITH_CEPHFS=OFF -DWITH_RBD=OFF -DWITH_KRBD=OFF -DWITH_CCACHE=OFF -DNinja

Then invoke the build process (using ninja) from within the build directory (created by do_cmake.sh). Assuming the build was completed successfully, you can run the unit tests.

Now you are ready to run the ceph processes, as explained in the Ceph project README. You probably would also like to check the developer guide and learn more on how to build Ceph and run it locally.

Now it is time to play around a little with the radosgw-admin commandline tool:

  • Create a bucket using standard tools like the aws CLI or s3cmd which would be owned by the default user created as part of vstart
  • Upload objects to that bucket
  • Create a new user using radosgw-admin
  • Modify bucket ownership to the new user using radosgw-admin
  • Use radosgw-admin to get bucket stats and verify that ownership changed
  • Try to upload an object using the default credentials and verify it fails
  • Verify that using the credentials of the new user allows you to upload object to the bucket

If you run into issues with step 1, please use the rgw-devel slack channel for help (you can find details of the Ceph slack workspace on the Ceph website).

Step 2

In this step, please try to find mismatches (e.g. missing commands, missing parameters) between these:

  • the radosgw-admin code
  • the "usage" message (i.e. what is printed to the screen with radosgw-admin -h
  • the radosgw-admin man page

If you wish, you may also try to fix some of the issues that you find in a PR.

In your proposal, please provide a list of the issues you find, with links to any fix PRs you may have created.

In the proposal, please perform an initial survey of possible commandline argument frameworks that we might want to evaluate. Please use at least some of the following criteria for evaluation:

  • Is it an established and well maintained framework (e.g. boost)?
  • Is it a header only framework?
  • Does it allow for nested commands/verbs as we have (e.g. radosgw-admin bucket list)?
  • Can it generate the "usage" docs automatically?
  • Can it give command/verb specific help (e.g. radosgw-admin bucket --help)?
  • Does it support per-command argument declaration, and generate the errors automatically when required arguments are missing?
  • Does it support the existing behavior that knows how to list the possible verbs that are next in the hierarchy. e.g. if you use the verb "bucket" and then "logging" the next options are:
radosgw-admin bucket logging
ERROR: Unknown command
Expected one of the following:
  flush
  info
  list

If you have questions or need clarifications for phase 2. please contact a mentor by email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment