Nucleus

Nucleus is a RESTful abstraction layer and Ruby gem to unify core management functions of Platform as a Service (PaaS) systems.

The API is build using Ruby and the grape framework. It provides fully compliant swagger schemas that serve for documentation and client generation.

• Supported Vendors
• Usage
  • Ruby Interpreter Compatibility
  • Installation instructions
  • Use in your application
  • Use the API
    • Start the server
    • API endpoints
• Functionality
  • Authentication
    • Special characters (umlauts, ....)
  • Core constructs
    • Vendors
    • Providers and Endpoints
  • Custom API calls (experimental)
    • Execute a custom API call against the endpoint
    • Execute a custom API call against an endpoint's application
• Adapters
  • Heroku
  • Cloud Foundry v2
  • Openshift v2
• Configuration
  • Vendors, Providers and Endpoints
  • Application configuration
• API client(s)
  • Accept Header
  • Error codes
  • Language specific clients
• Tests
• Schema validation
• Versioning
• Security
• Project structure
• Contributing
• Further documentation

• Heroku
• Cloud Foundry (v2)
  • AppFog, Anynines, IBM Bluemix, Pivotal Web Services, HP Helion
• Openshift (v2)
  • OpenShift Online, getup Cloud

More information on the vendors and the associated adapter can be found in the adapters section.

Nucleus can either be used as standalone application/service, or as part of another ruby application. Please make sure to obey the following installation instructions before starting to use Nucleus.

Nucleus is supposed to run on Ruby >= 2.3. Due to native gem dependencies, it currently won't work on JRuby.

1. The following executables must be available on the system's PATH:

   git, ssh

Unix systems should run fine out of the box, whereas Windows systems might need some adjustments:

Both required executables should be located in the Git/bin installation directory of msysGit. Nucleus is verified to work with msysGit and the included version of OpenSSH. We did not verify other alternatives, e.g. PuTTY's plink.exe. PuTTY is supposed to not work due to the lack of the -o UserKnownHostsFile=NUL -o StrictHostKeyChecking=no options that allow to connect any git repository without confirmation of the host's identity.

Eventmachine:

Eventmachine sometimes fails with the error Encryption not available on this event-machine. A fix is available, but requires a few steps:

1. Uninstall the gem

$ gem uninstall eventmachine

2. Download the OpenSSL package from http://packages.openknapsack.org/openssl/openssl-1.0.0k-x86-windows.tar.lzma

3. Extract it to a desired location

4. Re-install the gem and point to the OpenSSL installation directory. Escape backslashes or use forward slashes.

$ gem install eventmachine -- --with-ssl-dir=C:/SSL

Add a dependency on the Nucleus gem, for instance in your application's Gemfile,

gem 'nucleus'

upon which you would update your bundle.

$ bundle install

Or install the gem by yourself:

$ gem install nucleus

Finally, require the gem inside your application

require 'nucleus'

1. Configuration [optional]

Adapt the configuration to your needs and adjust the values via the global nucleus_config variable. The configuration must be changed before initializing the AdapterResolver, otherwise the configuration is locked and can't be changed anymore.

For more information have a look at the configuration section.

2. Show all currently available API versions:

Nucleus::VersionDetector.api_versions

3. Instantiate an AdapterResolver for the desired API version:

resolver = Nucleus::AdapterResolver.new('v1')

4. Show all adapters that are supported by Nucleus by this specific API version:

resolver.adapters

{ "cloud_foundry_v2"=>Nucleus::Adapters::V1::CloudFoundryV2, "heroku"=>Nucleus::Adapters::V1::Heroku, "openshift_v2"=>Nucleus::Adapters::V1::OpenshiftV2 }

5. Load your desired adapter implementation:

adapter = resolver.load('cloud_foundry_v2', 'api.pivotal.io', 'your_username', 'your_password')

By default, the adapter will be populated with the default configuration options that are defined in the vendor's configuration for the selected endpoint_url. If you are using a custom installation, e.g. of OpenShift or Cloud Foundry, make sure to pass the option that describes the app_domain for deployed applications. Otherwise, the web_url links created by Nucleus will be malformed.

