OpenStack4j > Documentation / Getting Started

General

OpenStack Services

Getting Started

This chapter will guide you through setup and some basic examples to get you going. For advance API coverage please refer to each topic within the overall guide.

Maven Configuration

If you are a Maven user just add the library as a dependency:

Latest Release (Stable)

Starting with version 3.0.0+ OpenStack4j now has the ability to choose the underlying connection framework. By default the API’s are configured to use the Jersey 2 connector. See optional configuration scenarios below:

Default Setup (Using Jersey2 as the connector choice)

<dependency>
  <groupId>com.github.openstack4j.core</groupId>
  <artifactId>openstack4j</artifactId>
  <version>3.3</version>
</dependency>

With Dependencies (all in one jar)

<dependency>
  <groupId>com.github.openstack4j.core</groupId>
  <artifactId>openstack4j</artifactId>
  <version>3.3</version>
  <classifier>withdeps</classifier>
</dependency>


Using version 3.0.0+ of OpenStack4j offers support for the Identity (Keystone) V3 API.

Default Setup (Using Jersey2 as the connector choice)

<dependency>
  <groupId>com.github.openstack4j.core</groupId>
  <artifactId>openstack4j</artifactId>
  <version>3.3</version>
</dependency>

With Dependencies (all in one jar)

<dependency>
  <groupId>com.github.openstack4j.core</groupId>
  <artifactId>openstack4j</artifactId>
  <version>3.3</version>
  <classifier>withdeps</classifier>
</dependency>


Using a Connector of Your Choice

1. Declare the openstack4j core dependency in your POM

<dependency>
  <groupId>com.github.openstack4j.core</groupId>
  <artifactId>openstack4j-core</artifactId>
  <version>3.3</version>
</dependency>

2. Declare a connector

<dependency>
  <groupId>com.github.openstack4j.core.connectors</groupId>
  <artifactId>[ connector artifactId ]</artifactId>
  <version>3.3</version>
</dependency>
Valid artifactId's are: openstack4j-jersey2, openstack4j-resteasy, openstack4j-okhttp, openstack4j-http-connector and openstack4j-httpclient

Snapshots (Current Development)

Usage of snapshots is the same as above except for the version tag. Copy any of the stable declarations above that suit your environment and replace the version tag with 3.4-SNAPSHOT.

Snapshot Dependencies Repository Configuration

Snapshots are not sync’d with maven central. To allow Maven to properly resolve the latest snapshot you will need to add the sonatype repository:

<repositories>
  <repository>
    <id>st-snapshots</id>
    <name>sonatype-snapshots</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </repository>
</repositories>

Example Maven project setup

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.cloudapp</groupId>
  <artifactId>my-cloudapp</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>com.github.openstack4j.core</groupId>
      <artifactId>openstack4j</artifactId>
      <version>3.4-SNAPSHOT</version>
    </dependency>
  </dependencies>
</project>

If you are not familiar with Apache Maven but would like to try it, when we recommend reading Maven in 5 Minutes

Required Runtime Dependencies

OpenStack4j requires some runtime dependencies in order to run. The easiest is to use the “-withdeps” version which has everything included. Otherwise refer to pom for most recent changes. In a later release we will be adding a slight modular approach allowing options to use Jersey 1 vs 2 and possibly another popular connector. For now refer to the needed dependencies for runtime if your not using the “-withdeps” jar.

Lets Play!

Let’s test your OpenStack deployment with the API. For advance coverage of the API please refer to the service of interest on the left navigation pane.

Authenticate

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClientV2 or OSClientV3 - depending on the Keystone version. The OSClientV2/OSClientV3 allows you to invoke Compute, Identity V2/V3, Neutron operations fluently.

In the example below we are specifying the OpenStack deployment endpoint to connect to, user credentials to authenticate and the default tenant we would like to be in context of.

Since OpenStack4j both version 3.0.0 version 2 and 3 of the Identity API are supported.

Version 2 Authentication

NOTE: OpenStack4j 3.0.0 introduced some breaking changes.
The Identity V2 API is no longer available with the OSClient but only with the new OSClientV2.

In previous OpenStack4j versions (2.x) V2 authentication was done by:

import org.openstack4j.api.OSClient;
import org.openstack4j.openstack.OSFactory;

OSClient os = OSFactory.builder()
        .endpoint("http://127.0.0.1:5000/v2.0")
        .credentials("admin", "test")
        .tenantName("admin")
        .authenticate();

V2 authentication in OpenStack4j 3.x is done the following way:

