From adf2ce0237430d9835cd291b36f4d6b40fdc9e09 Mon Sep 17 00:00:00 2001 From: Prashanth Pai Date: Thu, 2 Mar 2017 11:38:43 +0530 Subject: Update quick start guide The steps in this updated guide is verified on: * CentOS 7 * Ubuntu 16.04 'Xenial' LTS Change-Id: I47c1bfadebbafd56ceee0e09b1afef862700081a Signed-off-by: Prashanth Pai Reviewed-on: https://review.gluster.org/16822 --- doc/markdown/quick_start_guide.md | 301 ++++++++++++++++---------------------- 1 file changed, 129 insertions(+), 172 deletions(-) diff --git a/doc/markdown/quick_start_guide.md b/doc/markdown/quick_start_guide.md index 0b0990f..9312ae9 100644 --- a/doc/markdown/quick_start_guide.md +++ b/doc/markdown/quick_start_guide.md @@ -2,196 +2,158 @@ ## Contents * [Overview](#overview) -* [System Setup](#system_setup) -* [Gluster For Swift Setup](#swift_setup) +* [Setting up GlusterFS](#gluster_setup) +* [Setting up gluster-swift](#swift_setup) * [Using Gluster for Swift](#using_swift) -* [Accessing over Amazon S3 API](s3.md) * [What now?](#what_now) ## Overview -Gluster-swift allows GlusterFS to be used as the backend to the object -store OpenStack Swift. +Gluster-swift project enables object based access (over Swift and S3 API) +to GlusterFS volumes.This guide is a great way to begin using gluster-swift, +and can be easily deployed on a single virtual machine. The final result +will be a single gluster-swift node. -The following guide will get you quickly started with a gluster-swift -environment on a Fedora or RHEL/CentOS system. This guide is a -great way to begin using gluster-swift, and can be easily deployed on -a single virtual machine. The final result will be a single gluster-swift -node. +The instructions provided in this guide has been tested specifically on: +* CentOS 7 +* Ubuntu 16.04.2 LTS 'xenial' + +If you are on other distributions, the steps related to where you fetch +the installation packages may vary. > NOTE: In Gluster-Swift, accounts must be GlusterFS volumes. - -## System Setup + +## Setting up GlusterFS -### Prerequisites on CentOS/RHEL -On CentOS/RHEL you will need to setup GlusterFS and EPEL repos. +### Installing and starting GlusterFS -#### GlusterFS CentOS/RHEL Repo +If on Ubuntu 16.04: -* CentOS +```sh +# add-apt-repository ppa:gluster/glusterfs-3.10 +# apt-get install glusterfs-server attr +# service glusterfs-server start +``` -~~~ -wget -O /etc/yum.repos.d/glusterfs-epel.repo \ - http://download.gluster.org/pub/gluster/glusterfs/LATEST/CentOS/glusterfs-epel.repo -~~~ +If on CentOS 7: -* RHEL +```sh +# yum install centos-release-gluster +# yum install glusterfs-server +# service glusterd start +``` -~~~ -wget -O /etc/yum.repos.d/glusterfs-epel.repo \ - http://download.gluster.org/pub/gluster/glusterfs/LATEST/RHEL/glusterfs-epel.repo -~~~ +### Setting up a GlusterFS volume -#### EPEL CentOS/RHEL Repo -Please refer to [EPEL][] for more information on how to setup the EPEL repo. +You can use separate partitions as bricks. This guide illustrates using +loopback devices as bricks. -### Required Package Installation -Install and start the required packages on your system to create a GlusterFS volume. +Create bricks: -~~~ -yum install glusterfs glusterfs-server glusterfs-fuse memcached xfsprogs -~~~ +```sh +# truncate -s 1GB /srv/disk{1..4} +# for i in `seq 1 4`;do mkfs.xfs -i size=512 /srv/disk$i ;done +# mkdir -p /export/brick{1..4} +``` -#### Start services - -Type the following to start `memcached` and `glusterfs` services: +Add the following lines to `/etc/fstab` to auto-mount the the bricks on system startup: ~~~ -service memcached start -service glusterd start +/srv/disk1 /export/brick1 xfs loop,inode64,noatime,nodiratime 0 0 +/srv/disk2 /export/brick2 xfs loop,inode64,noatime,nodiratime 0 0 +/srv/disk3 /export/brick3 xfs loop,inode64,noatime,nodiratime 0 0 +/srv/disk4 /export/brick4 xfs loop,inode64,noatime,nodiratime 0 0 ~~~ -Type the following to start the services automatically on system startup: +Mount the bricks: -~~~ -chkconfig memcached on -chkconfig glusterd on -~~~ - -### Gluster Volume Setup -Now you need to determine whether you are going to use a partition or a loopback device -for storage. +```sh +# mount -a +``` -#### Partition Storage Setup -If you are using a separate disk partition, please execute the following instructions -to create a GlusterFS brick: - -~~~ -mkfs.xfs -i size=512 /dev/ -mkdir -p /export/brick -~~~ +You can now create and start the GlusterFS volume. +Make sure your hostname is in /etc/hosts or is DNS-resolvable. -Add the following line to `/etc/fstab` to mount the storage automatically on system -startup: +```sh +# gluster volume create myvolume replica 2 transport tcp `hostname`:/export/brick{1..4}/data force +# gluster volume start myvolume +``` -~~~ -/dev/ /export/brick xfs inode64,noatime,nodiratime 0 0 -~~~ +Mount the GlusterFS volume: -Now type the following to mount the storage: - -~~~ -mount -a -~~~ - -#### Loopback Storage Setup -If you do not have a separate partition, please execute the following instructions -to create a disk image as a file: - -~~~ -truncate -s 5GB /srv/swift-disk -mkfs.xfs -i size=512 /srv/swift-disk -mkdir -p /export/brick -~~~ - -Add the following line to `/etc/fstab` to mount the storage automatically on system -startup: - -~~~ -/srv/swift-disk /export/brick xfs loop,inode64,noatime,nodiratime 0 0 -~~~ - -Now type the following to mount the storage: - -~~~ -mount -a -~~~ - -### Create a GlusterFS Volume -You now need to create a GlusterFS volume (make sure your hostname is in /etc/hosts or is DNS-resolvable) - -~~~ -mkdir /export/brick/b1 -gluster volume create myvolume `hostname`:/export/brick/b1 -gluster volume start myvolume -~~~ +```sh +# mkdir -p /mnt/gluster-object/myvolume +# mount -t glusterfs `hostname`:myvolume /mnt/gluster-object/myvolume +``` -## Gluster-Swift Setup +## Setting up gluster-swift -### Repository Setup on RHEL/CentOS -Gluster-Swift requires OpenStack Swift's Havana release, which -may not be available on some older operating systems. For RHEL/CentOS -systems, please setup Red Hat RDO's repo by executing the following command: +### Installing Openstack Swift (kilo version) -~~~ -yum install -y http://rdo.fedorapeople.org/rdo-release.rpm -~~~ +If on Ubuntu 16.04: -### Download -Download the latest Havana release RPMs from [launchpad.net downloads][]: +```sh +# apt install python-pip libffi-dev memcached +# git clone https://github.com/openstack/swift; cd swift +# git checkout -b kilo tags/kilo-eol +# pip install -r ./requirements.txt +# python setup.py install +``` -### Install -Install the RPM by executing the following: +If on CentOS 7: -~~~ -yum install -y -~~~ +```sh +# yum install centos-release-openstack-kilo +# yum install openstack-swift-* +``` -### Enabling gluster-swift accross reboots -Type the following to make sure gluster-swift is enabled at -system startup: +### Installing gluster-swift (kilo version) -~~~ -chkconfig openstack-swift-proxy on -chkconfig openstack-swift-account on -chkconfig openstack-swift-container on -chkconfig openstack-swift-object on -~~~ +If on Ubuntu 16.04: -#### Fedora 19 Adjustment -Currently gluster-swift requires its processes to be run as `root`. You need to -edit the `openstack-swift-*.service` files in -`/etc/systemd/system/multi-user.target.wants` and change the `User` entry value -to `root`. +```sh +# git clone https://github.com/gluster/gluster-swift; cd gluster-swift +# pip install -r ./requirements.txt +# python setup.py install +``` -Then run the following command to reload the configuration: +If on CentoOS 7: -~~~ -systemctl --system daemon-reload -~~~ +```sh +# yum install epel-release +# yum install python-scandir python-prettytable git +# git clone https://github.com/gluster/gluster-swift; cd gluster-swift +# python setup.py install +``` -### Configuration +### gluster-swift configuration files As with OpenStack Swift, gluster-swift uses `/etc/swift` as the directory containing the configuration files. You will need to base the configuration files on the template files provided. On new installations, the simplest way is to copy the `*.conf-gluster` files to `*.conf` files as follows: -~~~ -cd /etc/swift -for tmpl in *.conf-gluster ; do cp ${tmpl} ${tmpl%.*}.conf; done -~~~ +Copy conf files from `etc` directory in gluster-swift repo to +`/etc/swift` and rename the template files. -#### Generate Ring Files -You now need to generate the ring files, which inform gluster-swift -which GlusterFS volumes are accessible over the object -storage interface. The format is +```sh +# mkdir -p /etc/swift/ +# cp etc/* /etc/swift/ +# cd /etc/swift +# for tmpl in *.conf-gluster ; do cp ${tmpl} ${tmpl%.*}.conf; done +``` -~~~ -gluster-swift-gen-builders [VOLUME] [VOLUME...] -~~~ +### Export GlusterFS volumes over gluster-swift + +You now need to generate the ring files, which informs gluster-swift +which GlusterFS volumes are accessible over the object storage interface. +The format is: + +```sh +# gluster-swift-gen-builders [VOLUME] [VOLUME...] +``` Where *VOLUME* is the name of the GlusterFS volume which you would like to access over gluster-swift. @@ -199,20 +161,16 @@ like to access over gluster-swift. Let's now expose the GlusterFS volume called `myvolume` you created above by executing the following command: -~~~ -cd /etc/swift -/usr/bin/gluster-swift-gen-builders myvolume -~~~ +```sh +# gluster-swift-gen-builders myvolume +``` ### Start gluster-swift Use the following commands to start gluster-swift: -~~~ -service openstack-swift-object start -service openstack-swift-container start -service openstack-swift-account start -service openstack-swift-proxy start -~~~ +```sh +# swift-init main start +``` ## Using gluster-swift @@ -220,41 +178,41 @@ service openstack-swift-proxy start ### Create a container Create a container using the following command: -~~~ -curl -v -X PUT http://localhost:8080/v1/AUTH_myvolume/mycontainer -~~~ +```sh +# curl -i -X PUT http://localhost:8080/v1/AUTH_myvolume/mycontainer +``` It should return `HTTP/1.1 201 Created` on a successful creation. You can also confirm that the container has been created by inspecting the GlusterFS volume: -~~~ -ls /mnt/gluster-object/myvolume -~~~ +```sh +# ls /mnt/gluster-object/myvolume +``` #### Create an object You can now place an object in the container you have just created: -~~~ -echo "Hello World" > mytestfile -curl -v -X PUT -T mytestfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile -~~~ +```sh +# echo "Hello World" > mytestfile +# curl -i -X PUT -T mytestfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile +``` To confirm that the object has been written correctly, you can compare the test file with the object you created: -~~~ -cat /mnt/gluster-object/myvolume/mycontainer/mytestfile -~~~ +```sh +# cat /mnt/gluster-object/myvolume/mycontainer/mytestfile +``` #### Request the object Now you can retreive the object and inspect its contents using the following commands: -~~~ -curl -v -X GET -o newfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile -cat newfile -~~~ +```sh +# curl -i -X GET -o newfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile +# cat newfile +``` ## What now? @@ -263,11 +221,10 @@ For more information, please visit the following links: * [Authentication Services Start Guide][] * [GlusterFS Quick Start Guide][] * [OpenStack Swift API][] +* [Accessing over Amazon S3 API][] + [GlusterFS Quick Start Guide]: http://www.gluster.org/community/documentation/index.php/QuickStart [OpenStack Swift API]: http://docs.openstack.org/api/openstack-object-storage/1.0/content/ -[Jenkins]: http://jenkins-ci.org [Authentication Services Start Guide]: auth_guide.md -[EPEL]: https://fedoraproject.org/wiki/EPEL -[launchpad.net downloads]: http://launchpad.net/gluster-swift/havana/1.10.0-2 - +[Accessing over Amazon S3 API]: s3.md -- cgit