<h3 id="table-of-contents">Table of Contents</h3>
<ul>
<li><a href="#commands">Commands</a>
<ul>
<li><a href="#modify-pool-replica-count">Modify Pool Replica Count</a></li>
<li><a href="#show-current-space-used">Show current space used</a></li>
<li><a href="#show-status">Show status</a></li>
<li><a href="#list-create-and-delete-volumes">List, create and delete volumes</a></li>
<li><a href="#presenting-a-volume-to-this-host">Presenting a volume to this host</a></li>
<li><a href="#snapshots">Snapshots</a></li>
<li><a href="#save-rbd-as-file">Save RBD as file</a></li>
<li><a href="#python-automation">Python Automation</a></li>
</ul>
</li>
</ul>
<h1 id="commands">Commands</h1>
<h2 id="modify-pool-replica-count">Modify Pool Replica Count</h2>
<p>Show and modify the replica count (size) in a given pool.</p>
<p>You can do the same with <code>min_size</code> if needed.</p>
<pre><code class="language-bash"># Show the current replica count
#   ceph osd pool get &#x3C;pool name> size
ceph osd pool get images size

# Set the replica count for a given pool
#   ceph osd pool set &#x3C;pool name> size &#x3C;number of replicas>
ceph osd pool set images size 2
</code></pre>
<h2 id="show-current-space-used">Show current space used</h2>
<pre><code class="language-bash">ceph df
</code></pre>
<h2 id="show-status">Show status</h2>
<pre><code class="language-bash"># Show the status right now
ceph -s

# Show the status and watch it
ceph -w
</code></pre>
<h2 id="list-create-and-delete-volumes">List, create and delete volumes</h2>
<pre><code class="language-bash"># LIST
# rbd ls -p &#x3C;pool name>
rbd ls -p volumes

# CREATE
#   rbd create --size &#x3C;size in gb> &#x3C;pool>/&#x3C;volume id>
rbd create --size 10 volumes/myVolume

# DELETE
#   rbd rm &#x3C;pool>/&#x3C;volume id>
rbd rm volumes/myVolume
</code></pre>
<h2 id="presenting-a-volume-to-this-host">Presenting a volume to this host</h2>
<pre><code class="language-bash"># PRESENT TO HOST
#   rbd map &#x3C;pool>/&#x3C;volume id>
rbd map volumes/myVolume

# LIST MAPPED
rbd showmapped

# REMOVE FROM HOST
#   rbd unmap &#x3C;pool>/&#x3C;volume id>
rbd unmap volumes/myVolume
</code></pre>
<p>Once you've presented the volume you can use it like this:</p>
<pre><code class="language-bash">mkfs.ext4 /dev/rbd0
mkdir /data
mount /dev/rbd0 /data
</code></pre>
<h2 id="snapshots">Snapshots</h2>
<pre><code class="language-bash"># LIST SNAPSHOTS
#   rbd snap ls &#x3C;pool>/&#x3C;volume id>
rbd snap ls volumes/myVolume

# REVERT TO SNAPSHOT
# rbd snap rollback &#x3C;pool>/&#x3C;volume id>@&#x3C;snapshot id>
rbd snap rollback volumes/myVolume@sampleSnapshot

# DELETE SNAPSHOT
#   rbd snap rm &#x3C;pool>/&#x3C;volume id>@&#x3C;snap id>
rbd snap rm volumes/myVolume@sampleSnapshot
</code></pre>
<h2 id="save-rbd-as-file">Save RBD as file</h2>
<pre><code class="language-bash">#   rbd export &#x3C;pool>/&#x3C;volume> &#x3C;filename>
rbd export volumes/myVolume myVolume.raw
</code></pre>
<h2 id="python-automation">Python Automation</h2>
<p>To automate any of the above from Python, the <code>rados</code> and <code>rbd</code> libraries
wrap the same operations. See <a href="/python-ceph.html">Python Ceph Examples</a> for
pool management, volume creation, and snapshot handling via the Python API.</p>