import org.openstack4j.api.OSClient.OSClientV2;
import org.openstack4j.openstack.OSFactory;

OSClientV2 os = OSFactory.builderV2()
        .endpoint("http://127.0.0.1:5000/v2.0")
        .credentials("admin","sample")
        .tenantName("admin")
        .authenticate();

Version 3 Authentication

NOTE: OpenStack4j 3.0.0 introduced some breaking changes.
The Identity V3 API is only available with the new OSClientV3.
import org.openstack4j.api.OSClient.OSClientV3;
import org.openstack4j.openstack.OSFactory;
import org.openstack4j.model.common.Identifier;

// use Identifier.byId("domainId") or Identifier.byName("example-domain")
Identifier domainIdentifier = Identifier.byId("domainId");

// unscoped authentication
// as the username is not unique across domains you need to provide the domainIdentifier
OSClientV3 os = OSFactory.builderV3()
        .endpoint("http://127.0.0.1:5000/v3")
        .credentials("admin","sample", domainIdentifier)
        .authenticate();

// project scoped authentication
OSClientV3 os = OSFactory.builderV3()
        .endpoint("http://127.0.0.1:5000/v3")
        .credentials("admin", "secret", Identifier.byName("example-domain"))
        .scopeToProject(Identifier.byId(projectIdentifier))
        .authenticate();

// domain scoped authentication
// using the unique userId does not require a domainIdentifier
OSClientV3 os = OSFactory.builderV3()
        .endpoint("http://127.0.0.1:5000/v3")
        .credentials("userId", "secret")
        .scopeToDomain(Identifier.byId(domainIdentifier))
        .authenticate();

// Scoping to a project just by name isn't possible as the project name is only unique within a domain.
// You can either use this as the id of the project is unique across domains
OSClientV3 os = OSFactory.builderV3()
        .endpoint("http://127.0.0.1:5000/v3")
        .credentials("userId", "secret")
        .scopeToProject(Identifier.byName(projectName), Identifier.byName(domainName))
        .authenticate();

// Or alternatively
OSClientV3 os = OSFactory.builderV3()
        .endpoint("http://127.0.0.1:5000/v3")
        .credentials("userId", "secret")
        .scopeToDomain(Identifier.byName(domainName))
        .authenticate();

Run some Queries

Now that we have successfully authenticated and have a client we will show you a few basic examples of grabbing data from the various services. These are high level and for full CRUD and management calls please refer to each individual service guide.

// Find all Users
List<? extends User> users = os.identity().users().list();

// List all Tenants
List<? extends Tenant> tenants = os.identity().tenants().list();

// Find all Compute Flavors
List<? extends Flavor> flavors = os.compute().flavors().list();

// Find all running Servers
List<? extends Server> servers = os.compute().servers().list();

// Suspend a Server
os.compute().servers().action("serverId", Action.SUSPEND);

// List all Networks
List<? extends Network> networks = os.networking().network().list();

// List all Subnets
List<? extends Subnet> subnets = os.networking().subnet().list();

// List all Routers
List<? extends Router> routers = os.networking().router().list();

// List all Images (Glance)
List<? extends Image> images = os.images().list();

// Download the Image Data
InputStream is = os.images().getAsStream("imageId");

As you can see in the examples above we have exercised a small portion of the following services (Identity, Computer, Network and Image).

FAQ

Logging

Logging of HTTP communication can be enabled via

OSFactory.enableHttpLoggingFilter(true);

Resolver

Once authenticated, OpenStack services obtain their respective endpoint from a catalog using a default Resolver. This logic can be overridden by defining a custom ServiceVersionResolver

// define custom ServiceVersionResolver
final ServiceVersionResolver resolver = new ServiceVersionResolver() {
    @Override
    public Service resolve(ServiceType type, SortedSet<? extends Service> services) {
        // resolver logic; possibly ext. default logic
        return endpoint;
    }
};

// apply resolver to client
OSClient.withConfig(Config.newConfig().withResolver(resolver))

Endpoint URL Resolver

Resolving and endpoint URL is by default based on the Service Type and Facing perspective. The default logic can be overridden by a custom EndpointURLResolver

// define a custom EndpointURLResolver
final EndpointURLResolver endpointUrlResolver = new EndpointURLResolver() {
  @Override
  public String findURLV3(URLResolverParams arg0) {
    // logic for V3
    return null;
  }

  @Override
  public String findURLV2(URLResolverParams arg0) {
    // logic for V2
    return null;
  }
};

// apply resolver to client
OSClient.withConfig(Config.newConfig().withEndpointURLResolver(resolver));