How to set up a standalone Swift installation in a VM and test it

In this tutorial, we will be speaking about a “Swiftbox”. This is nothing more than our terminology for an Openstack installation that only needs and uses Swift and Keystone. The use and setup of this Swiftbox will be explained in this article.

The reason why someone might want a stripped-down OpenStack installation with only Swift and Keystone running, is that it allows easy testing of Swift services. A Swiftbox can be used to try understanding how object storage works. Also, having an independent object storage, is a good perk: it allows testing or running various different projects, with only one Swiftbox to be configured for everything.

A use case for this standalone Swift installation is to reproduce an isolated and potentially local environment to test applications that need or want to use Swift as their object storage backend. This can prove useful to experiment with the technology as well as to debug or exercise existing applications.

For the simplified nature of the Swift installation here described (everything runs inside a VM and not over a cluster of nodes!), this procedure should not be considered to run Swift for anything else than a stubby backend for a testing environment.

The main steps to set up a Swiftbox are:

• Creating and configuring a VM (we will use Vagrant and run a Ubuntu Server 14.04 box)
• Configuring Devstack
• Configuring a Keystone endpoint for Swift
• Testing Swift
• Some troubleshooting

INSTALLATION

First things first. The very first step is to download and install Vagrant (vagrantup.com). It’s important that you install an updated version (this tutorial was tested with version 1.6.5) – note that packaged versions shipping with your OS repository may be old.

Vagrant is a tool that lets us manage and automatize the deployment of VMs, using configuration files and the command line. We only have the stuff we need and actually want. It’s best when you have a directory in which you want to collect the VM files:

$ mkdir swiftbox/
$ cd swiftbox/

Now that we are in the directory we want the VM to be in, we use Vagrant to download a pre-built Ubuntu box and setup a VM. Vagrant will create a Vagrantfile in which the configuration of the VM can be set. To download the Ubuntu 14.04 Vagrant box and initialize our VM, you can do the following:

$ vagrant box add ubuntu/trusty64 # downloads the box with the OS
$ vagrant init # creates the Vagrantfile

The Vagrantfile is now in the directory, and ready to be configured. Open this file with your preferred text editor. The configurations have to be changed, so

• the correct box will be used.
• the ports 8080 (for Swift) and 5000 (for Keystone clients) will be forwarded.
• a private IP address will be set.

Port forwarding allows the request on these host ports to be redirected to the guest VM. By doing so, the Swift service will become accessible from the outside of the host running the VM. The Vagrantfile should look like this now:

VAGRANTFILE_API_VERSION = "2"

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
 config.vm.box = "ubuntu/trusty64"

 config.vm.network "forwarded_port", guest: 8080, host: 8080
 config.vm.network "forwarded_port", guest: 5000, host: 5000

 config.vm.network "private_network", ip: "192.168.33.10"
end

The Next step is to fire up the VM, ssh into it and start setting up the SwiftBox by downloading Devstack:

$ vagrant up #starts the VM
$ vagrant ssh #enters the VM

To download Devstack your machine will need git, which is not installed yet. So install git and download the Devstack repository.

$ sudo apt-get install git
$ git clone https://github.com/openstack-dev/devstack.git

Now, we don’t want or need an entire Devstack installation: since the Swiftbox only needs Swift and Keystone the other services can be disabled. We configure Devstack in a local.conf file, which we create in the Devstack directory (the one that was created by cloning the repository):

$ cd devstack
# use nano if you prefer, as editor
$ vim local.conf

In the local.conf file configurations have to be set for:

• general stuff like passwords or the service token
• the logging
• enabling and disabling of the services
• configurations for Swift

The local.conf should look similar to this now (obviously you can pick your own password and you can generate a new uuid for the token with the uuidgen command):

[[local|localrc]]
DEST=/opt/stack
ADMIN_PASSWORD=secrete
DATABASE_PASSWORD=$ADMIN_PASSWORD
RABBIT_PASSWORD=$ADMIN_PASSWORD
SERVICE_PASSWORD=$ADMIN_PASSWORD
SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50

##logging
LOGFILE=$DEST/logs/stack.sh.log
LOGDAYS=1

##services
disable_all_services
enable_service key mysql s-proxy s-object s-container s-account

##swift
SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5
SWIFT_REPLICAS=1
SWIFT_DATA_DIR=$DEST/data/swift

After configuring Devstack we can install it with:

$ ./stack.sh

