Welcome to Rook! We hope you have a great experience installing the Rook **cloud-native storage orchestrator** platform to enable highly available, durable Ceph storage in your Kubernetes cluster.
If you have any questions along the way, please don't hesitate to ask us in our [Slack channel](https://rook-io.slack.com). You can sign up for our Slack [here](https://slack.rook.io).
This guide will walk you through the basic setup of a Ceph cluster and enable you to consume block, object, and file storage
from other pods running in your cluster.
**Always use a virtual machine when testing Rook. Never use your host system where local devices may mistakenly be consumed.**
To make sure you have a Kubernetes cluster that is ready for `Rook`, you can [follow these instructions](Prerequisites/prerequisites.md).
In order to configure the Ceph storage cluster, at least one of these local storage options are required:
* Raw devices (no partitions or formatted filesystems)
* Raw partitions (no formatted filesystem)
* Persistent Volumes available from a storage class in `block` mode
## TL;DR
A simple Rook cluster can be created with the following kubectl commands and [example manifests](https://github.com/rook/rook/blob/master/deploy/examples).
After the cluster is running, you can create [block, object, or file](#storage) storage to be consumed by other applications in your cluster.
## Deploy the Rook Operator
The first step is to deploy the Rook operator. Check that you are using the [example yaml files](https://github.com/rook/rook/blob/master/deploy/examples) that correspond to your release of Rook. For more options, see the [example configurations documentation](example-configurations.md).
# verify the rook-ceph-operator is in the `Running` state before proceeding
kubectl -n rook-ceph get pod
```
You can also deploy the operator with the [Rook Helm Chart](../Helm-Charts/operator-chart.md).
Before you start the operator in production, there are some settings that you may want to consider:
1. Consider if you want to enable certain Rook features that are disabled by default. See the [operator.yaml](https://github.com/rook/rook/blob/master/deploy/examples/operator.yaml) for these and other advanced settings.
1. Device discovery: Rook will watch for new devices to configure if the `ROOK_ENABLE_DISCOVERY_DAEMON` setting is enabled, commonly used in bare metal clusters.
2. Node affinity and tolerations: The CSI driver by default will run on any node in the cluster. To configure the CSI driver affinity, several settings are available.
If you wish to deploy into a namespace other than the default `rook-ceph`, see the
[Ceph advanced configuration section](../Storage-Configuration/Advanced/ceph-configuration.md#using-alternate-namespaces) on the topic.
## Cluster Environments
The Rook documentation is focused around starting Rook in a production environment. Examples are also
provided to relax some settings for test environments. When creating the cluster later in this guide, consider these example cluster manifests:
* [cluster.yaml](https://github.com/rook/rook/blob/master/deploy/examples/cluster.yaml): Cluster settings for a production cluster running on bare metal. Requires at least three worker nodes.
* [cluster-on-pvc.yaml](https://github.com/rook/rook/blob/master/deploy/examples/cluster-on-pvc.yaml): Cluster settings for a production cluster running in a dynamic cloud environment.
* [cluster-test.yaml](https://github.com/rook/rook/blob/master/deploy/examples/cluster-test.yaml): Cluster settings for a test environment such as minikube.
See the [Ceph example configurations](example-configurations.md) for more details.
## Create a Ceph Cluster
Now that the Rook operator is running we can create the Ceph cluster. For the cluster to survive reboots,
make sure you set the `dataDirHostPath` property that is valid for your hosts. For more settings, see the documentation on [configuring the cluster](../CRDs/Cluster/ceph-cluster-crd.md).
To verify that the cluster is in a healthy state, connect to the [Rook toolbox](../Troubleshooting/ceph-toolbox.md) and run the
`ceph status` command.
* All mons should be in quorum
* A mgr should be active
* At least one OSD should be active
* If the health is not `HEALTH_OK`, the warnings or errors should be investigated
```console
$ ceph status
cluster:
id: a0452c76-30d9-4c1a-a948-5d8405f19a7c
health: HEALTH_OK
services:
mon: 3 daemons, quorum a,b,c (age 3m)
mgr: a(active, since 2m)
osd: 3 osds: 3 up (since 1m), 3 in (since 1m)
[]...]
```
If the cluster is not healthy, please refer to the [Ceph common issues](../Troubleshooting/ceph-common-issues.md) for more details and potential solutions.
## Storage
For a walkthrough of the three types of storage exposed by Rook, see the guides for:
* **[Block](../Storage-Configuration/Block-Storage-RBD/block-storage.md)**: Create block storage to be consumed by a pod (RWO)
* **[Shared Filesystem](../Storage-Configuration/Shared-Filesystem-CephFS/filesystem-storage.md)**: Create a filesystem to be shared across multiple pods (RWX)
* **[Object](../Storage-Configuration/Object-Storage-RGW/object-storage.md)**: Create an object store that is accessible inside or outside the Kubernetes cluster
## Ceph Dashboard
Ceph has a dashboard in which you can view the status of your cluster. Please see the [dashboard guide](../Storage-Configuration/Monitoring/ceph-dashboard.md) for more details.
## Tools
Create a toolbox pod for full access to a ceph admin client for debugging and troubleshooting your Rook cluster. Please see the [toolbox documentation](../Troubleshooting/ceph-toolbox.md) for setup and usage information. Also see our [advanced configuration](../Storage-Configuration/Advanced/ceph-configuration.md) document for helpful maintenance and tuning examples.
## Monitoring
Each Rook cluster has some built in metrics collectors/exporters for monitoring with [Prometheus](https://prometheus.io/).
To learn how to set up monitoring for your Rook cluster, you can follow the steps in the [monitoring guide](../Storage-Configuration/Monitoring/ceph-monitoring.md).