minimal = resolver.load('heroku', 'your_username', 'your_password')
adapter = resolver.load('cloud_foundry_v2', 'api.example.org', 'your_username', 'your_password', app_domain: 'apps.example.org', check_ssl: false)

6. Start using the platform and invoke commands:

# Show available regions
adapter.regions
# Create our first application
app = adapter.create_application(region: 'default', name: 'myusersfirstapplication', runtimes: ['nodejs'])
# And delete the application again
adapter.delete_application(app[:id])

Check the documentation of the Nucleus::Adapters::V1::Stub adapter (or any other API version) for a complete list of supported actions. You can also refer to the documentation of the REST interface to get detailed information about the parameter options of post and put commands, including which fields are required and those that are only optional.

Besides including the abstraction layer in your application, Nucleus can also be started and serve a RESTful API: For detailed usage information go to the section API client(s).

The easiest way to run the API is via Docker Hub.

docker pull stfnklb/nucleus
docker run -it -p 9292:9292 nucleus

The server is exposed at localhost:9292 by default.

Or build it on your own. Be aware that there might be issues with line endings inside the configuration files, if you check out Windows or legacy macOS line endings instead of Linux LF line endings.

$ docker build -t nucleus .
$ docker run -it -p 9292:9292 nucleus

If you want to run Nucleus locally without Docker here's how to do it. A rack server can be started in multiple ways. The most convenient solution is to use the provided script:

$ ./bin/nucleus

However, you can also start the API using the thin server:

$ rackup -s thin config.ru

Due to limitations in the log tailing process, Nucleus currently requires thin and does not work on other Rack servers. In theory, it should be possible to make other Rack servers work that also utilize eventmachine.

We highly encourage you to only use https connections when your application is running in production or used outside of your local computer. This is due to the fact that all passwords are passed via the HTTP basic authentication, which does not encrypt your data so that any third party could log and identify your credentials.

To enforce this policy, Nucleus will automatically redirect all connections on plain HTTP to HTTPS connections if it is running in production (detected via RACK_ENV).

The API of Nucleus is documented via swagger. After you started a server instance, you can access an interactive swagger-ui at the /docs path.

The following list shows the degree to which the adapters implement the offered methods. This list can be auto-generated via:

$ bundle exec rake evaluation:compatibility:markdown

State: 3/7/2016

Nucleus could support any constellation of PaaS offers that are currently available. In order to do so, we differentiate between between vendors, providers, and endpoints:

A vendor is the organization that developed the platform software, which also determines the offered functionalities. A provider runs the platform, which always has at least one endpoint.

For most scenarios the endpoint is identical to the provider, but in some cases, for instance on IBM Bluemix, endpoints distinguish different deployment regions.

If running Nucleus as web service, all changes made to these entities at runtime will be discarded, unless you enable persistence functionality in the configuration and specify a location where to persist the data to.

You can use the API of Nucleus to show a list of all supported vendors. This request is publicly available and does not require any authentication.

However, you cannot create, delete or update a vendor at runtime because it represents the logic to communicate with the associated platform. All developers that want to have more information on how to add a new vendor, please see the instructions: Add a vendor (or implement a new adapter)

Providers and Endpoints can be managed without authentication and support GET, POST, PATCH, DELETE requests.

A new entity can be registered at runtime by sending a POST request. Whereas a provider only requires a name, an endpoint also needs the url as further attribute. Please refer to the swagger-ui documentation for additional information about the requests.

Authentication against the endpoint is managed by Nucleus. The credentials must be provided as Basic authentication header within each single request. Heroku requires a combination of username:apikey instead of username:password!

Authorization: Basic thebase64encodedcredentialsstring

The usage of special characters, for instance german umlauts may cause issues with some platforms. Please make sure to select the correct encoding for your credentials before encoding them with Base64:

• Stackato 3.4.2: Different encodings cause the requests to crash and return status 500

Below are some examples how to use the API in order to obtain detailed application logs.

curl -X "GET" "http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/{log_id}/download" -H "Authorization: {auth_header}" -O -J

curl -X "GET" "http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/download" -H "Authorization: {auth_header}" -O -J

curl -X "GET" "http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/{log_id}/tail" -H "Authorization: {auth_header}" --raw -v

