SoftLayer: Getting Started Guide

This page helps you get started using the jclouds API with SoftLayer.

Currently, SoftLayer offers 3 main “cloud” flavours:

Starting from 1.8.0, Jclouds supports officially only Public Cloud Instances (CCI).

Getting Started

  1. Sign up for SoftLayer Cloud.
  2. Log in to the
  3. Get your Username and API Key:
  4. Ensure you are using a recent version of Java 6.
  5. Setup your project to include softlayer.
    • Get the dependencies org.jclouds.provider/softlayer using jclouds Installation.
  6. Start coding.

SoftLayer Compute

// Get a context with softlayer that offers the portable ComputeService API
ComputeServiceContext computeServiceContext = ContextBuilder.newBuilder("softlayer")
                      .credentials("username", "apiKey")
                      .modules(ImmutableSet.<Module> of(new Log4JLoggingModule(),
                                                        new SshjSshClientModule()))
                      .buildView(ComputeServiceContext.class);

ComputeService computeService = computeServiceContext.getComputeService();

// List availability zones
Set<? extends Location> locations = computeService.listAssignableLocations();

// List nodes
Set<? extends ComputeMetadata> nodes = computeService.listNodes();

// List hardware profiles
Set<? extends Hardware> hardware = computeService.listHardwareProfiles();

// List images
Set<? extends org.jclouds.compute.domain.Image> image  = computeService.listImages();

NB: "computeService.listImages()" returns operatingSystems from SoftLayer_Container_Virtual_Guest_Configuration.

// Create nodes with templates
Template template = computeService.templateBuilder().osFamily(OsFamily.UBUNTU).build();
Set<? extends NodeMetadata> groupedNodes = computeService.createNodesInGroup("myGroup", 2, template);

// Reboot images in a group
computeService.rebootNodesMatching(inGroup("myGroup"));

TemplateOptions and SoftLayerTemplateOptions

In jclouds, the standard mechanism to specify template options is by using the TemplateBuilder. This supports a number of configuration supported by all the api/provider jclouds

For example, the location id is used to specify the "region" provider where to spin your VM:

TemplateBuilder templateBuilder = context.getComputeService().templateBuilder();
templateBuilder.locationId("ams01");

If you need to specify a public image supported by SoftLayer can be referenced as follows:

templateBuilder.imageId("CENTOS_6_64");

If you want instead to specify a private image, you need to set the globalIdentifier of a VirtualGuestBlockDeviceTemplateGroup, like:

templateBuilder.imageId("3d7697d8-beef-437a-8921-5a2a18bc116f");

Notice, if you don't know the globalIdentifier upfront you can use the following curl command:

curl -uusername:apiKey https://api.softlayer.com/rest/v3/SoftLayer_Account/getBlockDeviceTemplateGroups?objectMask=children.blockDevices.diskImage.softwareReferences.softwareDescription

and use the globalIdentifier desired

jclouds is able to leverage SoftLayer CCI specific-options described at createObject by doing the following:

SoftLayerTemplateOptions options = template.getOptions().as(SoftLayerTemplateOptions.class);
// domain
options.domainName("live.org");
// multi-disk
options.blockDevices(ImmutableList.of(25, 400, 400));
// disk type (SAN, LOCAL)
options.diskType("SAN");
//tags
options.tags(ImmutableList.of("jclouds"));
// primaryNetworkComponent.networkVlan.id
options.primaryNetworkComponentNetworkVlanId(vlanId);
// primaryBackendNetworkComponent.networkVlan.id
options.primaryBackendNetworkComponentNetworkVlanId(backendVlanId);

NB: notice, vlandId and backendVlanId should be the internal IDs and not the vlan number! One can easily retrieve it from the SoftLayer web UI by clicking on VLAN number link of https://control.softlayer.com/network/vlans The url will show something like https://control.softlayer.com/network/vlans/1234567 where the vlanId is 1234567

Provider-specific APIs

When you need access to SoftLayer features, use the provider-specific context

SoftLayerApi api = computeServiceContext.unwrapApi(SoftLayerApi.class);
// and then get access to the delegate API groups
api.getVirtualGuestApi();
api.getDatacenterApi();
api.getSoftwareDescriptionApi();
api.getVirtualGuestBlockDeviceTemplateGroupApi();
api.getAccountApi();

// Be sure to close the context when done
computeServiceContext.close();

SoftLayer Object Storage

SoftLayer Object Storage is an OpenStack® based blobstore storage system.

// Get a context with softlayer that offers the portable BlobStore API
BlobStoreContext context = ContextBuilder.newBuilder("swift")
                 .credentials("tenantName:accessKey", "apiKey)
                 .endpoint("https://<locationId>.objectstorage.softlayer.net/auth/v1.0")
                 .buildView(BlobStoreContext.class);

// Create a container in the default location
context.getBlobStore().createContainerInLocation(null, container);

// Be sure to close the context when done
context.close();

For more examples, see Openstack documentation.