ceph/doc/start/quick-ceph-deploy.rst

==========================
 Object Store Quick Start
==========================

If you haven't completed your `Preflight Checklist`_, do that first. This
**Quick Start** sets up a two-node demo cluster so you can explore some of the
object store functionality. This **Quick Start**  will help you install a
minimal Ceph cluster on a server node from your admin node using
``ceph-deploy``.

.. ditaa:: 
           /----------------\         /----------------\
           |   Admin Node   |<------->|   Server Node  |
           | cCCC           |         | cCCC           |
           +----------------+         +----------------+
           |  Ceph Commands |         |   ceph - mon   |
           \----------------/         +----------------+
                                      |   ceph - osd   |
                                      +----------------+
                                      |   ceph - mds   |
                                      \----------------/


For best results, create a directory on your admin node for maintaining the
configuration of your cluster. ::

	mkdir my-cluster
	cd my-cluster

.. tip:: The ``ceph-deploy`` utility will output files to the 
   current directory.


Create a Cluster
================

To create your cluster, declare its initial monitors, generate a filesystem ID
(``fsid``) and generate monitor keys by entering the following command on a
commandline prompt:: 

	ceph-deploy new {node-name}
	ceph-deploy new ceph-node

Check the output with ``ls`` and ``cat`` in the current directory. You should
see a Ceph configuration file, a keyring, and a log file for the new cluster. 
See `ceph-deploy new -h`_ for additional details.

.. topic:: Single Node Quick Start

	Assuming only one node for your cluster, you	will need to modify the default 
	``osd crush chooseleaf type`` setting (it	defaults to ``1`` for ``node``) to 
	``0`` so that it will peer with OSDs on the local node. Add the following
	line to your Ceph configuration file:: 
	
		osd crush chooseleaf type = 0 


Install Ceph
============

To install Ceph on your server node, open a command line on your admin
node and type the following::

	ceph-deploy install {node-name}[,{node-name}]
	ceph-deploy install --stable cuttlefish ceph-node

Without additional arguments, ``ceph-deploy`` will install the most recent
stable Ceph package to the server node. See `ceph-deploy install -h`_ for
additional details.


Add a Monitor
=============

To run a Ceph cluster, you need at least one Ceph Monitor. When using
``ceph-deploy``, the tool enforces a single Ceph Monitor per node. Execute the
following to create a Ceph Monitor::

	ceph-deploy mon create {node-name}
	ceph-deploy mon create ceph-node

.. tip:: In production environments, we recommend running Ceph Monitors on 
   nodes that do not run OSDs.




Gather Keys
===========

To deploy additional daemons and provision them with monitor authentication keys
from your admin node, you must first gather keys from a monitor node. Execute
the following to gather keys:: 

	ceph-deploy gatherkeys {mon-node-name}
	ceph-deploy gatherkeys ceph-node


Once you have gathered keys, you should have a keyring named
``{cluster-name}.client.admin.keyring``,
``{cluster-name}.bootstrap-osd.keyring`` and
``{cluster-name}.bootstrap-mds.keyring`` in the local directory. If you don't,
you may have a problem with your network  connection. Ensure that you complete
this step such that you have the foregoing keyrings before proceeding further.

Add OSDs
========

For a cluster's object placement groups to reach an ``active + clean`` state,
you must have at least two OSDs and at least two copies of an object (``osd pool
default size`` is ``2`` by default).

Adding OSDs is slightly more involved than other ``ceph-deploy`` commands,
because an OSD involves both a data store and a journal. The ``ceph-deploy``
tool has the ability to invoke ``ceph-disk-prepare`` to prepare the disk and
activate the OSD for you.


List Disks
----------

To list the available disk drives on a prospective OSD node, execute the
following::

	ceph-deploy disk list {osd-node-name}
	ceph-deploy disk list ceph-node


Zap a Disk
----------

To zap a disk (delete its partition table) in preparation for use with Ceph,
execute the following::

	ceph-deploy disk zap {osd-node-name}:{disk}
	ceph-deploy disk zap ceph-node:sdb ceph-node:sdb2

.. important:: This will delete all data on the disk.


Multiple OSDs on the OS Disk (Demo Only)
----------------------------------------

For demonstration purposes, you may wish to add multiple OSDs to the OS disk
(not recommended for production systems). To use Ceph OSDs daemons on the OS
disk, you must use ``prepare`` and ``activate`` as separate steps. First, define
a directory for the Ceph OSD daemon(s). ::
   
	mkdir /tmp/osd0
	mkdir /tmp/osd1
   
Then, use ``prepare`` to prepare the directory(ies) for use with a
Ceph OSD Daemon. :: 
   
	ceph-deploy osd prepare {osd-node-name}:/tmp/osd0
	ceph-deploy osd prepare {osd-node-name}:/tmp/osd1

Finally, use ``activate`` to activate the Ceph OSD Daemons. :: 

	ceph-deploy osd activate {osd-node-name}:/tmp/osd0
	ceph-deploy osd activate {osd-node-name}:/tmp/osd1		

.. tip:: You need two OSDs to reach an ``active + clean`` state. You can 
   add one OSD at a time, but OSDs need to communicate with each other
   for Ceph to run properly. Always use more than one OSD per cluster.


Add OSDs on Standalone Disks
----------------------------

You can add OSDs using ``prepare`` and ``activate`` in two discrete
steps. To prepare a disk for use with a Ceph OSD Daemon, execute the 
following:: 

	ceph-deploy osd prepare {osd-node-name}:{osd-disk-name}[:/path/to/journal]
	ceph-deploy osd prepare ceph-node:sdb

To activate the Ceph OSD Daemon, execute the following:: 

	ceph-deploy osd activate {osd-node-name}:{osd-partition-name}
	ceph-deploy osd activate ceph-node:sdb1


To prepare an OSD disk and activate it in one step, execute the following:: 

	ceph-deploy osd create {osd-node-name}:{osd-disk-name}[:/path/to/journal] [{osd-node-name}:{osd-disk-name}[:/path/to/journal]]
	ceph-deploy osd create ceph-node:sdb:/dev/ssd1 ceph-node:sdc:/dev/ssd2


.. note:: The journal example assumes you will use a partition on a separate 
   solid state drive (SSD). If you omit a journal drive or partition, 
   ``ceph-deploy`` will use create a separate partition for the journal
   on the same drive. If you have already formatted your disks and created
   partitions, you may also use partition syntax for your OSD disk.

You must add a minimum of two OSDs for the placement groups in a cluster to
achieve an ``active + clean`` state. 


Add a MDS
=========

To use CephFS, you need at least one metadata node. Execute the following to
create a metadata node::

	ceph-deploy mds create {node-name}
	ceph-deploy mds create ceph-node


.. note:: Currently Ceph runs in production with one metadata node only. You 
   may use more, but there is currently no commercial support for a cluster 
   with multiple metadata nodes.


Summary
=======

Once you deploy a Ceph cluster, you can try out some of the administration
functionality, the object store command line, and then proceed to Quick Start
guides for RBD, CephFS, and the Ceph Gateway.

.. topic:: Other ceph-deploy Commands

	To view other ``ceph-deploy`` commands, execute: 
	
	``ceph-deploy -h``
	

See `Ceph Deploy`_ for additional details.


.. _Preflight Checklist: ../quick-start-preflight
.. _Ceph Deploy: ../../rados/deployment
.. _ceph-deploy install -h: ../../rados/deployment/ceph-deploy-install
.. _ceph-deploy new -h: ../../rados/deployment/ceph-deploy-new