Sometimes you might want to call proprietary functionality that goes beyond Nucleus' unified API approach. You can also execute such custom API calls against the endpoint's API with Nucleus. This feature is included as experimental functionality and does not return unified objects or errors. The response of the API is passed 1:1 to the REST client.

The custom calls can be made either against the endpoint or against an application. Allowed HTTP methods are GET, POST,PATCH, PUT and DELETE. Data embedded in a requests body is used 1:1 in the API call, header information are going to be discarded.

Please be aware that you must also include the API version in the path if required by the platform. For instance, Cloud Foundry requests would have to look like: .../call/v2/app_usage_events

In this example, we want to get the current user's account information. Therefore, we append the call action to the endpoint, followed by the API's native path to the resource: account

GET /api/endpoints/heroku/call/account

{
  "allow_tracking": true,
  "beta": false,
  "email": "theusersemail@provider.domain",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "last_login": "2014-11-25T08:52:59Z",
  "name": " ",
  "two_factor_authentication": false,
  "verified": false,
  "created_at": "2014-11-18T09:37:21Z",
  "updated_at": "2015-02-18T18:57:33Z",
  "default_organization": null
}

In this example we try to list the builds of an Heroku application. Therefore, we append the call action to the application at the endpoint, followed by the API's native path to the resource: builds

GET /api/endpoints/heroku/applications/the_application_name/call/builds

The response is the unprocessed response of the Heroku API as shown in the previous example.

The functionality to communicate with different platforms is implemented in so called adapters. However, not each adapter can fully support the abstract Nucleus definitions. Please refer to the functionality section for more information about the supported features.

Providers: Heroku

Heroku requires a combination of username:apikey instead of username:password for authentication!

Providers: AppFog, Anynines, IBM Bluemix, Pivotal Web Services, HP Helion

Logs

CF stopped to provide the stdout and stderr files in the logs directory. Currently, we do not know of an approach to fetch recent log entries without registering an additional service on the application.

Moreover, logs can only be retrieved as long as at least once instance of the CF application is running, hence the application state is running. If there are no logs that can be retrieved, the log list will be empty and the request for a particular log file will result in an 404 error.

Services

• As of now, we only allow bindable services and create a new instance of the service to add
• Therefore, services must be active and bindable
• Only one instance of the same service can be bound to the application

Providers: OpenShift Online, getup Cloud

Application update

An application can't be updated, the name and runtimes can't be changed once created.

Application scaling

Applications not created with Nucleus can't be scaled if they were created with the attribute scalable = false

Services

• Services can be added to the application, but scaling (gears, memory allocation, ...) and further configuration are not supported as of now.
• We focus on the embedded cartridges and omit standalone services such as Jenkins.
• With no service plans and therefore nothing to change, the change service function is not implemented.

Performance

Recording is really slow. Even worse, actions quite often fail with Openshift internal timeouts.

Several parts of Nucleus can be configured, e.g. whether to persist your data or always start with a clean instance. There are two different locations at which the configuration files can be placed. They are described with increasing importance, meaning that the last option overwrites keys that were also configured in the previous files:

1. A file in user account's home directory. On UNIX systems this file must be placed at ~/.nucleus/nucleus_config.rb, whereas it is expected at ~/nucleus/nucleus_config.rb if running Windows.
2. The config/nucleus_config.rb file in the project's directory

A vendor is reflected by an adapter implementation, but the providers and their endpoints can either be changed at runtime or via .yaml configuration files. These adapter configuration files are located in the project directory at config/adapters.

To add a new provider, open the config/adapters directory and select the platform that the provider is using. For more explanations of the fields, or if the platform is not listed, please refer to the Guide how to implement a new adapter).

Next, add your provider and its endpoint(s) to the configuration file.

  ---
  name: "Openshift 2"
  id: "openshift_v2"
  providers:
    -
      name: "Openshift Online"
      id: "openshift-online"
      endpoints:
        -
          name: "Openshift Online"
          id: "openshift-online"
          url: "openshift.redhat.com/broker/rest"

The API can be used with the REST client of your choice.

Nucleus always uses the latest API version if no Accept header is specified. We therefore strongly encourage you to always specify the Accept header. The vendor thereby must be set to nucleus and the version must be available. Otherwise an error with the HTTP status 406 is returned. A sample Accept header would be:

Accept = application/vnd.nucleus-v1

The application uses the following subset of error codes:

400: Bad Request
401: Unauthorized
404: Resource not found
406: API vendor or version not found
422: Unprocessable Entity due to invalid parameters
500: Internal processing error
501: Not implemented, adapter does not provide this feature
503: Destination service temporarily unavailable
504: Gateway Time-out

All errors are returned in a common schema:

{
  "status": HTTP_STATUS_CODE,
  "message": SIMPLE_ERROR_MESSAGE,
  "dev_message": DEVELOPER_MESSAGE_WITH_TECHNICAL_DETAILS_TO_RESOLUTION,
  "error_code": UNIQUE_ERROR_CODE,
  "more_info": LINK_TO_DOCUMENTATION_DESCRIBING_THE_ERROR
}

As of now, there is no language-specific API client available. As a reward of providing swagger-compatible API docs, clients can be generated for several languages. For detailed information, please have a look at the swagger-codegen project.

The tests are divided into 3 categories, unit, integration and adapter tests. You can either call all tests or each suite separately.

bundle exec rake spec
bundle exec rake spec:suite:unit
bundle exec rake spec:suite:integration
bundle exec rake spec:suite:adapters

The generated schema can be validated against the swagger specification. Please have a look at the swagger-codegen project.

Nucleus follows the Semantic Versioning standard. Therefore, Nucleus also allows to serve multiple versions of the API and provide legacy support.

However, be aware that each non-backward compatible change of the application must result in an increase of the major version.

Until the first release (v1), the initial version is: 0.1.0.

As described in the HTTPS section, we strongly encourage you to only run Nucleus with HTTPS.

Nucleus uses the SSH key authentication for Git deployments. The private (!) key that will be used is located at config/nucleus_git_key.pem. Using the pre-generated key mitigates issues with the key usage/generation on various platforms. To prevent abuse we register the key before each command and immediately remove the key once the command has been executed.

To improve the security of your deployment, you can use your own custom private key. To do so, set the nucleus_config.ssh.custom_key option in the common configuration to the location of the private key file. For reasons of automation, the key must not be password encrypted.

bin # Binary startup files and GIT__SSH env. agents
config # Configuration files for Nucleus and its adapters
doc # Generated YARD documentation
lib # The Nucleus application source code
lib/nucleus # Gem compatible directory of the core, includes the AdapterResolver class
lib/nucleus/adapters # The adapter implementations to communicate with the vendor's platforms, grouped by API version.
lib/nucleus/core # All other functionality used throughout the application, but rather unrelated to the Grape API: http requests, authentication, errors, etc.
lib/nucleus/ext # Monkey patched classed and extensions
lib/nucleus/scripts # Initialization scripts, bootstrapping and shutdown hooks
lib/nucleus_api/api # Everything that is directly related to the RESTful Grape API: entities, embedded helpers and the actual API version's definitions
lib/nucleus_api/ext # Monkey patched classed and extensions related only to the API
lib/nucleus_api/import # Import management of the adapter configuration files
lib/nucleus_api/persistence # The persistence layer, including the DAOs and the entity's models (Vendor, Provider, Endpoint, ...)
lib/nucleus_api/rack_middleware # Rack middleware layers for authentication, request ids and logging
lib/nucleus_api/scripts # Initialization scripts, bootstrapping, rackup and shutdown hooks of the API
public # public directory for rack, hosts the swagger-ui files for the live API documentation
schemas # Kwalify schemas, used to parse the configuration and load new vendors at startup
spec # All rspec test suites
tasks # Rake tasks, mostly related to generate tables and statistics
wiki # Further documentation files

We love contributions from everyone! See our contribution guidelines for details.

• Add a vendor (or implement a new adapter)
• Adapter Tests

The technical report "Nucleus - Unified Deployment and Management for Platform as a Service" explaining the details of our implementation is available here. Nucleus also has been used in the the paper "Unified Cloud Application Management" which was presented at the 12th IEEE World Congress on Services in San Francisco, USA. You can find a preprint version of the paper here.