Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Force GitHub README to respect dark mode (function() { var style = document.createElement('style'); style.textContent = ' .markdown-body { color-scheme: dark light; } .markdown-body pre { background: #161b22 !important; } .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; } .markdown-body table th, .markdown-body table td { border-color: #30363d !important; } .markdown-body img { background: #0d1117; } .markdown-body blockquote { border-left-color: #8b949e; } .markdown-body hr { border-color: #30363d; } '; document.head.appendChild(style); })(); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Highlight search terms from Google/DuckDuckGo/Bing referrer (function() { var ref = document.referrer; var terms = []; if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) { var url = new URL(ref); var q = url.searchParams.get('q') || url.searchParams.get('p'); if (q) { terms = q.split(/\s+/).filter(function(t) { return t.length > 2; }); } } if (terms.length === 0) return; var style = document.createElement('style'); style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }'; document.head.appendChild(style); function highlight(node) { if (node.nodeType === 3) { // text node var text = node.textContent; var found = false; terms.forEach(function(term) { var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ' GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Universal Dark Mode - works on any site (function() { var enabled = true; function applyDarkMode() { if (!enabled) return; // Create style element if it doesn't exist var style = document.getElementById('universal-dark-mode-style'); if (!style) { style = document.createElement('style'); style.id = 'universal-dark-mode-style'; document.head.appendChild(style); } // Dark mode CSS - inverts colors but preserves images/video style.textContent = ' /* Invert everything except media */ html { filter: invert(1) hue-rotate(180deg) !important; background: #1a1a2e !important; } /* Restore images, videos, iframes, canvas */ img, video, iframe, canvas, svg, picture, [style*="background-image"] { filter: invert(1) hue-rotate(180deg) !important; } /* Preserve specific elements that should not be inverted */ .no-dark-mode, .no-dark-mode *, [data-theme="light"], [data-theme="light"], .ace_editor, .ace_editor *, .CodeMirror, .CodeMirror *, .monaco-editor, .monaco-editor *, .markdown-body pre, .markdown-body pre *, .highlight, .highlight *, pre code, pre code * { filter: none !important; } /* Fix common UI elements */ .modal, .popup, .dropdown-menu, .tooltip, .popover { filter: invert(1) hue-rotate(180deg) !important; background: #2d2d44 !important; border-color: #444 !important; } /* Scrollbars */ ::-webkit-scrollbar { background: #1a1a2e !important; } ::-webkit-scrollbar-thumb { background: #444 !important; } ::-webkit-scrollbar-thumb:hover { background: #555 !important; } /* Selection */ ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; } ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; } '; } function removeDarkMode() { var style = document.getElementById('universal-dark-mode-style'); if (style) style.remove(); } // Toggle with Alt+Shift+D document.addEventListener('keydown', function(e) { if (e.altKey && e.shiftKey && e.key === 'D') { e.preventDefault(); enabled = !enabled; if (enabled) { applyDarkMode(); console.log('[Universal Dark Mode] Enabled'); } else { removeDarkMode(); console.log('[Universal Dark Mode] Disabled'); } } }); // Apply on load applyDarkMode(); // Re-apply on dynamic content var observer = new MutationObserver(function(mutations) { if (enabled && !document.getElementById('universal-dark-mode-style')) { applyDarkMode(); } }); observer.observe(document.head, { childList: true }); console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle'); })(); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })(); GitHub - simonklb/openstack4j: A Fluent OpenStack SDK / Client Library for Java · GitHub
Skip to content

Repository files navigation

OpenStack4j

Build StatusLicenseGitter

OpenStack4j is a fluent OpenStack client that allows provisioning and control of an OpenStack deployment. This includes support for Identity, Compute, Image, Network, Block Storage, Telemetry, Data Processing as well as many extensions (LBaaS, FWaaS, Quota-Sets, etc)

Documentation and Support

Bug Reports

Requirements

  • OpenStack4j 3.0.X - Java 7 (JDK 8 preferred)
  • OpenStack4j 2.0.X - Java 7

Maven

Latest Release (Stable)

Maven Central

OpenStack4j version 2.0.0+ is now modular. One of the benefits to this is the ability to choose the connector that you would like to use in your environment.

Using OpenStack4j with the default Jersey2 Connector

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.1</version>
</dependency>

Using OpenStack4j with one of our connector modules

To configure OpenStack4j to use one of our supported connectors (Jersey 2, Resteasy, Apache HttpClient, OKHttp) see the usage guide

Current (Master Branch)

See notes above about connectors (same rules apply) to development branches.

<dependency>
<groupId>org.pacesys</groupId>
<artifactId>openstack4j</artifactId>
<version>3.0.2-SNAPSHOT</version>
</dependency>

A note about referencing Snapshots without Source

Snapshots are deploys to sonatype. We automatically deploy snapshots on every merge into the master branch. Typically 5 - 10 snapshot releases before an official release.

You will need to add the repository to your POM or Settings file. Releases (above) are deployed to maven central and this step is not required.

Example POM based repository declaration to grab snapshots:

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

Contributing

If you would like to contribute please see our contributing guidelines

Top 15 Contributors

RankLoginContributions
1@gondor527
2@auhlig57
3@octupszhang26
4@gonzolino18
5@ekasitk17
6@magixyu17
7@maxrome12
8@isartcanyameres9
9@iviireczech8
10@n-r-anderson7
11@krishnabrucelee6
12@peter-nordquist4
13@RibeiroAna4
14@symcssn4
15@olivergondza5

Throughput

Throughput Graph

Quick Usage Guide

Below are some examples of the API usage. Please visit www.OpenStack4j.com for the full manual and getting started guides.

Authenticating

OpenStack4j 3.0.0+ supports Identity (Keystone) V3 and V2.

OpenStack4j 3.0.0 introduced some breaking changes. The legacy Identity V2 API now uses the class OSClientV2 in place of the class OSClient.

Using Identity V2 authentication:
// Identity V2 Authentication ExampleOSClientV2os = OSFactory.builderV2()
.endpoint("http://127.0.0.1:5000/v2.0")
.credentials("admin","sample")
.tenantName("admin")
.authenticate();
Using Identity V3 authentication

Creating and authenticating against OpenStack is extremely simple. Below is an example of authenticating which will result with the authorized OSClient. OSClient allows you to invoke Compute, Identity, Neutron operations fluently.

You can use either pass the users name or id and password in the following way

.credentials("username", "secret", Identifier.byId("domain id"))

or

.credentials("user id", "secret")

to provide credentials in each of the following cases.

Using Identity V3 authentication you basically have 4 options:

(1) authenticate with project-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToProject(Identifier.byId("project id"))
.authenticate());

(2) authenticate with domain-scope

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("admin", "secret", Identifier.byId("user domain id"))
.scopeToDomain(Identifier.byId("domain id"))
.authenticate());

(3) authenticate unscoped

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.credentials("user id", "secret")
.authenticate();

(4) authenticate with a token

OSClientV3os = OSFactory.builderV3()
.endpoint("http://<fqdn>:5000/v3")
.token("token id")
.scopeToProject(Identifier.byId("project id"))
.authenticate());