<p>This post covers some of the ways you can use Ceph from Python</p>
<p>The two libraries used here:</p>
<ul>
<li><a href="https://docs.ceph.com/docs/master/rados/api/python/">rados</a></li>
<li><a href="https://docs.ceph.com/docs/giant/rbd/librbdpy/">rbd</a></li>
</ul>
<hr>
<h1 id="setup">Setup</h1>
<h2 id="deploy-cephconf">Deploy ceph.conf</h2>
<p>Grab the ceph.conf file from your cluster or make a new valid one and place
it on the filesystem of the server which will execute the Python code.</p>
<p>Also copy the keyring over. Check <a href="https://docs.ceph.com/docs/master/rados/api/python/">here</a>
if you want to use anything other than the admin keyring.</p>
<h2 id="install-dependencies">Install Dependencies</h2>
<p>Ceph doesn't distribute a pure python library. Instead it seems to rely on some
C stuff that needs to be installed, so you need to use apt instead of pip.
This is a pain, since so far as I can tell you can't isolate these dependencies
inside a virtual environment.</p>
<pre><code class="language-bash">apt-get install python-rados
</code></pre>
<hr>
<h1 id="examples">Examples</h1>
<p>Be sure that the rados and rbd libraries, and <code>ceph.conf</code> are deployed first.</p>
<h2 id="instantiate-rados-and-rbd-instances">Instantiate rados and rbd instances</h2>
<p>The <code>cluster</code> and <code>rbd_inst</code> variables will be used through these examples.
The <code>rbd_inst</code> methods will expect <code>ioctx</code> as their first argument.</p>
<pre><code class="language-python">import rbd
import rados

cluster = rados.Rados(conffile='/etc/ceph/ceph.conf')
cluster.connect()

pool_name = 'volumes'
ioctx = cluster.open_ioctx(pool_name)
rbd_inst = rbd.RBD()
</code></pre>
<h1 id="usage-examples">Usage examples</h1>
<pre><code class="language-python"># Get cluster stats
# Returns dict with kb, num_objects, kb_avail, and kb_used
cluster.get_cluster_stats()

# Get cluster health by issuing a command to ceph's monitor
cmd = {"prefix":"status", "format":"json"}
## mon_command returns a tuple of (return code, data/buffer, errors)
command_result = cluster.mon_command(json.dumps(cmd), b'', timeout=5)
status = json.loads(command_result[1])

# Get Pool usage stats
# Returns num_objects_degraded, num_kb, num_wr, num_rd, num_objects_unfound,
#   num_objects_missing_on_primary, num_object_clones, num_objects,
#   num_object_copies, num_bytes, num_rd_kb, num_wr_kb
ioctx.get_stats()

# List pools
cluster.list_pools()

# Create pool
pool_name = 'test_pool'
cluster.create_pool(pool_name)

# Delete pool
cluster.delete_pool(pool_name)


# List rados block devices
rbd_inst.list(ioctx)

# Create block device
rbd_name = 'sample-device'
size_gb = 10
rbd_inst.create(ioctx, rbd_name, size_gb)

# Query a block device (image)
image = rbd.Image(ioctx, rbd_name)

# Resize image
new_size=20
image.resize(new_size)

# Create a snapshot
snap_name = 'sample-snap'
image.create_snap(snap_name)

# List snaps of image
image.list_snaps()

# Revert to snapshot
snap_name = 'sample-snap'
image.rollback_to_snap(snap_name)

# Delete a snapshot
image.remove_snap(snap_name)

# Close an open image (when you're done working with it)
image.close()

# Delete an image/volume. Must not have snapshots. Must be closed.
rbd_inst.remove(ioctx, rbd_name)
</code></pre>


Kyle Pericak

Ceph Reference Page

Python Ceph Examples