To actually use Swift, an endpoint has to be configured for it in Keystone. Keystone serves the purpose that it provides authorization for the other OpenStack services. So, if we create an endpoint for Swift, Keystone will forward this information to authenticated clients, so they can reach the required service. Keystone commands require many options to be provided or some environment variables to contain the same information. To simplify our tasks, we can create a keystonerc file to be sourced. It contains the environment settings necessary to Keystone. You can create this file in the home directory:

$ cd
# use nano if you prefer, as editor
$ vim keystonerc

You will need at least these environment variables (paste the following lines into the file and adjust the values, if you changed them in the local.conf file for DevStack):

export OS_USERNAME=admin
export OS_PASSWORD=secrete
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://10.0.2.15:35357/v2.0

Then import the variables to your shell by sourcing the file:

$ source ~/keystonerc

You can see what services Keystone is running with:

$ keystone service-list

You can see, that there is a Swift service already. To use the service we have to set a new endpoint for it, so we provide the host address instead of the address of the guest in the VM network. This, together with the port forwarding, will allow the SwiftBox to be accessed from the outside.

So we copy and paste the id of the Swift service and use it in the following command:

$ keystone endpoint-create \
--region RegionOne \
--service-id=(the one you copy & pasted) \
--publicurl 'http://(your host IP):8080/v1/AUTH_$(tenant_id)s' \
--adminurl 'http://10.0.2.15:8080' \
--internalurl 'http://10.0.2.15:8080/v1/AUTH_$(tenant_id)s'

Now we will have two endpoints for the swift service, as you can see with the following command:

$ keystone endpoint-list

To complete the installation, we now need to delete the old endpoint (check the “publicurl” column to identify it), by copying its id and using it in the following command:

$ keystone endpoint-delete (id of the old endpoint)

TESTING

There are two different ways to test your Swift object storage. The first and more direct one is to use cURL to send HTTP requests to Swift and check the responses (this method is explained later). Alternatively, we have written a very simple application that will just upload an object with a defined content, read the content from the object on the Swift storage and write it back to a local file.

You can download the source code of this test application from GitHub:

$ cd src/   #where the rep. will be
$ git clone https://github.com/icclab/swiftbox-testing.git

Before you can use the application, you need to install the swiftclient library for python and change the configurations of the application to match your Swift setup. The configurations can be found in the Configuration.py file. Things that need to be changed are: auth_url, username, tenant_name, tenant_id, container_name, password, object_name, object_content, down_file_name. Then you can run the application in the terminal. For this you open the terminal and go to the directory the repository is in. You can run the app with python now.

# install the swiftclient library with pip or any other method
$ pip install python-swiftclient
$ python TestSwift.py   #run the application

If you don’t get an error, everything is fine and the file on your local directory should contain the predefined object_content.

To check your Swift manually you have to use some cURL commands, first you need to get the token to access the container. If you use the following command, you will also see a very long id, copy it and save it under a variable called token.

$ curl -s -X POST http://localhost:5000/v2.0/tokens -d\
'{"auth": {"passwordCredentials": {"username":"admin",\
"password":"secrete"}, "tenantName":"admin"}}' -H\
"Content-type: application/json" | python -m json.tool

$ token=PKIZ_[...]T8989Y=

Now you have everything you need to access the container. You can check for containers with:

$ curl -X GET -i -H "X-Auth-Token:$token" \
http://10.0.2.15:8080/v1/AUTH_9a6819247ed640439584fbca408e28ae

To  add a new container, just add the name you want it to be called at the end of the URI:

$ curl -X PUT -i -H "X-Auth-Token: $token"\
http://10.0.2.15:8080/v1/AUTH_9a6819247ed640439584fbca408e28ae/newContainerName

TROUBLESHOOTING

One thing you really need to know, is how to boot the VM properly after shutting it down. You should always do the graceful shut down of your VM.

$ exit #exit the VM
$ vagrant halt #graceful shutdown of VM

The thing is, if you reboot the machine now, your Swift storage won’t be mounted to your VM anymore, so it needs to be mounted again. The command looks similar to this:

$sudo mount -t xfs -o loop,noatime,nodiratime,nobarrier,logbufs=8 \
 /opt/stack/data/swift/drives/images/swift.img /opt/stack/data/swift/drives/sdb1

Then we need to rejoin the stack, so Keystone and Swift are available again, for this we go to the Devstack directory.

$ cd devstack
$ ./rejoin_stack.sh

A NOTE ABOUT SECURITY

Vagrant uses default password and RSA keys to authenticate users into the VM. Do not expose the SwiftBox on public endpoints if you haven’t changed both the password and the authorized keys.