The document provides a comprehensive guide on writing cartridges for OpenShift, detailing the structure, required files, and functionalities of a minimal cartridge, including the manifest.yml file. It also explains the pub/sub protocol for database connections, showcases example applications, and emphasizes the importance of environment variables in the OpenShift ecosystem. Additional resources and tips for cartridge development and community support channels are also included.

1. Writing Cartridges for OpenShift
Jhon Honce
Pr Software Engineer, Red Hat Inc
OpenShift Origin Community Day (Boston)
June 13, 2013
http://openshift.github.io

2. The OpenShift Ecosystem: GUI/CLI, Broker, Node
GUI
rhc (CLI)
Broker
Node
(Cartridges)
REST API
ssh|git MCollective
snapshot.tgz
gitrepository

3. Where does my code fit?
● Application – application developer
● Gears – PaaS developer
● Cartridges – Cartridge authors
● Web Frameworks, Databases, Daemons
● Encapsulates some piece software for use within
the PaaS

4. The Cartridge API
● Low overhead
● Named executable files
● stdout/stderr
● Environment variables
● Configuration files:
manifest.yml, managed_files.yml
● You can use any language
● source $OPENSHIFT_CARTRIDGE_SDK_BASH
● The software you are packaging must either be on the
system or included in your cartridge

5. Minimal Cartridge – identify cartridge
+- bin
| +- setup
| +- control
+- env
+- metadata
| +- manifest.yml
● Assumes packaged software
already installed on system
● Most cartridges will have
more files
● manifest.yml
Name: dog
Cartridge-Short-Name: DOG
.
:
Version: ‘1.0’
Cartridge-Version: 0.0.1
Cartridge-Vendor: honce

6. Minimal Cartridge – required files
+- bin
| +- setup
| +- control
+- env
+- metadata
| +- manifest.yml
● Assumes packaged software
already installed on system
● Most cartridges will have
more files
● manifest.yml
Name: dog
Cartridge-Short-Name: DOG
.
:
Version: ‘1.0’
Cartridge-Version: 0.0.1
Cartridge-Vendor: honce

7. Minimal Cartridge
+- bin
| +- setup
| +- control
+- env
+- metadata
| +- manifest.yml
● Assumes packaged software
already installed on system
● Most cartridges will have
more files
● manifest.yml
Name: dog
Cartridge-Short-Name: DOG
.
:
Version: ‘1.0’
Cartridge-Version: 0.0.1
Cartridge-Vendor: honce

8. My Cartridge needs to be seen!
+- bin
| +- …
| +- control
+…
● control Arguments
● start
● stop
● manifest.yml
.
:
Endpoints:
- Private-IP-Name: IP
Private-Port-Name: PORT
Private-Port: 8080
Public-Port-Name: PROXY_PORT
Mappings:
- Frontend: ""
Backend: ""
● Environment Variables
OPENSHIFT_<SHORT_NAME>_IP
OPENSHIFT_<SHORT_NAME>_PORT
OPENSHIFT_…_PROXY_PORT

9. My Cartridge needs to be invoked
+- bin
| +- …
| +- control
+…
● Basic control arguments
● start
● stop
● manifest.yml
.
:
Endpoints:
- Private-IP-Name: IP
Private-Port-Name: PORT
Private-Port: 8080
Public-Port-Name: PROXY_PORT
Mappings:
- Frontend: ""
Backend: ""

10. My Cartridge needs to be seen!
+- bin
| +- …
| +- control
+…
● Basic control arguments
● start
● stop
● manifest.yml
.
:
Endpoints:
- Private-IP-Name: IP
Private-Port-Name: PORT
Private-Port: 8080
Public-Port-Name: PROXY_PORT
Mappings:
- Frontend: ""
Backend: ""

11. Tip: control script can be trivial
.
:
case “$1” in
start)
/usr/sbin/httpd -C
"Include $OPENSHIFT_DOG_CONF_DIR/*.conf"
-f $HTTPD_CFG_FILE -k start ;;
stop)
… -k stop ;;
restart)
… -k restart ;;
esac

12. My Cartridge needs help, a database cartridge
+- hooks
| +- …
| +- publish-db-connection-info
+…
● manifest.yml
.
:
Publishes:
publish-db-connection-info:
Type: "ENV:NET_TCP:db:connection-info"
● Pub/Sub Protocol
● publish-db-connection-info is a script
echo OPENSHIFT_MYSQL_DB_HOST=$OPENSHIFT_GEAR_DNS
echo OPENSHIFT_MYSQL_DB_PORT=$OPENSHIFT_MYSQL_DB_PROXY_PORT
echo OPENSHIFT_MYSQL_DB_URL=”mysql://…/”

13. My Cartridge needs help, a database cartridge!
● manifest.yml
.
:
Publishes:
publish-db-connection-info:
Type: "ENV:NET_TCP:db:connection-info"
● Publish/Subscribe Protocol
● publish-db-connection-info is a script
echo OPENSHIFT_MYSQL_DB_HOST=$OPENSHIFT_GEAR_DNS
echo OPENSHIFT_MYSQL_DB_PORT=$OPENSHIFT_MYSQL_DB_PROXY_PORT
echo OPENSHIFT_MYSQL_DB_URL=”mysql://…/”

