x/swiftonfile
Code Issues Proposed changes
swiftonfile/doc/markdown/quick_start_guide.md
Pushpesh Sharma 01abe7dc68 Minor updates
2014-07-18 13:10:24 +05:30

6.5 KiB
Raw Blame History

Quick Start Guide

Contents

## Overview SwiftOnFile allows any POSIX complaint filesystem (which supports extended attributes) to be used as the backend to the OpenStack Swift(Object Store).

The following guide assumes you have a running OpenStack Swift SAIO setup, and you want to extend this setup to try SwiftOnFile as Storage Policy on a with XFS partition or GlusterFS volume. This will get you quickly started with a SwiftOnFile deployment on a Fedora or RHEL/CentOS system.

This guide will not go on detail on how to prepare a Swift SAIO setup or how to create a gluster volume (or other FS).This guide assumes you know about these technologies, if you require any help in setting those please refer to the links provided.

## System Setup

Prerequisites on CentOS/RHEL

  1. OpenStack SAIO deployment(this guide uses SAIO on Fedora20)
  2. One xfs partition /glusterfs volume - named vol

Note: Swift SAIO deployment should contain Storage Policy code changes. SwiftOnFile should work with OpenStack Swift2.0.0 release and onwards. Icehouse and prior release of OpenStack Swift does not have Storage Policy code.

Each xfs partition/glusterfs volume will be defined as a separate storage policy.

Install SwiftOnfile

  1. Before you begin swiftonfile setup please ensure you have OpenStack Swift SAIO setup up & running. Please refer to the SAIO guide for this.
  2. cd $HOME; git clone https://github.com/swiftonfile/swiftonfile.git
  3. cd $HOME/swiftonfile;python setup.py develop;cd $HOME

Configure SwiftOnFile as Storage Policy

Object Server Configuration

An SAIO setup emulates a four node swift setup and should have four object server running. Add another object server for SwiftOnFile DiskFile API implementation by setting the following configurations in the file /etc/swift/object-server/5.conf:

[DEFAULT]
devices = /mnt/xfsvols/
mount_check = false
bind_port = 6050
max_clients = 1024
workers = 1
disable_fallocate = true

[pipeline:main]
pipeline = object-server

[app:object-server]
use = egg:gluster_swift#object
user = root
log_facility = LOG_LOCAL2
log_level = DEBUG
log_requests = on
disk_chunk_size = 65536

Note: The parameter 'devices' tells about the path where your xfs partition or glusterfs volume is mounted. The sub directory under which your xfs partition or glusterfs volume is mounted will be called device name.

For example: You have a xfs formated partition /dev/sdb1, and you mounted it under /mnt/xfsvols/vol, then your device name would be 'vol' & and the parameter 'devices' would contain value '/mnt/xfsvols'.

Setting SwiftOnFile as storage policy

Edit /etc/swift.conf to add swiftonfile as a storage policy:

[storage-policy:0]
name = swift
default = yes

[storage-policy:1]
name = swiftonfile-test

You can also make "swiftonfile-test" the default storage policy by using the 'default' parameter.

Prepare rings

Edit the remakerings script to prepare rings for this new storage policy:

swift-ring-builder object-1.builder create 1 1 1
swift-ring-builder object-1.builder add r1z1-127.0.0.1:6050/vol 1
swift-ring-builder object-1.builder rebalance

Execute the remakerings script to prepare new rings files. In a SAIO setup remakerings scipt is usually situated at ~/bin/remakerings.You can also run above rings builder commands manually.

Notice the mapping between SP index (1) defined in conf file above and the object ring builder command.

Load the new configurations

Restart swift services to reflect new changes:

swift-init main restart

Running functional tests

TBD

Using SwiftOnFile

It is assumed that you are still using 'tempauth' as authentication method, which is default in SAIO deployment.

Get the token

curl -v -H 'X-Auth-User: test:tester' -H "X-Auth-key: testing" -k http://localhost:8080/auth/v1.0

Use 'X-Auth-Token' & 'X-Storage-Url' returned in above request for all sucequent request.

Create a container

Create a container using the following command:

curl -v -X PUT -H 'X-Auth-Token: AUTH_XXXX' -H 'X-Storage-Policy: swiftonfile-test' http://localhost:8080/v1/AUTH_test/mycontainer

It should return HTTP/1.1 201 Created on a successful creation.

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 'X-Auth-Token: AUTH_XXXX' http://localhost:8080/v1/AUTH_test/mycontainer/mytestfile

To confirm that the object has been written correctly, you can compare the test file with the object you created:

cat /mnt/xfsvols/vol/AUTH_test/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_test/mycontainer/mytestfile
cat newfile

You can also use etag information provided while you do HEAD on object and compare it with md5sum of the file on your FS.

 ## What now? You now have a single node SwiftOnFile setup ready, next sane step is a multinode swift and SwiftOnFile setup. It is recomended to have a look at [OpenStack Swift deployment guide][] & [Multiple Server Swift Installation][].If you now consider yourself familiar with a typical 4-5 node swift setup, you are good to extent this setup further and add SwiftOnFile DiskFile implementation as a Storage Policy to it. If you want to use SwiftOnFile on a gluster volume, it would be good to have a seprate gluster cluster. We would love to hear about any deployment scenarios involving SOF.

For more information, please visit the following links: