• Getting Started
• Documentation
• Community
• Development
• News
• Contact

Quick Start: OpenStack

1. Introduction
2. Get OpenStack
3. Get jclouds
4. Terminology
5. List Servers
6. List Containers
7. Next Steps
8. OpenStack Providers

Introduction

OpenStack is a global collaboration of developers and cloud computing technologists producing the ubiquitous open source cloud computing platform for public and private clouds. The project aims to deliver solutions for all types of clouds by being simple to implement, massively scalable, and feature rich. The technology consists of a series of interrelated projects delivering various components for a cloud infrastructure solution.

Get OpenStack

You can either install a private OpenStack cloud for yourself or use an existing OpenStack public cloud.

DevStack

If you haven't installed OpenStack before, the best place to start is DevStack. DevStack is a documented shell script to build complete OpenStack development environments. The 1-2-3 Quick Start doesn't mention it but it's best to create a localrc file in your devstack directory before running stack.sh. For our purposes the setting we'll need to know to work with jclouds is ADMIN_PASSWORD.

DevStack can be run either in a local VM or in the cloud. The DevStack website has some generic instructions for Running a Cloud in a VM. You can find more specific instructions to run DevStack in VirtualBox at Contributing OpenStack Support to jclouds. To run it in the Rackspace Cloud please read OpenStack devstack on the Rackspace Cloud.

Public Clouds

Because the OpenStack API is also open, the jclouds APIs that talk to private OpenStack clouds work just as well with public OpenStack clouds. OpenStack is used by several large public clouds, both the HP Cloud and Rackspace Cloud are based on it. If you don't want to sign up for a paid public cloud, you can use TryStack.

Get jclouds

1. Ensure you are using the Java Development Kit (JDK) version 6 or later.
2. In your Terminal or Command Prompt run the following to verify the JDK is installed correctly.
   • javac -version
3. Create a directory to try out jclouds.
   • mkdir jclouds
4. Follow the instructions for Getting the binaries using Apache Ant.
5. You should now have a directory with the following structure:
   • jclouds/
     • build.xml
     • maven-ant-tasks.jar
     • lib/
       • *.jar

Terminology

There are some differences in terminology between jclouds and OpenStack that should be made clear.

	jclouds	OpenStack
	Compute	Nova
	Node	Server
	Location/Zone	Region
	Hardware	Flavor
	NodeMetadata	Server details
	UserMetadata	Metadata
	BlobStore	Swift
	Blob	File

List Servers

Introduction

OpenStack Compute (aka Nova) is an easy to use service that provides on-demand servers that you can use to to build dynamic websites, deliver mobile apps, or crunch big data.

The Source Code

1. Create a Java source file called JCloudsNova.java in the jclouds directory above.
2. You should now have a directory with the following structure:
   • jclouds/
     • JCloudsNova.java
     • build.xml
     • maven-ant-tasks.jar
     • lib/
       • *.jar
3. Open JCloudsNova.java for editing, read the code below, and copy it in.

import static com.google.common.io.Closeables.closeQuietly;
    
import java.io.Closeable;
import java.util.Set;

import org.jclouds.ContextBuilder;
import org.jclouds.compute.ComputeService;
import org.jclouds.compute.ComputeServiceContext;
import org.jclouds.logging.slf4j.config.SLF4JLoggingModule;
import org.jclouds.openstack.nova.v2_0.NovaApi;
import org.jclouds.openstack.nova.v2_0.NovaAsyncApi;
import org.jclouds.openstack.nova.v2_0.domain.Server;
import org.jclouds.openstack.nova.v2_0.features.ServerApi;
import org.jclouds.rest.RestContext;

import com.google.common.collect.ImmutableSet;
import com.google.inject.Module;

public class JCloudsNova implements Closeable {
   private ComputeService compute;
   private RestContext<NovaApi, NovaAsyncApi> nova;
   private Set<String> zones;

   public static void main(String[] args) {
      JCloudsNova jCloudsNova = new JCloudsNova();

      try {
         jCloudsNova.init();
         jCloudsNova.listServers();
         jCloudsNova.close();
      }
      catch (Exception e) {
         e.printStackTrace();
      }
      finally {
         jCloudsNova.close();
      }
   }

   private void init() {
      Iterable<Module> modules = ImmutableSet.<Module> of(new SLF4JLoggingModule());

      String provider = "openstack-nova";
      String identity = "demo:demo"; // tenantName:userName
      String password = "devstack"; // demo account uses ADMIN_PASSWORD too

      ComputeServiceContext context = ContextBuilder.newBuilder(provider)
            .endpoint("http://172.16.0.1:5000/v2.0/")
            .credentials(identity, password)
            .modules(modules)
            .buildView(ComputeServiceContext.class);
      compute = context.getComputeService();
      nova = context.unwrap();
      zones = nova.getApi().getConfiguredZones();
   }

   private void listServers() {
      for (String zone: zones) {
         ServerApi serverApi = nova.getApi().getServerApiForZone(zone);

         System.out.println("Servers in " + zone);

         for (Server server: serverApi.listInDetail().concat()) {
            System.out.println("  " + server);
         }
      }
   }

   public void close() {
      closeQuietly(compute.getContext());
   }
}

In the init() method note that

• String provider = "openstack-nova";
  • This ones pretty self explanatory, we're using the OpenStack Nova provider in jclouds
• String identity = "demo:demo"; // tenantName:userName
  • Here we use the tenant name and user name with a colon between them instead of just a user name
• String password = "devstack";
  • The demo account uses ADMIN_PASSWORD too
• .endpoint("http://172.16.0.1:5000/v2.0/")
  • This is the Keystone endpoint that jclouds needs to connect with to get more info (services and endpoints) from OpenStack
  • When the devstack installation completes successfully, one of the last few lines will read something like "Keystone is serving at http://172.16.0.1:5000/v2.0/"
  • Set the endpoint to this URL depending on the method used to get OpenStack above.

Compile and Run

javac -classpath ".:lib/*" JCloudsNova.java

java -classpath ".:lib/*" JCloudsNova

[logging output]
Servers in RegionOne
[logging output]
  Server{uuid=...}
  ...

List Containers

Introduction

OpenStack Object Storage (aka Swift) provides redundant, scalable object storage using clusters of standardized servers capable of storing petabytes of data.

The Source Code

1. Create a Java source file called JCloudsSwift.java in the jclouds directory above.
2. You should now have a directory with the following structure:
   • jclouds/
     • JCloudsSwift.java
     • build.xml
     • maven-ant-tasks.jar
     • lib/
       • *.jar
3. Open JCloudsSwift.java for editing, read the code below, and copy it in.

import static com.google.common.io.Closeables.closeQuietly;

import java.io.Closeable;
import java.util.Set;

import org.jclouds.ContextBuilder;
import org.jclouds.blobstore.BlobStore;
import org.jclouds.blobstore.BlobStoreContext;
import org.jclouds.logging.slf4j.config.SLF4JLoggingModule;
import org.jclouds.openstack.swift.CommonSwiftAsyncClient;
import org.jclouds.openstack.swift.CommonSwiftClient;
import org.jclouds.openstack.swift.domain.ContainerMetadata;
import org.jclouds.rest.RestContext;

import com.google.common.collect.ImmutableSet;
import com.google.inject.Module;

public class JCloudsSwift implements Closeable {
   private BlobStore storage;
   private RestContext<CommonSwiftClient, CommonSwiftAsyncClient> swift;

   public static void main(String[] args) {
      JCloudsSwift jCloudsSwift = new JCloudsSwift();

      try {
         jCloudsSwift.init();
         jCloudsSwift.listContainers();
         jCloudsSwift.close();
      }
      catch (Exception e) {
         e.printStackTrace();
      }
      finally {
         jCloudsSwift.close();
      }
   }
   
   private void init() {
      Iterable<Module> modules = ImmutableSet.<Module> of(
            new SLF4JLoggingModule());

      String provider = "swift-keystone";
      String identity = "demo:demo"; // tenantName:userName
      String password = "devstack"; // demo account uses ADMIN_PASSWORD too

      BlobStoreContext context = ContextBuilder.newBuilder(provider)
            .endpoint("http://172.16.0.1:5000/v2.0/")
            .credentials(identity, password)
            .modules(modules)
            .buildView(BlobStoreContext.class);
      storage = context.getBlobStore();
      swift = context.unwrap();
   }

   private void listContainers() {
      System.out.println("List Containers");
      Set<ContainerMetadata> containers = swift.getApi().listContainers();

      for (ContainerMetadata container: containers) {
         System.out.println("  " + container);
      }
   }

   public void close() {
      closeQuietly(storage.getContext());
   }
}

Compile and Run

javac -classpath ".:lib/*" JCloudsSwift.java

java -classpath ".:lib/*" JCloudsSwift

[logging output]
List Containers
[logging output]
  ContainerMetadata{name=...}
  ...

Next Steps

1. Try the example above with one of the public clouds. For the Rackspace Cloud init() becomes

private void init() {    
   Iterable modules = ImmutableSet. of(new SLF4JLoggingModule());
   Properties overrides = new Properties();
   overrides.setProperty(KeystoneProperties.CREDENTIAL_TYPE, CredentialTypes.PASSWORD_CREDENTIALS);
   overrides.setProperty(Constants.PROPERTY_API_VERSION, "2");

   String provider = "openstack-nova";
   String identity = "myUsername"; // userName
   String password = "myPassword"; 

   ComputeServiceContext context = ContextBuilder.newBuilder(provider)
         .endpoint("https://identity.api.rackspacecloud.com/v2.0/")
         .credentials(identity, password)
         .modules(modules)
         .overrides(overrides)
         .buildView(ComputeServiceContext.class);
   compute = context.getComputeService();
   nova = context.unwrap();
   zones = nova.getApi().getConfiguredZones();
}

1. Try using the "openstack-cinder" provider to list volumes (hint: see VolumeAndSnapshotApiLiveTest.testListVolumes()).
2. Have a look at how the optional extensions are handled (hint: see FloatingIPApiLiveTest.testListFloatingIPs()).
3. Change the example to do different things that you want to do.
4. Browse the documentation and have a look at the Javadoc.
5. Return to the Installation Guide and have a look at the different ways to integrate jclouds with your project.
6. Join the jclouds mailing list or maybe even the jclouds developer mailing list.

OpenStack Providers

This is a list of providers that work with OpenStack that you can use to build your Context.

• "openstack-nova"
• "openstack-keystone"
• "openstack-cinder"
• "swift-keystone"