Identity Operations (Keystone) V3

After successful v3 - authentication you can invoke any Identity (Keystone) V3 directly from the OSClientV3.

Identity Services fully cover User, Role, Project, Domain, Group,.. service operations (in progess).
The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV3.

User operations

// Create a User associated to the new ProjectUseruser = os.identity().users().create(Builders.user()
.domainId("domain id")
.name("foobar")
.password("secret")
.email("foobar@example.com")
.enabled(true)
.build());
//orUseruser = os.identity().users().create("domain id", "foobar", "secret", "foobar@example.org", true);
// Get detailed info on a user by idUseruser = os.identity().users.get("user id");
//or by name and domain identifierUseruser = os.identity().users.getByName("username", "domain id");
// Add a project based role to the useros.identity().roles().grantProjectUserRole("project id","user id", "role id");
// Add a domain based role to the useros.identity().roles().grantDomainUserRole("domain id","user id", "role id");
// Add a user to a groupos.identity().users().addUserToGroup("user id", "group id");

Role operations

// Get a list of all rolesos.identity().roles().list();
// Get a role by nameos.identity().roles().getByName("role name);

Project operations

// Create a projectos.identity().project().create(Builders.project()
.name("project name")
.description("project description")
.domainId("project domain id")
.enabled(true)
.build());

