rook

README

Open, Cloud Native, and Universal Distributed Storage

• What is Rook?
• Status
• Quickstart
• Building
• Design
• Contributing
• Contact
• Licensing

What is Rook?

Rook is a distributed storage system designed for cloud native applications. It exposes file, block, and object storage on top of shared resource pools. Rook has minimal dependencies and can be deployed in dedicated storage clusters or converged clusters. It's self-managing, self-protecting, self-healing, and is designed to just work without teams of engineers managing it. It scales from a single node, to multi-PB clusters spread geographically. It's based on the Ceph project with over 10 years of production deployments in some of the largest storage clusters in the world.

Status

Rook is in alpha state. We're just getting started. Not all planned features are complete. The API and other user-facing objects are subject to change. Backward-compability is not supported for this release. See our Roadmap and Issues. Please help us by Contributing to the project.

Quickstart

Here's the quickest way to get going with Rook.

Linux

On a modern Linux host run the following:

1. Download the latest binaries

   $ wget https://github.com/rook/rook/releases/download/v0.2.1/rook-v0.2.1-linux-amd64.tar.gz
   $ tar xvf rook-v0.2.1-linux-amd64.tar.gz
   

2. Start a one node Rook cluster

   $ ./rookd --data-dir /tmp/rook-test
   

Block Storage

1. In a different shell (in the same path) create a new volume image (10MB)

   $ ./rook block create --name test --size 10485760
   

2. Mount the block volume and format it

   sudo ./rook block mount --name test --path /tmp/rook-volume
   sudo chown $USER:$USER /tmp/rook-volume
   

3. Write and read a file

   echo "Hello Rook!" > /tmp/rook-volume/hello
   cat /tmp/rook-volume/hello
   

4. Cleanup

   sudo ./rook block unmount --path /tmp/rook-volume
   

Shared File System

1. Create a shared file system

   ./rook filesystem create --name testFS
   

2. Verify the shared file system was created

   ./rook filesystem ls
   

3. Mount the shared file system from the cluster to your local machine

   ./rook filesystem mount --name testFS --path /tmp/rookFS
   sudo chown $USER:$USER /tmp/rookFS
   

4. Write and read a file to the shared file system

   echo "Hello Rook!" > /tmp/rookFS/hello
   cat /tmp/rookFS/hello
   

5. Unmount the shared file system (this does not delete the data from the cluster)

   ./rook filesystem unmount --path /tmp/rookFS
   

6. Cleanup the shared file system from the cluster (this does delete the data from the cluster)

   ./rook filesystem delete --name testFS
   

Object Storage

1. Create an object storage instance in the cluster

   ./rook object create
   

2. Get the connection information for accessing object storage

   eval $(./rook object connection --format env-var)
   

3. Use an S3 compatible client to create a bucket in the object store

   s3cmd mb --no-ssl --host=${AWS_ENDPOINT} --host-bucket=  s3://rookbucket
   

4. List all buckets in the object store

   s3cmd ls --no-ssl --host=${AWS_ENDPOINT} --host-bucket=
   

5. Upload a file to the newly created bucket

   echo "Hello Rook!" > /tmp/rookObj
   s3cmd put /tmp/rookObj --no-ssl --host=${AWS_ENDPOINT} --host-bucket=  s3://rookbucket
   

6. Download and verify the file from the bucket

   s3cmd get s3://rookbucket/rookObj /tmp/rookObj-download --no-ssl --host=${AWS_ENDPOINT} --host-bucket=
   cat /tmp/rookObj-download
   

Kubernetes

To run a Kubernetes cluster with Rook for persistent storage go here

CoreOS

Rook is also easy to run on CoreOS either directly on the host or via rkt.

cd demo/vagrant
vagrant up

Building

See Building in the wiki for more details.

Design

A rook cluster is made up of one or more nodes each running the Rook daemon rookd. Containers and Pods can mount block devices and filesystems exposed by the cluster, or can use S3/Swift API for object storage. There is also a REST API exposed by rookd as well as a command line tool called rook.

The Rook daemon rookd is a single binary that is self-contained and has all that is needed to bootstrap, scale and manage a storage cluster. rookd is typically compiled into a single static binary (just like most golang binaries) or a dynamic binary that takes a dependency on mostly libc. It can run in minimal containers, alongside a hypervisor, or directly on the host on most Linux distributions.

rookd uses an embedded version of Ceph for storing all data -- there are no changes to the data path. An embedded version of Ceph was created specifically for Rook scenarios and has been pushed upstream. Rook does not attempt to maintain full fidelity with Ceph, for example, most of the Ceph concepts like OSDs, MONs, placement groups, etc. are hidden. Instead Rook creates a much simplified UX for admins that is in terms of physical resources, pools, volumes, filesystems, and buckets.

rookd embeds Etcd to store configuration and coordinate cluster-wide management operations. rookd will automatically bootstrap Etcd, manage it, and scale it as the cluster grows. It's also possible to use an external Etcd instead of the embedded one if needed.

Rook and etcd are implemented in golang. Ceph is implemented in C++ where the data path is highly optimized. We believe this combination offers the best of both worlds.

See Design wiki for more details.

Contributing

We welcome contributions. See Contributing to get started.

Report a Bug

For filing bugs, suggesting improvements, or requesting new features, help us out by opening an issue.

Contact

Please use the following to reach members of the community:

• Email: rook-dev
• Gitter: rook/rook for general project discussions or rook-dev for development discussions.
• Twitter: @rook_io

Licensing

Rook and Etcd are under the Apache 2.0 license. Ceph is mostly under the LGPL 2.0 license. Some portions of the code are under different licenses. The appropriate license information can be found in the headers of the source files.

Documentation

Overview

Copyright 2016 The Rook Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.