14. My Cartridge needs needs to be listening
● Pub/Sub Protocol
● The Type: element determines both the message format and
whether the subscribe hook may be implemented in the
Platform
● A provided hook script will be run in place of Platform code
● manifest.yml
.
:
Subscribes:
set-db-connection-info:
Type: “ENV:NET_TCP:db:connection-info”
Required: false

15. Let the Platform the cartridge can use a database
● Pub/Sub Protocol
● The Type: element determines both the message format and
whether the subscribe hook may be implemented in the
Platform
● A provided hook script will be run in place of Platform code
● manifest.yml
.
:
Subscribes:
set-db-connection-info:
Type: “ENV:NET_TCP:db:connection-info”
Required: false

16. Let the Platform the cartridge can use a database
● Pub/Sub Protocol
● The Type: element determines both the message format and
whether the subscribe hook may be implemented in the
Platform
● A provided hook script will be run in place of Platform code
● manifest.yml
.
:
Subscribes:
set-db-connection-info:
Type: “ENV:NET_TCP:db:connection-info”
Required: false

17. My Cartridge needs to be listening for databases
● Pub/Sub Protocol
● The Type: element determines both the message format and
whether the subscribe hook may be implemented in the
Platform
● A provided hook script will be run in place of Platform code
● manifest.yml
.
:
Subscribes:
set-db-connection-info:
Type: “ENV:NET_TCP:db:connection-info”
Required: false

18. My Cartridge needs to be listening for databases
● Pub/Sub Protocol
● The Type: element determines both the message format and
whether the subscribe hook may be implemented in the
Platform
● A provided hook script will be run in place of Platform code
● manifest.yml
.
:
Subscribes:
set-db-connection-info:
Type: “ENV:NET_TCP:db:connection-info”
Required: false

19. Customize Work Flows
● Cartridge Authors
● Implement additional control actions
● Provide optional scrips
● Application Developers
● .openshift/action_hooks
● .openshift/markers
● git pushed from developers repository

20. For Language Frameworks: A sample application
● template directory
● Checked in as the gear's initial git repository
● A “complete” application demonstrating that your
cartridge is ready for business
● If you should add the manifest element:
● Install-Build-Required: false
● Speeds up the installation of your cartridge
● You need to do work for the application developer

21. Environment Variables
The Node/Application/Gear/Cartridge all have shared
environment variables in their scope
● Node Scope variables
● /etc/openshift/env
● Gear Scope
● .../<gear uuid>/.env
● Application Scope
● .../<gear uuid>/.env/<cartridge name>
● Cartridge Scope
● .../<gear uuid>/<cartridge name>/env

22. Example Platform Environment Variables
● OPENSHIFT_APP_NAME
● OPENSHIFT_APP_DNS
● OPENSHIFT_DATA_DIR
● OPENSHIFT_HOMEDIR
● OPENSHIFT_TMP_DIR
● OPENSHIFT_<SHORT NAME>_DIR
● OPENSHIFT_<SHORT NAME>_IP
● OPENSHIFT_<SHORT NAME>_PORT
● You and application developer use these to tie into the software you
are packaging
● System tracks them and builds the correct process environment for
you

23. Creating An Application With Your Cartridge
● rhc create-app dog001 http://…/metadata/manifest.yml
● Tip: use raw URL from github
● manifest.yml contains Source-Url element
● Source-Url addresses root of your cartridge
● Tip: use download zip file from github repository

24. Tip: Origin VM as a development platform
● http://openshift.github.io/
● Broker-Node communication
● /var/log/mcollective.log
● Node logging
● /var/log/openshift/node/platform.log
● Node detailed logging
● /var/log/openshift/node/platform-trace.log
● Warning: Origin – Fedora 18
Online – RHEL 6

25. Tip: Examples – Online Cartridges
● http://tinyurl.com/online-cartridges
● JBoss EWS: multiple versions of packaged software
and support for multiple java versions
● MySQL: pub/sub database connections
● PHP My Admin: one cartridge dependent on another

26. Tip: Using bash for scripts
● -e and -u options are your friends
● -e exit on error
● -u using unset variable is an error
● -x for debugging
● Bash “SDK” (Library of functions)
● source $OPENSHIFT_CARTRIDGE_SDK_BASH

27. ERB File Rendering
● Unified method of doing value substitutions in
configuration files
● httpd.conf, php.ini, etc
● metadata/managed_files.yml
● processed_templates:
- '**/*.erb'
● All environment variables available
● No code can be executed

28. Title here
Text with no bullets
● Bullets layer one
● Bullets layer two
● Bullets layer three

29. Additional Resources!
● Cartridge Writing Guide:
http://tinyurl.com/writing-cartridges
● IRC Freenode
● #openshift (application developers)
● #openshift-dev (PaaS development)
● #openshift-dev-node (cartridge/node development)
● Email
● dev@lists.openshift.redhat.com

30. For more information:
http://openshift.github.io
Follow us on twitter:
@openshift
Join us on irc (freenode):
openshift