Introducing the OpenShift Cartridge API Version 2

OpenShift Cartridge As folks familiar with Origin may have noticed, the team has been hard at work bringing a lot of exciting new capabilities to OpenShift cartridges over the last few months, and those changes are now available both in Origin master and in OpenShift Online. With the new v2 cartridge API it's easier than ever before to bring your favorite frameworks and services to OpenShift as cartridges. To help improve the cartridge writing experience for those without Origin environments, we've also enabled the ability to run your own custom cartridges directly on OpenShift Online.

What is possible now?

  • Running cartridges in userspace - all code runs in the gear under the user account
  • Multiple software versions in the same cart (e.g. Ruby 1.8.7 and 1.9.3 are delivered together)
  • Expose TCP and HTTP proxy ports
  • Create scaled non-web cartridges
  • Set arbitrary environment variables on cart installation
  • Define both plugin and service cartridges
  • Participate in the cartridge build lifecycle
  • Can code X run on Linux? Then it's possible

Where to get started?

The best place to start is with Mike's great introductory blog posts. This establishes the basics of how the API works, and the various pieces, as well as an example of a real cart.

Next, hit up the Cartridge Developer's Guide which is the best reference for the various parts of the API. If something's not clearly explained, please let us know here or on IRC, or even provide pull requests to the doc.

To get an idea of what real cartridges look like, see the supported cartridges:

And these new and experimental cartridges:

(Not all of these cartridges are fully functional - take a look and help out if you want to see them sooner)

How do I deploy a cart to OpenShift Online?

To develop cartridges on OpenShift Online, you need to provide the URL of the manifest (which must be visible on the public internet) and the manifest must contain an attribute 'Source-Url' which points to a zip, tar, or git repository that contains the contents of your cart.

Upgrade to the latest version of rhc (1.9.1) and then pass the URL to the create-app command (also supported in the web console):

rhc create-app myapp http://url.to/the/cartridge/manifest.yml

The add-cartridge command also supports this functionality:

rhc add-cartridge http://url.to/the/cartridge/manifest.yml -a

Your app will add or install the cartridge - any errors should be reported during creation (the most common are typos or bash script errors)

To prevent you from having to update a URL and zip file every time you change the cartridge source, you can use a handy service we run on OpenShift - the cart reflector. You can pass the name of a GitHub repository and the commit ID to load to the reflector, and it'll fetch the manifest and generate a Source-Url automatically. Here's an example to install the openshift-go-cart from GitHub:

rhc create-app mygoapp "http://cartreflect-claytondev.rhcloud.com/reflect?github=smarterclayton/openshift-go-cart&commit=master"

If you need to build your cart, or would rather have your Git repository in OpenShift Online, you can install the new Cartridge Development Kit as an app, and use it to build other carts. For example:

rhc create-app mynewcart "http://cdk-claytondev.rhcloud.com/" --from-code="git://github.com/smarterclayton/openshift-go-cart.git"

is all you need to create a copy of the Go cart and have your own private copy to work on.

Read more about the OpenShift Cartridge Development Kit:

For more helpful tips on installing and running downloadable carts, visit the OpenShift downloadable cartridges page

Known Limitations (for now)

  • Not all placement options for plugins are supported today - if you want to put a cart in a specific place, check the cart guide or ask.
  • The format of connection hooks on scaled cartridges is tough to parse. We're looking to improve this, but see the Redis cart for ways to get started.
  • Process management requires some knowledge of starting, stopping, and watching processes. We're looking into ways to make this easier to start out with.
  • There's no formal upgrade process for cartridges downloaded into a gear - you'll need to roll your own for now.
  • Scale up of a downloaded cart will refetch your source cartridge - be sure to have a manifest URL that uniquely identifies a particular version of a cart
  • You can't set or retrieve environment variables on app creation or via the REST API - we want to get to this soon.

If you hit other roadblocks, let us know! We've got a ton of new features and cleanup on deck, and we want to help you bring your favorite tech to OpenShift.

The new cartridge API looks great! I can't wait to put together some new ones.