Welcome to Solum’s documentation!¶

Contents:

Solum¶

Application Lifecycle Management

An OpenStack related project designed to make cloud services easier to consume and integrate into your application development process.

Overview¶

Solum is natively designed for OpenStack clouds and leverages numerous OpenStack projects, including Heat, Keystone, Nova, Trove, and more. We value vendor neutrality, open design and collaboration, and leveraging existing solutions where possible. One example is our use of Docker for deployment of containers. Multiple language run-time environments will be supported with a modular “language pack” solution so you can easily run applications written in any language of your choice.

Free software: Apache 2.0 License. See LICENSE file.
Documentation: http://wiki.openstack.org/wiki/Solum

Getting started with Solum¶

See the getting_started guide.

Project Info¶

Web-site: http://solum.io/

Source Code: http://github.com/stackforge/solum

Wiki: https://wiki.openstack.org/wiki/Solum

Launchpad: https://launchpad.net/solum

Blueprints: https://blueprints.launchpad.net/solum

Bugs: https://bugs.launchpad.net/solum

Code Reviews: https://review.openstack.org/#q,status:open+solum,n,z

IRC: #solum at freenode

Solum Quick Start Guide¶

The following is a guide to deploying an app with Solum.

Overview¶

$ solum languagepack create <NAME> <GIT_REPO>
$ solum languagepack show <UUID\Name>
$ solum languagepack logs <UUID>
$ solum languagepack list
$ solum app create --plan-file <plan_file> [--param-file param_file]
$ solum assembly show <assembly_uuid>
$ curl <application_uri>

Vagrant Demo Environment¶

We strongly recommend using this approach if you are setting up Solum for the first time.

Follow the Solum Demo Instructions

In this document we will work with a python example to demonstrate how you can use solum to deploy an application.

Create a languagepack¶

Before deploying an app on Solum, we need to create a run time environment, called languagepack, for the application. To learn more, see the languagepacks section of this document.

$ solum languagepack create python https://github.com/rackspace-solum-samples/solum-languagepack-python.git
+-------------+--------------------------------------+
| Property    | Value                                |
+-------------+--------------------------------------+
| status      | PENDING                              |
| description | None                                 |
| uuid        | 96f889e7-e8db-4ae3-a38d-0bfda8268e30 |
| name        | python                               |
+-------------+--------------------------------------+

Solum takes a few minutes to build your languagepack. You can check the state by using the languagepack show command. A languagepack is ready for use once the state changes to ‘READY’.

$ solum languagepack show 96f889e7-e8db-4ae3-a38d-0bfda8268e30
+-------------+--------------------------------------------------------------------------+
| Property    | Value                                                                    |
+-------------+--------------------------------------------------------------------------+
| status      | READY                                                                    |
| source_uri  | https://github.com/rackspace-solum-samples/solum-languagepack-python.git |
| description | None                                                                     |
| uuid        | 96f889e7-e8db-4ae3-a38d-0bfda8268e30                                     |
| name        | python                                                                   |
+-------------+--------------------------------------------------------------------------+

You can check logs that were generated while building the languagepack with the following command. This is a great way to debug your languagepack if it fails to build.

$ solum languagepack logs 96f889e7-e8db-4ae3-a38d-0bfda8268e30
+--------------------------------------+-----------------------------------------------------------------------------+
| resource_uuid                        | local_storage                                                               |
+--------------------------------------+-----------------------------------------------------------------------------+
| 96f889e7-e8db-4ae3-a38d-0bfda8268e30 | /var/log/solum/worker/languagepack-840d51c0-7a4d-4a3c-a2af-452de076eed8.log |
+--------------------------------------+-----------------------------------------------------------------------------+

You can find all available languagepacks with the following command

$ solum languagepack list
+--------------------------------------+--------+-------------+--------+--------------------------------------------------------------------------+
| uuid                                 | name   | description | status | source_uri                                                               |
+--------------------------------------+--------+-------------+--------+--------------------------------------------------------------------------+
| 95310b74-b3ed-4150-b0bf-e64c21359900 | java   | None        | READY  | https://github.com/rackspace-solum-samples/solum-languagepack-java.git   |
| 96f889e7-e8db-4ae3-a38d-0bfda8268e30 | python | None        | READY  | https://github.com/rackspace-solum-samples/solum-languagepack-python.git |
+--------------------------------------+--------+-------------+--------+--------------------------------------------------------------------------+

Create your app¶

Solum clones code from the user’s public Git repository or user’s public/private GitHub repository. Before you begin, push your code to a Git repo. From within your devstack host, you can now run solum commands to build and deploy your application.

2. To register an app with Solum, you will need to write a planfile to describe it. The following plan file deploys a sample python application. You can find other examples in the examples/plans/ folder of the solum repo on github. To learn more, see the planfile section of this document.

version: 1
name: python-sample-app
description: Sample Python web app.
artifacts:
- name: python-sample-app
  content:
    href: https://github.com/rackspace-solum-samples/solum-python-sample-app.git
  language_pack: python
  unittest_cmd: pip install -r test-requirements.txt; pep8 app.py
  run_cmd: ./main.sh
  ports: 80

The app is named python-sample-app, and it describes a single application, running the code from the given Github repo. The code in that repo is a Python app that listens for HTTP requests and returns environment variables supplied by the user during app creation. We have configured this example to listen on port 80.

Deploy your app¶

3. Authenticate to Keystone. The easiest way is to use the credentials supplied by Devstack.

$ source ~/devstack/openrc

4. Create an app by supplying the planfile. This registers your app with Solum. For demonstration purposes, we will use the provided example.

$ solum app create --plan-file planfile.yaml --param-file params.yaml
+-------------+---------------------------------------------------------------------+
| Property    | Value                                                               |
+-------------+---------------------------------------------------------------------+
| description | Sample Python web app.                                              |
| uri         | http://10.0.2.15:9777/v1/plans/4a795b99-936d-4330-be4d-d2099b160075 |
| name        | python-sample-app                                                   |
| trigger_uri |                                                                     |
| uuid        | 4a795b99-936d-4330-be4d-d2099b160075                                |
+-------------+---------------------------------------------------------------------+

The uri field above refers to the newly-registered plan. At this point, your app is not deployed yet.

Your app is now ready to be deployed using the uuid from above to deploy your app.

$ solum app deploy 4a795b99-936d-4330-be4d-d2099b160075
+-----------------+------------------------------------------------------------------------+
| Property        | Value                                                                  |
+-----------------+------------------------------------------------------------------------+
| status          | QUEUED                                                                 |
| description     | Sample Python web app.                                                 |
| application_uri | None                                                                   |
| name            | python-sample-app                                                      |
| trigger_uri     | http://10.0.2.15:9777/v1/triggers/b6eb26e5-3b7b-416b-b932-302c514071cc |
| uuid            | 185f2741-61e0-497e-b2b7-c890c7e151dd                                   |
+-----------------+------------------------------------------------------------------------+

Solum builds a docker image by layering your app’s code on top of the related language pack’s image. Then, Solum creates a stack via Heat to deploy your app. At this point, Solum is done, and in a matter of minutes your app will be deployed.

6. You can monitor the progress of your app as it builds and deploys. The status field will show the progress of your app through the process.

$ solum assembly show 185f2741-61e0-497e-b2b7-c890c7e151dd
+-----------------+------------------------------------------------------------------------+
| Property        | Value                                                                  |
+-----------------+------------------------------------------------------------------------+
| status          | BUILDING                                                               |
| description     | Sample Python web app.                                                 |
| application_uri | None                                                                   |
| created_at      | 2015-03-10T22:47:04                                                    |
| updated_at      | 2015-03-10T22:49:59                                                    |
| name            | python-sample-app                                                      |
| trigger_uri     | http://10.0.2.15:9777/v1/triggers/b6eb26e5-3b7b-416b-b932-302c514071cc |
| uuid            | 185f2741-61e0-497e-b2b7-c890c7e151dd                                   |
+-----------------+------------------------------------------------------------------------+

Run the solum assembly show command a few times to see the status change. You will notice the status field changes to READY and the application_uri is available.

$ solum assembly show 185f2741-61e0-497e-b2b7-c890c7e151dd
+-----------------+------------------------------------------------------------------------+
| Property        | Value                                                                  |
+-----------------+------------------------------------------------------------------------+
| status          | READY                                                                  |
| description     | Sample Python web app.                                                 |
| application_uri | 192.168.76.21:80                                                       |
| created_at      | 2015-03-10T22:47:04                                                    |
| updated_at      | 2015-03-10T22:49:59                                                    |
| name            | python-sample-app                                                      |
| trigger_uri     | http://10.0.2.15:9777/v1/triggers/b6eb26e5-3b7b-416b-b932-302c514071cc |
| uuid            | 185f2741-61e0-497e-b2b7-c890c7e151dd                                   |
+-----------------+------------------------------------------------------------------------+

Connect to Your App¶

Connect to your app using the value in the application_uri field.

$ curl <your_application_uri_here>
Hello World

Update Your App¶

You can set up your Git repository to fire an on_commit action to make a webhook call to Solum each time you make a commit. The webhook call sends a POST request to http://10.0.2.15:9777/v1/triggers/<trigger_id> causing Solum to automatically build a new image and re-deploy your application.

To do this with a GitHub repo, go to your repo on the web, click on Settings, and then select “Webhooks & Services” form the left navigation menu. In the Webhooks section, click “Add Webhook”, and enter your GitHub account password when prompted. Copy and paste the value of trigger_uri from your “solum assembly show” command into the “Payload URL” filed. Note that this will only work if you have a public IP address or hostname in the trigger_uri field. Select the “application/vnd.github.v3+json” Payload version, determine if you only want to trigger this webhook on “git push” or if you want it for other events too by using the radio buttons and Checkboxes provided. Finish by clicking “Add Webhook”. Now next time that event is triggered on GitHub, Solum will automatically check out your change, build it, and deploy it for you.

Languagepacks¶

Languagepacks define the runtime environment required by your application.

To build a languagepack, solum requires a git repo containing a Dockerfile. Solum creates a Docker and stores the image for use when building and deploying your application. See the sample languagepack repo below

$ https://github.com/rackspace-solum-samples/solum-languagepack-python

Here are some best practices to keep in mind while creating a languagepack

A good languagepack is reusable across application
All Operating system level libraries should be defined in the languagepack
Test tools should be installed in the languagepack
Includes a mandatory build.sh script, which Solum CI expects and executes during the build phase

planfile¶

A planfile is used to define your application and passed in during application creation.

$ solum app create --plan-file planfile.yaml --param-file params.yaml

In the above command, we use the –plan-file flag to provide

version: 1
name: python-sample-app
description: Sample Python web app.
artifacts:
- name: python-sample-app
  content:
    href: https://github.com/rackspace-solum-samples/solum-python-sample-app.git
  language_pack: python
  unittest_cmd: pip install -r test-requirements.txt; pep8 app.py
  run_cmd: ./main.sh
  ports: 80

The planfile is used to define the following

The git repo where your code exists
The languagepack to use
A name for your application
A command that executes your unittests. This command is executed during the unit test phase of the Solum CI workflow.
The port which is exposed publicly for accessing your application.
A command that executes your command.

App configuration and environment variables¶

Applications deployed using solum can be configured using environment variables. Provide a parameter file during application creation to inject environment variables

$ solum app create --plan-file planfile.yaml --param-file params.yaml

In the example above, we pass in the parameter file (shown in the table below) using the –param-file flag. The parameter file contains key value pairs which are injected into the application run time environment.

key: secret_key
user: user_name_goes_here
password: password_for_demo

Set up a Development Environment¶

These instructions are for those who plan to contribute to Solum, or use features that are not yet in the latest release.

1. Clone the Solum repo. At present it is a Stackforge project, and its repository is available on the OpenStack Git server.

$ mkdir ~/Solum
$ cd Solum
$ git clone git://git.openstack.org/stackforge/solum

In addition to Solum, your environment will also need Devstack to configure and run the requisite OpenStack components, including Keystone, Glance, Nova, Neutron, and Heat.

Vagrant Dev Environment (optional, for developers)¶

2. We have provided a Vagrant environment to deploy Solum and its required OpenStack components via Devstack. We recommend using this approach if you are planning to contribute to Solum. This takes about the same amount of time as setting up Devstack manually, but it automates the setup for you. By default, it uses virtualbox as its provisioner. We have tested this with Vagrant 1.5.4. The environment will need to know where your Solum code is, via the environment variable SOLUM.

$ cd ~/Solum
$ export SOLUM=~/Solum/solum
$ git clone https://github.com/rackerlabs/vagrant-solum-dev.git vagrant
$ cd vagrant

3. Bring up the devstack vagrant environment. This may take a while. Allow about an hour, more or less depending on your machine speed and its connection to the internet.

$ vagrant up --provision devstack
$ vagrant ssh devstack

Devstack (alternate, for experts)¶

Using Vagrant is not a requirement for deploying Solum. You may instead opt to install Solum and Devstack yourself. Keep in mind that this approach is much slower than using the Vagrant option. It may take an hour or more to complete this setup step. Please set your expectations accordingly. The details of integrating Solum with Devstack can be found in contrib/devstack/README.rst.

Install Solum¶

Distro specific installation¶

TODO add docs here on how to install on different distros like:

debian

redhat

suse

ubuntu

For a development installation use devstack¶

The contrib/devstack/ directory contains the files necessary to integrate Solum with devstack.

Install Docker, to be used by our build service: http://docs.docker.io/installation/

To install devstack, run the setup script provided in the Solum code tree:

export SOLUM_DIR=/path/to/solum/source/dir
sh ${SOLUM_DIR}/contrib/devstack/setup_devstack.sh

Note that this setup will produce virtual machines, not Docker containers. For an example of the Docker setup, see: http://wiki.openstack.org/Solum/Docker

Configure and run Solum¶

Configuration Reference¶

To alter the default compute flavor edit /etc/solum/templates/*.yaml

flavor:
  type: string
  description: Flavor to use for servers
  default: m1.tiny

Edit the default section to the desired value.

Administrator Guide¶

Man pages for services and utilities¶

Solum utilities¶

solum-db-manage¶

SYNOPSIS¶

solum-db-manage <action> [options]

DESCRIPTION¶

solum-db-manage helps manage solum specific database operations.

The migrations in the “alembic_migrations/versions/” directory contain the changes needed to migrate from older Solum releases to newer versions. A migration occurs by executing a script that details the changes needed to upgrade/downgrade the database. The migration scripts are ordered so that multiple scripts can run sequentially to update the database. The scripts are executed by Solum’s migration wrapper which uses the Alembic library to manage the migration.

OPTIONS¶

The standard pattern for executing a solum-db-manage command is:

solum-db-manage <command> [<args>]

Run with -h to see a list of available commands:

solum-db-manage -h

Commands are:

version
upgrade
downgrade
stamp
revision

Detailed descriptions are below.

Upgrading/Downgrading¶

If you are a deployer or developer and want to migrate from Icehouse to Juno or later you must first add version tracking to the database:

solum-db-manage stamp icehouse

You can then upgrade to the latest database version via:

solum-db-manage upgrade head

To check the current database version:

solum-db-manage version

Downgrade the database to a specific revision:

solum-db-manage downgrade 594288b1585a

Generating migration templates (developers only)¶

A database migration script is required when you submit a change to Solum that alters the database model definition. The migration script is a special python file that includes code to update/downgrade the database to match the changes in the model definition. Alembic will execute these scripts in order to provide a linear migration path between revision. The solum-db-manage command can be used to generate migration template for you to complete. The operations in the template are those supported by the Alembic migration library.

solum-db-manage revision -m "description of revision" --autogenerate

This generates a prepopulated template with the changes needed to match the database state with the models. You should inspect the autogenerated template to ensure that the proper models have been altered.

In rare circumstances, you may want to start with an empty migration template and manually author the changes necessary for an upgrade/downgrade. You can create a blank file via:

solum-db-manage revision -m "description of revision"

FILES¶

The /etc/solum/solum.conf file contains global options which can be used to configure some aspects of solum-db-manage, for example the DB connection and logging.

BUGS¶

Solum issues are tracked in Launchpad so you can view or report bugs here:: OpenStack Solum Bugs

High Availability Guide¶

Operations Guide¶

Security Guide¶

Develop applications for Solum¶

API Complete Reference¶

Version discovery¶

type Version¶

Version representation.

Data samples:

Json

{
    "id": "v1.0",
    "link": {
        "href": "http://example.com:9777/v1",
        "target_name": "v1"
    },
    "status": "CURRENT"
}

XML

<value>
  <id>v1.0</id>
  <status>CURRENT</status>
  <link>
    <href>http://example.com:9777/v1</href>
    <target_name>v1</target_name>
  </link>
</value>

id¶

Type:	unicode

The version identifier.

link¶

Type:	Link

The link to the versioned API.

status¶

Type:	Enum(SUPPORTED, CURRENT, DEPRECATED)

The status of the API (SUPPORTED, CURRENT or DEPRECATED).

V1 API¶

type Link¶

A link representation.

Data samples:

Json

{
    "href": "http://example.com:9777/v1",
    "target_name": "v1"
}

XML

<value>
  <href>http://example.com:9777/v1</href>
  <target_name>v1</target_name>
</value>

href¶

Type:	unicode

The link URI.

target_name¶

Type:	unicode

Textual name of the target link.

Platform¶

type Platform¶

Representation of a Platform.

The Platform resource is the root level resource that refers to all the other resources owned by this tenant.

Data samples:

Json

{
    "assemblies_uri": "http://example.com:9777/v1/assemblies",
    "components_uri": "http://example.com:9777/v1/components",
    "description": "solum native implementation",
    "extensions_uri": "http://example.com:9777/v1/extensions",
    "implementation_version": "2014.1.1",
    "infrastructure_uri": "http://example.com:9777/v1/infrastructure",
    "language_packs_uri": "http://example.com:9777/v1/language_packs",
    "name": "solum",
    "operations_uri": "http://example.com:9777/v1/operations",
    "pipelines_uri": "http://example.com:9777/v1/pipelines",
    "plans_uri": "http://example.com:9777/v1/plans",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "sensors_uri": "http://example.com:9777/v1/sensors",
    "services_uri": "http://example.com:9777/v1/services",
    "tags": [
        "solid"
    ],
    "triggers_uri": "http://example.com:9777/v1/triggers",
    "type": "platform",
    "uri": "http://example.com/v1",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <implementation_version>2014.1.1</implementation_version>
  <plans_uri>http://example.com:9777/v1/plans</plans_uri>
  <assemblies_uri>http://example.com:9777/v1/assemblies</assemblies_uri>
  <services_uri>http://example.com:9777/v1/services</services_uri>
  <components_uri>http://example.com:9777/v1/components</components_uri>
  <extensions_uri>http://example.com:9777/v1/extensions</extensions_uri>
  <operations_uri>http://example.com:9777/v1/operations</operations_uri>
  <sensors_uri>http://example.com:9777/v1/sensors</sensors_uri>
  <language_packs_uri>http://example.com:9777/v1/language_packs</language_packs_uri>
  <pipelines_uri>http://example.com:9777/v1/pipelines</pipelines_uri>
  <triggers_uri>http://example.com:9777/v1/triggers</triggers_uri>
  <infrastructure_uri>http://example.com:9777/v1/infrastructure</infrastructure_uri>
  <name>solum</name>
  <type>platform</type>
  <tags>
    <item>solid</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>solum native implementation</description>
  <uri>http://example.com/v1</uri>
</value>

assemblies_uri¶

Type:	unicode

URI to assemblies.

components_uri¶

Type:	unicode

URI to components.

extensions_uri¶

Type:	unicode

URI to extensions.

implementation_version¶

Type:	unicode

Version of the platform.

infrastructure_uri¶

Type:	unicode

URI to infrastructure.

language_packs_uri¶

Type:	unicode

URI to language packs.

operations_uri¶

Type:	unicode

URI to operations.

pipelines_uri¶

Type:	unicode

URI to pipelines.

plans_uri¶

Type:	unicode

URI to plans.

sensors_uri¶

Type:	unicode

URI to sensors.

services_uri¶

Type:	unicode

URI to services.

triggers_uri¶

Type:	unicode

URI to triggers.

Plans¶

GET /v1/plans¶: Return all plans, based on the query provided.

POST /v1/plans¶: Create a new plan.

GET /v1/plans/(plan_id)¶: Return this plan.

PUT /v1/plans/(plan_id)¶: Modify this plan.

DELETE /v1/plans/(plan_id)¶: Delete this plan.

type Plan¶

Representation of an Plan file.

The Plan resource is a representation of a Plan file. Plans are used to create Assembly resources. A Plan resource may be used to create an arbitrary number of Assembly instances. They use artifacts and services to indicate what will be used to generate the plan, and what services Solum can use to satisfy them. Note: Plan files are YAML and Plan resources are the REST representation of the Plan file after services have been matched to ones offered by Solum.

Data samples:

Json

{
    "artifacts": [
        {
            "artifact_type": "git_pull",
            "content": {
                "href": "git://example.com/project.git",
                "private": false
            },
            "language_pack": "4ae66383-77c0-4205-bca8-8c8f7f16be24",
            "name": "My-python-app",
            "requirements": [
                {
                    "fulfillment": "id:build",
                    "requirement_type": "git_pull"
                }
            ]
        }
    ],
    "description": "A plan with no services or artifacts shown",
    "name": "Example-plan",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "services": [
        {
            "characteristics": [
                "python_build_service"
            ],
            "id": "build",
            "name": "Build-Service"
        }
    ],
    "tags": [
        "small"
    ],
    "trigger_uri": "http://example.com/v1/triggers/1abc234",
    "type": "plan",
    "uri": "http://example.com/v1/plans/x1",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <artifacts>
    <item>
      <name>My-python-app</name>
      <artifact_type>git_pull</artifact_type>
      <content>
        <item>
          <key>href</key>
          <value>git://example.com/project.git</value>
        </item>
        <item>
          <key>private</key>
          <value>False</value>
        </item>
      </content>
      <language_pack>4ae66383-77c0-4205-bca8-8c8f7f16be24</language_pack>
      <requirements>
        <item>
          <requirement_type>git_pull</requirement_type>
          <fulfillment>id:build</fulfillment>
        </item>
      </requirements>
    </item>
  </artifacts>
  <services>
    <item>
      <name>Build-Service</name>
      <id>build</id>
      <characteristics>
        <item>python_build_service</item>
      </characteristics>
    </item>
  </services>
  <trigger_uri>http://example.com/v1/triggers/1abc234</trigger_uri>
  <name>Example-plan</name>
  <type>plan</type>
  <tags>
    <item>small</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>A plan with no services or artifacts shown</description>
  <uri>http://example.com/v1/plans/x1</uri>
</value>

artifacts¶

Type:	list(Artifact)

List of artifacts defining the plan.

parameters¶

Type:	dict(unicode: None)

User defined parameters

services¶

Type:	list(ServiceReference)

List of services needed by the plan.

trigger_uri¶

Type:	unicode

The trigger uri used to trigger the build of the plan

Pipelines¶

GET /v1/pipelines¶

Return all pipelines.

Return type:	list(`Pipeline`)

POST /v1/pipelines¶

Create a new pipeline. :type data: Pipeline

Return type:	`Pipeline`

GET /v1/pipelines/(pipeline_id)¶

Return this pipeline.

Return type:	`Pipeline`

PUT /v1/pipelines/(pipeline_id)¶

Modify this pipeline. :type data: Pipeline

Return type:	`Pipeline`

DELETE /v1/pipelines/(pipeline_id)¶: Delete this pipeline.

type Pipeline¶

Representation of an Pipeline.

A pipeline is the association between a plan, a mistral workbook and a git trigger. Together they form a working developement “pipeline”.

Data samples:

Json

{
    "description": "A pipeline for my app",
    "last_execution": "78f41cf46df7430b9486a35f5d28a41",
    "name": "Example-pipeline",
    "plan_uri": "http://example.com/v1/plans/x1",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "tags": [
        "small"
    ],
    "trigger_uri": "http://example.com/v1/triggers/1abc234",
    "type": "pipeline",
    "uri": "http://example.com/v2/pipelines/p1",
    "user_id": "55f41cf46df74320b9486a35f5d28a11",
    "workbook_name": "build-deploy"
}

XML

<value>
  <plan_uri>http://example.com/v1/plans/x1</plan_uri>
  <workbook_name>build-deploy</workbook_name>
  <trigger_uri>http://example.com/v1/triggers/1abc234</trigger_uri>
  <last_execution>78f41cf46df7430b9486a35f5d28a41</last_execution>
  <type>pipeline</type>
  <name>Example-pipeline</name>
  <description>A pipeline for my app</description>
  <tags>
    <item>small</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <uri>http://example.com/v2/pipelines/p1</uri>
</value>

last_execution¶

Type:	unicode

The UUID of the last run execution.

plan_uri¶

Type:	unicode

Link to the plan URI.

trigger_uri¶

Type:	unicode

The trigger uri used to trigger the pipeline.

workbook_name¶

Type:	unicode

Name of the workbook in Mistral to use.

Executions¶

GET /v1/pipelines/(pipeline_id)/executions¶

Return all executions, based on the provided pipeline_id. :type pipeline_id: unicode

Return type:	list(`Execution`)

type Execution¶

Data samples:

Json

{
    "href": "http://example.com:9777/v1",
    "target_name": "v1"
}

XML

<value>
  <href>http://example.com:9777/v1</href>
  <target_name>v1</target_name>
</value>

Assemblies¶

GET /v1/assemblies¶

Return all assemblies, based on the query provided.

Return type:	list(`Assembly`)

POST /v1/assemblies¶

Create a new assembly. :type data: Assembly

Return type:	`Assembly`

GET /v1/assemblies/(assembly_id)¶

Return this assembly.

Return type:	`Assembly`

PUT /v1/assemblies/(assembly_id)¶

Modify this assembly. :type data: Assembly

Return type:	`Assembly`

DELETE /v1/assemblies/(assembly_id)¶: Delete this assembly.

type Assembly¶

Representation of an Assembly.

The Assembly resource represents a group of components that make up a running instance of an application. You may casually refer to this as “the application” but we refer to it as an Assembly because most cloud applications are actually a system of multiple service instances that make up a system. For example, a three-tier web application may have a load balancer component, a group of application servers, and a database server all represented as Component resources that make up an Assembly resource. An Assembly resource has at least one Component resource associated with it.

Data samples:

Json

{
    "components": [],
    "created_at": "2015-05-18T21:35:31.726791",
    "description": "A mysql database",
    "name": "database",
    "operations": [],
    "plan_uri": "http://example.com/v1/plans/45-09",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "sensors": [],
    "tags": [
        "small"
    ],
    "type": "assembly",
    "updated_at": "2015-05-18T21:35:31.726791",
    "uri": "http://example.com/v1/assemblies/x4",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <plan_uri>http://example.com/v1/plans/45-09</plan_uri>
  <components />
  <operations />
  <sensors />
  <updated_at>2015-05-18T21:35:31.726791</updated_at>
  <created_at>2015-05-18T21:35:31.726791</created_at>
  <name>database</name>
  <type>assembly</type>
  <tags>
    <item>small</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>A mysql database</description>
  <uri>http://example.com/v1/assemblies/x4</uri>
</value>

application_uri¶

Type:	unicode

The uri of the deployed application.

components¶

Type:	list(Component)

Components that belong to the assembly.

created_at¶

Type:	datetime

The time the assembly initially created.

operations¶

Type:	list(Operation)

Operations that belong to the assembly.

plan_uri¶

Type:	unicode

The URI to the plan to be used to create this assembly.

sensors¶

Type:	list(Sensor)

Sensors that belong to the assembly.

status¶

Type:	unicode

The status of the assembly.

updated_at¶

Type:	datetime

The last time a change was made to the assembly’s status.

workflow¶

Type:	list(Enum(unittest, build, deploy))

Defines the workflow that an assembly will go through.

Services¶

GET /v1/services¶

Return all services, based on the query provided.

Return type:	list(`Service`)

POST /v1/services¶

Create a new service. :type data: Service

Return type:	`Service`

GET /v1/services/(service_id)¶

Return this service.

Return type:	`Service`

PUT /v1/services/(service_id)¶

Modify this service. :type data: Service

Return type:	`Service`

DELETE /v1/services/(service_id)¶: Delete this service.

type Service¶

The Service resource represents a networked service.

You may create Component resources that refer to Service resources. A Component represents an instance of a Service. Your application connects to such a Component using a network protocol. For example, the Platform may offer a default Service named “mysql”. You may create multiple Component resources that reference different instances of the “mysql” service. Each Component may be a multi-tenant instance of a MySQL database (perhaps a logical database) service offered by the Platform for a given Assembly.

Data samples:

Json

{
    "description": "A language pack service",
    "name": "language-pack",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "read_only": false,
    "service_type": "language_pack",
    "tags": [
        "group_xyz"
    ],
    "type": "service",
    "uri": "http://example.com/v1/language_packs/java1.4",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <read_only>false</read_only>
  <service_type>language_pack</service_type>
  <name>language-pack</name>
  <type>service</type>
  <description>A language pack service</description>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <tags>
    <item>group_xyz</item>
  </tags>
  <uri>http://example.com/v1/language_packs/java1.4</uri>
</value>

read_only¶

Type:	bool

The service is read only when this value is true.

service_type¶

Type:	unicode

Type of service. Example: language_pack or db::mysql

Operations¶

GET /v1/operations¶

Return all operations, based on the query provided.

Return type:	list(`Operation`)

POST /v1/operations¶

Create a new operation. :type data: Operation

Return type:	`Operation`

GET /v1/operations/(operation_id)¶

Return this operation.

Return type:	`Operation`

PUT /v1/operations/(operation_id)¶

Modify this operation. :type data: unicode

Return type:	`Operation`

DELETE /v1/operations/(operation_id)¶: Delete this operation.

type Operation¶

An Operation resource represents an operation or action.

This is for defining actions that may change the state of the resource they are related to. For example, the API already provides ways to register, start, and stop your application (POST an Assembly to register+start, and DELETE an Assembly to stop) but Operations provide a way to extend the system to add your own actions such as “pause” and “resume”, or “scale_up” and “scale_down”.

Data samples:

Json

{
    "description": "A resume operation",
    "documentation": "http://example.com/docs/resume_op",
    "name": "resume",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "tags": [
        "small"
    ],
    "target_resource": "http://example.com/instances/uuid",
    "type": "operation",
    "uri": "http://example.com/v1/operations/resume",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <documentation>http://example.com/docs/resume_op</documentation>
  <target_resource>http://example.com/instances/uuid</target_resource>
  <name>resume</name>
  <type>operation</type>
  <tags>
    <item>small</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>A resume operation</description>
  <uri>http://example.com/v1/operations/resume</uri>
</value>

documentation¶

Type:	unicode

Documentation URI for the operation.

target_resource¶

Type:	unicode

Target resource URI to the operation.

Sensors¶

GET /v1/sensors¶

Return all sensors, based on the query provided.

Return type:	list(`Sensor`)

POST /v1/sensors¶

Create a new sensor. :type data: unicode

Return type:	`Sensor`

GET /v1/sensors/(sensor_id)¶

Return this sensor.

Return type:	`Sensor`

PUT /v1/sensors/(sensor_id)¶

Modify this sensor. :type data: unicode

Return type:	`Sensor`

DELETE /v1/sensors/(sensor_id)¶: Delete this sensor.

type Sensor¶

A Sensor resource represents exactly one supported sensor.

Sensor resources represent dynamic data about resources, such as metrics or state. Sensor resources are useful for exposing data that changes rapidly, or that may need to be fetched from a secondary system.

Data samples:

Json

{
    "description": "A heartbeat sensor",
    "documentation": "http://example.com/docs/heartbeat/",
    "name": "hb",
    "operations": [],
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "sensor_type": "str",
    "target_resource": "http://example.com/instances/uuid",
    "timestamp": "2015-05-18T21:35:32.583063",
    "type": "sensor",
    "uri": "http://example.com/v1/sensors/hb",
    "user_id": "55f41cf46df74320b9486a35f5d28a11",
    "value": "30"
}

XML

<value>
  <documentation>http://example.com/docs/heartbeat/</documentation>
  <target_resource>http://example.com/instances/uuid</target_resource>
  <sensor_type>str</sensor_type>
  <timestamp>2015-05-18T21:35:32.583063</timestamp>
  <operations />
  <value>30</value>
  <name>hb</name>
  <type>sensor</type>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>A heartbeat sensor</description>
  <uri>http://example.com/v1/sensors/hb</uri>
</value>

documentation¶

Type:	unicode

Documentation URI for the sensor.

operations¶

Type:	list(Operation)

Operations that belong to the sensor.

sensor_type¶

Type:	Enum(str, float, int)

Sensor data type.

target_resource¶

Type:	unicode

Target resource URI to the sensor.

timestamp¶

Type:	datetime

Timestamp for Sensor.

value¶

Type:	str

Value of the sensor.

Components¶

GET /v1/components¶

Return all components, based on the query provided.

Return type:	list(`Component`)

POST /v1/components¶

Create a new component. :type data: Component

Return type:	`Component`

GET /v1/components/(component_id)¶

Return this component.

Return type:	`Component`

PUT /v1/components/(component_id)¶

Modify this component. :type data: Component

Return type:	`Component`

DELETE /v1/components/(component_id)¶: Delete this component.

type Component¶

The Component resource represents one part of an Assembly.

For example, an instance of a database service may be a Component. A Component resource may also represent a static artifact, such as an archive file that contains data for initializing your application. An Assembly may have different components that represent different processes that run. For example, you may have one Component that represents an API service process, and another that represents a web UI process that consumes that API service. The simplest case is when an Assembly has only one component. For example, your component may be named “PHP” and refers to the PHP Service offered by the platform for running a PHP application.

Data samples:

Json

{
    "abbreviated": true,
    "component_type": "heat_stack",
    "components_ids": [],
    "description": "A php web application component",
    "heat_stack_id": "4c712026-dcd5-4664-90b8-0915494c1332",
    "name": "php-web-app",
    "operations": [],
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "sensors": [],
    "services": [],
    "tags": [
        "group_xyz"
    ],
    "type": "component",
    "uri": "http://example.com/v1/components/php-web-app",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <services />
  <operations />
  <sensors />
  <abbreviated>true</abbreviated>
  <components_ids />
  <component_type>heat_stack</component_type>
  <heat_stack_id>4c712026-dcd5-4664-90b8-0915494c1332</heat_stack_id>
  <name>php-web-app</name>
  <type>component</type>
  <description>A php web application component</description>
  <tags>
    <item>group_xyz</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <uri>http://example.com/v1/components/php-web-app</uri>
</value>

abbreviated¶

Type:	bool

Boolean value indicating if this components has nested components at more than one level of depth.

assembly_uuid¶

Type:	unicode

“The uuid of the assembly that this component belongs in.

component_type¶

Type:	unicode

Type of component e.g. heat_stack.

components_ids¶

Type:	list(unicode)

IDs of nested component of the component.

heat_stack_id¶

Type:	unicode

Unique identifier of the Heat Stack.

operations¶

Type:	list(Operation)

Operations that belong to the component.

resource_uri¶

Type:	unicode

Remote resource URI of the component.

sensors¶

Type:	list(Sensor)

Sensors that belong to the component.

services¶

Type:	list(Service)

Services that belong to the component.

Extensions¶

GET /v1/extensions¶

Return all extensions, based on the query provided.

Return type:	list(`Extension`)

POST /v1/extensions¶

Create a new extension. :type data: unicode

Return type:	`Extension`

GET /v1/extensions/(extension_id)¶

Return this extension.

Return type:	`Extension`

PUT /v1/extensions/(extension_id)¶

Modify this extension. :type data: unicode

Return type:	`Extension`

DELETE /v1/extensions/(extension_id)¶: Delete this extension.

type Extension¶

The Extension resource represents Provider modifications.

This may include additional protocol semantics, resource types, application lifecycle states, resource attributes, etc. Anything may be added, as long as it does not contradict the base functionality offered by Solum.

Data samples:

Json

{
    "description": "This logstash extension provides a tool for managing your application events and logs.",
    "documentation": "http://example.com/docs/ext/logstash",
    "name": "logstash",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "tags": [
        "large"
    ],
    "type": "extension",
    "uri": "http://example.com/v1/extensions/logstash",
    "user_id": "55f41cf46df74320b9486a35f5d28a11",
    "version": "2.13"
}

XML

<value>
  <version>2.13</version>
  <documentation>http://example.com/docs/ext/logstash</documentation>
  <name>logstash</name>
  <type>extension</type>
  <tags>
    <item>large</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>This logstash extension provides a tool for managing your application events and logs.</description>
  <uri>http://example.com/v1/extensions/logstash</uri>
</value>

documentation¶

Type:	unicode

Documentation URI to the extension.

version¶

Type:	unicode

Version of the extension.

LanguagePacks¶

GET /v1/language_packs¶

Return all languagepacks, based on the query provided.

Return type:	list(`LanguagePack`)

POST /v1/language_packs¶

Create a new languagepack. :type data: LanguagePack

Return type:	`LanguagePack`

GET /v1/language_packs/(lp_id)¶

Return a languagepack.

Return type:	`LanguagePack`

DELETE /v1/language_packs/(lp_id)¶: Delete a languagepack.

type LanguagePack¶

Representation of a language pack.

When a user creates an application, he specifies the language pack to be used. The language pack is responsible for building the application and producing an artifact for deployment.

For a complete list of language pack attributes please refer: https://etherpad.openstack.org/p/Solum-Language-pack-json-format

Data samples:

Json

{
    "attributes": {
        "admin_email": "someadmin@somewhere.com",
        "optional_attr1": "value"
    },
    "base_image_id": "4dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "build_tool_chain": [
        {
            "type": "ant",
            "version": "1.7"
        },
        {
            "type": "maven",
            "version": "1.2"
        }
    ],
    "compiler_versions": [
        "1.4",
        "1.6",
        "1.7"
    ],
    "created_image_id": "4afasa09ef2b4d8cbf3594b0ec4f6b94",
    "description": "A php web application",
    "image_format": "docker",
    "language_implementation": "Sun",
    "language_pack_type": "org.openstack.solum.Java",
    "name": "php-web-app",
    "os_platform": {
        "OS": "Ubuntu",
        "version": "12.04"
    },
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "runtime_versions": [
        "1.4",
        "1.6",
        "1.7"
    ],
    "source_format": "heroku",
    "source_uri": "git://example.com/project/app.git",
    "tags": [
        "group_xyz"
    ],
    "type": "languagepack",
    "uri": "http://example.com/v1/images/b3e0d79",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <language_pack_type>org.openstack.solum.Java</language_pack_type>
  <compiler_versions>
    <item>1.4</item>
    <item>1.6</item>
    <item>1.7</item>
  </compiler_versions>
  <runtime_versions>
    <item>1.4</item>
    <item>1.6</item>
    <item>1.7</item>
  </runtime_versions>
  <language_implementation>Sun</language_implementation>
  <build_tool_chain>
    <item>
      <type>ant</type>
      <version>1.7</version>
    </item>
    <item>
      <type>maven</type>
      <version>1.2</version>
    </item>
  </build_tool_chain>
  <os_platform>
    <item>
      <key>version</key>
      <value>12.04</value>
    </item>
    <item>
      <key>OS</key>
      <value>Ubuntu</value>
    </item>
  </os_platform>
  <attributes>
    <item>
      <key>optional_attr1</key>
      <value>value</value>
    </item>
    <item>
      <key>admin_email</key>
      <value>someadmin@somewhere.com</value>
    </item>
  </attributes>
  <source_uri>git://example.com/project/app.git</source_uri>
  <source_format>heroku</source_format>
  <base_image_id>4dae5a09ef2b4d8cbf3594b0eb4f6b94</base_image_id>
  <image_format>docker</image_format>
  <created_image_id>4afasa09ef2b4d8cbf3594b0ec4f6b94</created_image_id>
  <tags>
    <item>group_xyz</item>
  </tags>
  <name>php-web-app</name>
  <type>languagepack</type>
  <description>A php web application</description>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <uri>http://example.com/v1/images/b3e0d79</uri>
</value>

attributes¶

Type:	dict(str: unicode)

Additional section attributes will be used to expose custom attributes designed by language pack creator.

base_image_id¶

Type:	unicode

The id (in glance) of the image to customize.

build_tool_chain¶

Type:	list(BuildTool)

Toolchain available in the language pack. Example: For a java language pack which supports Ant and Maven, build_tool_chain = [“{type:ant,version:1.7}”,”{type:maven,version:1.2}”]

compiler_versions¶

Type:	list(unicode)

List of all the compiler versions supported by the language pack. Example: For a java language pack supporting Java versions 1.4 to 1.7, version = [‘1.4’, ‘1.6’, ‘1.7’]

created_image_id¶

Type:	unicode

The id of the created image in glance.

image_format¶

Type:	Enum(auto, qcow2, docker)

The image format.

language_implementation¶

Type:	unicode

Actual language implementation supported by the language pack. Example: In case of java it might be ‘Sun’ or ‘openJava’ In case of C++ it can be ‘gcc’ or ‘icc’ or ‘microsoft’.

language_pack_type¶

Type:	unicode

Type of the language pack. Identifies the language supported by the language pack. This attribute value will use the org.openstack.solum namespace.

lp_metadata¶

Type:	unicode

The languagepack meta data.

os_platform¶

Type:	dict(str: unicode)

OS and its version used by the language pack. This attribute identifies the base image of the language pack.

runtime_versions¶

Type:	list(unicode)

List of all runtime versions supported by the language pack. Runtime version can be different than compiler version. Example: An application can be compiled with java 1.7 but it should run in java 1.6 as it is backward compatible.

source_format¶

Type:	Enum(auto, heroku, dib, dockerfile)

The source repository format.

source_uri¶

Type:	unicode

The URI of the app/element.

status¶

Type:	Enum(BUILDING, READY, QUEUED, ERROR)

The state of the image.

Infrastructure¶

type Infrastructure¶

Description of an Infrastructure.

Data samples:

Json

{
    "description": "Solum Infrastructure endpoint",
    "name": "infrastructure",
    "project_id": "1dae5a09ef2b4d8cbf3594b0eb4f6b94",
    "stacks_uri": "http://example.com/v1/infrastructure/stacks",
    "tags": [
        "small"
    ],
    "type": "infrastructure",
    "uri": "http://example.com/v1/infrastructure",
    "user_id": "55f41cf46df74320b9486a35f5d28a11"
}

XML

<value>
  <stacks_uri>http://example.com/v1/infrastructure/stacks</stacks_uri>
  <name>infrastructure</name>
  <type>infrastructure</type>
  <tags>
    <item>small</item>
  </tags>
  <project_id>1dae5a09ef2b4d8cbf3594b0eb4f6b94</project_id>
  <user_id>55f41cf46df74320b9486a35f5d28a11</user_id>
  <description>Solum Infrastructure endpoint</description>
  <uri>http://example.com/v1/infrastructure</uri>
</value>

stacks_uri¶

Type:	unicode

URI to services.

Triggers¶

POST /v1/triggers¶: Trigger a new event on Solum.

How to contribute to Solum¶

If you would like to contribute to Solum, please see our contributing wiki:: https://wiki.openstack.org/wiki/Solum/Contributing

We have the same CLA requirements as OpenStack, so you must follow the steps in the “If you’re a developer, start here” section of this page:

http://docs.openstack.org/infra/manual/developers.html

Once those steps have been completed, submit your changes to for review via the Gerrit tool, following the workflow documented at:

http://docs.openstack.org/infra/manual/developers.html#development-workflow

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/solum

For tips to help with running unit tests and funcitonal tests on your code, see:

https://wiki.openstack.org/wiki/Solum/Testing

OpenStack

Welcome to Solum’s documentation!¶

Solum¶

Overview¶

Getting started with Solum¶

Project Info¶

Solum Quick Start Guide¶

Overview¶

Vagrant Demo Environment¶

Create a languagepack¶

Create your app¶

Deploy your app¶

Connect to Your App¶

Update Your App¶

Languagepacks¶

planfile¶

App configuration and environment variables¶

Set up a Development Environment¶

Vagrant Dev Environment (optional, for developers)¶

Devstack (alternate, for experts)¶

Install Solum¶

Distro specific installation¶

For a development installation use devstack¶

Configure and run Solum¶

Configuration Reference¶

Administrator Guide¶

Man pages for services and utilities¶

Solum utilities¶

solum-db-manage¶

High Availability Guide¶

Operations Guide¶

Security Guide¶

Develop applications for Solum¶

API Complete Reference¶

Version discovery¶

V1 API¶

Platform¶

Plans¶

Pipelines¶

Executions¶

Assemblies¶

Services¶

Operations¶

Sensors¶

Components¶

Extensions¶

LanguagePacks¶

Infrastructure¶

Triggers¶

How to contribute to Solum¶

Indices and tables¶

Table Of Contents

Quick search