Identity Operations (Keystone) V2

After successful v2 - authentication you can invoke any Identity (Keystone) V2 directly from the OSClientV2.

Identity V2 Services fully cover Tenants, Users, Roles, Services, Endpoints and Identity Extension listings. The examples below are only a small fraction of the existing API so please refer to the API documentation for more details.

NOTE: The os used here is an instance of org.openstack4j.api.OSClient.OSClientV2.

Create a Tenant, User and associate a Role

// Create a Tenant (could also be created fluent within user create)Tenanttenant = os.identity().tenants().create(Builders.identityV2().tenant().name("MyNewTenant").build());
// Create a User associated to the new TenantUseruser = os.identity().users().create(Builders.identityV2().user().name("jack").password("sample").tenant(tenant).build());
// Add a Tenant based Role to the Useros.identity().roles().addUserRole(tenant.getId(), user.getId(), os.identity().roles().getByName("Member").getId());

Compute Operations (Nova)

OpenStack4j covers most the major common compute based operations. With the simplistic API approach you can fully manage Servers, Flavors, Images, Quota-Sets, Diagnostics, Tenant Usage and more. As the API evolves additional providers and extensions will be covered and documented within the API.

Create a Flavor and Boot a Server/VM

// Create a Flavor for a special customer baseFlavorflavor = os.compute().flavors()
.create(Builders.flavor().name("Gold").vcpus(4).disk(80).ram(2048).build());
// Create and Boot a new Server (minimal builder options shown in example)Serverserver = os.compute().servers()
.boot(Builders.server().name("Ubuntu 2").flavor(flavor.getId()).image("imageId").build());

Create a new Server Snapshot

StringimageId = os.compute().servers().createSnapshot(server.getId(), "Clean State Snapshot");

Server Diagnostics

Diagnostics are usage information about the server. Usage includes CPU, Memory and IO. Information is dependant on the hypervisor used by the OpenStack installation. As of right now there is no concrete diagnostic specification which is why the information is variable and in map form (key and value)

Map<String, ? extendsNumber> diagnostics = os.compute().servers().diagnostics("serverId");

Networks (Neutron)

Network Operations

// List the networks which the current authorized tenant has access toList<? extendsNetwork> networks = os.networking().network().list();
// Create a NetworkNetworknetwork = os.networking().network()
.create(Builders.network().name("MyNewNet").tenantId(tenant.getId()).build());

Subnet Operations

// List all subnets which the current authorized tenant has access toList<? extendsSubnet> subnets = os.networking().subnet().list();
// Create a SubnetSubnetsubnet = os.networking().subnet().create(Builders.subnet()
.name("MySubnet")
.networkId("networkId")
.tenantId("tenantId")
.addPool("192.168.0.1", "192.168.0.254")
.ipVersion(IPVersionType.V4)
.cidr("192.168.0.0/24")
.build());

Router Operations

// List all RoutersList<? extendsRouter> = os.networking().router().list();
// Create a RouterRouterrouter = os.networking().router().create(Builders.router()
.name("ext_net").adminStateUp(true).externalGateway("networkId").build());

Image Operations (Glance)

Basic Operations

// List all ImagesList<? extendsImage> images = os.images().list();
// Get an Image by IDImageimage = os.images().get("imageId");
// Delete a Imageos.images().delete("imageId");
// Update a ImageImageimage = os.images().get("imageId");
os.images().update(image.toBuilder()
.name("New VM Image Name").minDisk(1024).property("personal-distro", "true"));

Download the Image Data

InputStreamis = os.images().getAsStream("imageId");

Create a Image

// (URL Payload in this example, File, InputStream are other payloads available)Imageimage = os.images().create(Builders.image()
.name("Cirros 0.3.0 x64")
.isPublic(true)
.containerFormat(ContainerFormat.BARE)
.diskFormat(DiskFormat.QCOW2)
.build()
), Payloads.create(newURL("https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img")));

License

This software is licensed under the Apache 2 license, quoted below.
Copyright 2016 ContainX and OpenStack4j
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

About

A Fluent OpenStack SDK / Client Library for Java

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages