diff --git a/_build_cfg.yml b/_build_cfg.yml index 552971118044..b75065f0f095 100644 --- a/_build_cfg.yml +++ b/_build_cfg.yml @@ -33,3 +33,30 @@ Topics: File: configuring_client_tools - Name: Updating Client Tools File: updating_client_tools + +--- +Name: Reference for Developing Cartridges +Dir: cartridge_specification_guide +Topics: + - Name: Managed Files + File: managed_files + - Name: Locking Cartridges + File: locking_cartridges + - Name: Exposing Services + File: exposing_services + - Name: Creating Template Directories for Language Cartridges + File: creating_template_directories_for_language_cartridges + - Name: Cartridge Scripts + File: cartridge_scripts + - Name: Environment Variables + File: environment_variables + - Name: Cartridge Events + File: cartridge_events + - Name: OpenShift Build Process + File: openshift_build_process + - Name: Backing Up and Restoring Cartridges + File: backing_up_and_restoring_cartridges + - Name: Upgrading Custom and Community Cartridges + File: upgrading_custom_and_community_cartridges + - Name: OpenShift Cartridge Reference + File: openshift_cartridge_reference \ No newline at end of file diff --git a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc new file mode 100644 index 000000000000..dd6b66743269 --- /dev/null +++ b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc @@ -0,0 +1,91 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[backing_up_and_restoring_cartridges]] +== Backing Up and Restoring Cartridges + +OpenShift provides +snapshot+ and +restore+ features for user applications. These features enable OpenShift application developers to: + + +* Snapshot the current state of an application to create a backup. +* Restore an application from an archived state. +* Copy or rename an application by taking a snapshot, creating a new application, then restoring the snapshot data to the new application. + +[[snapshot]] +=== Snapshot + +When an application developer runs the +rhc snapshot save+ command, OpenShift creates an archive of the application and performs the following steps: + +. Stops the application by running the +gear stop+ command. +. Runs the +control pre-snapshot+ command for each cartridge on the gear. You can control cartridge serialization in the snapshot by implementing the +control pre-snapshot+ command in conjunction with exclusions. For example, you can snapshot to a database dump instead of a database file. +. Builds a list of exclusions from the [variable]#snapshot_exclusions## entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file for each cartridge on the gear. +. Creates an archive of the application in [filename]#tar.gz# format and writes it to [literal]#stdout# for use by the client tools. In addition to the files listed in the [variable]#snapshot_exclusions# entry in the [filename]#managed_files.yml# file, OpenShift excludes the following files: + +* Selected gear user files: [filename]#.tmp#, [filename]#.ssh#, [filename]#.sandbox#. + + +* Application state file: [filename]#app-root/runtime/.state#. + + +* Bash history file: [filename]#$OPENSHIFT_DATA_DIR/.bash_history#. + + +. Runs the +control post-snapshot+ command for each cartridge on the gear. Use this script to cleanup after the snapshot runs. + + +. Will either stop or start the gear based on the state of the application before the snapshot. + +*Snapshot Exclusions* + +Use the optional [variable]#snapshot_exclusions# entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file to list files to exclude from the snapshot and restore process. File patterns originate from the [variable]#OPENSHIFT_HOMEDIR# directory, not the cartridge directory. Do not exclude files that your cartridge requires to operate. + + + +.snapshot_exclusions Entry +---- +snapshot_exclusions Entry +snapshot_exclusions: +- mydir/* +---- + +OpenShift uses the +tar+ command when performing snapshots. See the +tar+ man page +--exclude-from+ option for more information. + +[[restore]] +=== Restore + +When an application developer runs the +rhc snapshot restore+ command, OpenShift restores the application from an archive in the following steps: + + +. Prepares the application for restoration. + +* If the archive contains a Git repository, OpenShift runs the +gear pre-receive+ command. + + +* If the archive does not contain a Git repository, OpenShift runs the +gear stop+ command. + +. Runs the +control pre-restore+ command for each cartridge on the gear. This enables you to control the restoration of your cartridge, for example by deleting an old database dump. +. Builds a list of file name changes to apply during the restoration from the [variable]#restore_transforms## entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file for each cartridge on the gear. +. Extracts the archive into the gear user's home directory, overwriting existing files and applying the file name changes listed in the [variable]#restore_transforms# entry in the [filename]#managed_files.yml# file. +. Runs the +control post-restore+ command for each cartridge on the gear. Use this script to load a database flat file into the running database. +. Resumes the application. + +* If the archive contains a Git repository, OpenShift runs the +gear postreceive+ command. +* If the archive does not contain a Git repository, OpenShift runs the +gear start+ command. + +. Will either stop or start the gear based on the state of the application before restoring. + +*Restoring with Transformed File Names* + +Use the optional [variable]#restore_transforms# entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file to provide scripts that transform file names when OpenShift restores an application. This entry enables you to restore older snapshots to a newer cartridge with file name changes. + + +.restore_transforms Entry +---- +restore_transforms: +- s|${OPENSHIFT_GEAR_NAME}/data|app-root/data| +---- + +OpenShift uses the +tar+ command when restoring a gear. See the +tar+ man page +--transform+ option for more information. + diff --git a/cartridge_specification_guide/cartridge_events.adoc b/cartridge_specification_guide/cartridge_events.adoc new file mode 100644 index 000000000000..721b14dbf5bf --- /dev/null +++ b/cartridge_specification_guide/cartridge_events.adoc @@ -0,0 +1,123 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[cartridge_events]] +== Cartridge Events + +OpenShift provides a publish and subscribe system that enables a cartridge to act when a developer adds or removes another cartridge in an application. + +The _Publishes_ and _Subscribes_ elements in the [filename]#$cartridge_name/metadata/manifest.yml# file detail support for cartridge events. + +[[cartridge_event_publishing]] +=== Cartridge Event Publishing + +When OpenShift adds a cartridge to an application, it uses entries in the _Publishes_ section of the [filename]#$cartridge_name/metadata/manifest.yml# file to construct events sent to other cartridges in the application. Define publish events in the [filename]#manifest.yml# file using the following format: + +---- +Publishes: + : + Type: "" +---- + +.PHP Cartridge Publishes Entry +---- +Publishes: + get-php-ini: + Type: "FILESYSTEM:php-ini" + publish-http-url: + Type: "NET_TCP:httpd-proxy-info" + publish-gear-endpoint: + Type: "NET_TCP:gear-endpoint-info" +---- + +For each _Publishes_ entry, OpenShift runs a script named [filename]#$cartridge_name/hooks/$event_name#. + +OpenShift joins lines of output that the [filename]#hooks/$event_name# script writes to [literal]#stdout# with single spaces, then inputs the result to subscriber scripts in other cartridges that match the [variable]#Type# of the publish event. The input to matching subscriber scripts is prefaced with [filename]#hooks/ #. + +[[cartridge_event_subscriptions]] +=== Cartridge Event Subscriptions + +When OpenShift adds a cartridge to an application, it uses entries in the _Subscribes_ section of the [filename]#$cartridge_name/metadata/manifest.yml# file in other cartridges to determine what actions to take for those other cartridges. Define subscribe events in the [filename]#manifest.yml# file using the following format: + +---- +Subscribes: + : + Type: "" +---- + +.PHP Cartridge Subscribes Entry +---- +Subscribes: + set-env: + Type: "ENV:*" + Required: false + set-mysql-connection-info: + Type: "NET_TCP:db:mysql" + Required: false + set-postgres-connection-info: + Type: "NET_TCP:db:postgres" + Required: false + set-doc-url: + Type: "STRING:urlpath" + Required: false +---- + +When OpenShift processes a cartridge publish script, it inputs the result to subscriber scripts in other cartridges that match the [variable]#Type# of the publish event. The input to matching subscriber scripts is prefaced with [filename]#$cartridge_name/hooks/ #. + +For each matching _Subscribes_ entry, OpenShift runs a script named [filename]#$cartridge_name/hooks/$event_name#. OpenShift must send and process entries marked with +Required: true+. + +The publisher script determines the format of the information input to the subscriber script. Ensure that subscriber script can parse the input correctly. + +[[cartridge_event_example]] +=== Cartridge Event Example +In this example, an application developer adds a MySQL database cartridge to a PHP application. The publish and subscribe relationship between the cartridges enables the PHP cartridge to set environment variables on its gear so it can connect to the new MySQL cartridge, which is on a different gear. + +*MySQL Cartridge as Publisher* + +The MySQL cartridge lists a [variable]#publish-mysql-connection-info# event in the _Publishes_ section of its [filename]#mysql/metadata/manifest.yml# file: + +---- +Publishes: + publish-mysql-connection-info: + Type: "NET_TCP:db:mysql" +---- + +The MySQL cartridge implements a script in [filename]#mysql/hooks/publish-mysql-connection-info#. + +*PHP Cartridge as Subscriber* + +The PHP cartridge lists a [variable]#set-mysql-connection-info# event in the _Subscribes_ section of its [filename]#php/metadata/manifest.yml# file: + +---- +Subscribes: + set-mysql-connection-info: + Type: "NET_TCP:db:mysql" +---- + + +The PHP cartridge implements a script in [filename]#php/hooks/set-mysql-connection-info#. + +*Cartridge Event Communication Process* + +OpenShift matches the event [variable]#Type# in the PHP cartridge's _Subscribes_ list to the event [variable]#Type# in the MySQL cartridge's _Publishes_ list. In this example, the event [variable]#Type# is "NET_TCP:db:mysql". + +The MySQL cartridge's [filename]#publish-mysql-connection-info# script outputs the username, host, port, URL, and password required to connect to the MySQL instance: + +---- +OPENSHIFT_MYSQL_DB_USERNAME=username; +OPENSHIFT_MYSQL_DB_PASSWORD=password; +OPENSHIFT_MYSQL_DB_HOST=hostname; +OPENSHIFT_MYSQL_DB_PORT=port; +OPENSHIFT_MYSQL_DB_URL=url; +---- + +OpenShift sends the output of the MySQL cartridge's [filename]#publish-mysql-connection-info# to the PHP cartridge's [filename]#set-mysql-connection-info# script using the following format: + +---- +hooks/publish-mysql-connection-info gear_name namespace gear_uuid 'OPENSHIFT_MYSQL_DB_USERNAME=username;OPENSHIFT_MYSQL_DB_PASSWORD=password;OPENSHIFT_MYSQL_DB_HOST=hostname;OPENSHIFT_MYSQL_DB_PORT=port;OPENSHIFT_MYSQL_DB_URL=url;' +---- + +Note that the publisher script determines the format of the information input to the subscriber script. When writing subscriber scripts, ensure that they parse the input correctly. + diff --git a/cartridge_specification_guide/cartridge_scripts.adoc b/cartridge_specification_guide/cartridge_scripts.adoc new file mode 100644 index 000000000000..d3bef16827f6 --- /dev/null +++ b/cartridge_specification_guide/cartridge_scripts.adoc @@ -0,0 +1,409 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[cartridge_scripts]] +== Cartridge Scripts +Cartridge scripts act as the application programming interface (API) for a cartridge. Use these scripts to contain the required code for single version software that configures easily. For complex configurations and software with multiple versions, use these scripts as shim code to set up the required environment and run additional scripts. You can also create symbolic links from these scripts. + +Cartridge scripts are located in the [filename]#$cartridge_name/bin/# directory, and run from the cartridge's home directory. + +.Required Scripts +[cols="3,7",options="header"] +|=== +|Script Name|Usage + +|setup|Creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. Runs for the initial installation and every upgrade. + +|control + |Enables OpenShift or the application developer to control the state of a cartridge and its packaged software. +|=== + +.Optional Scripts +[cols="3,7",options="header"] +|=== +|Script Name|Usage + +|teardown + |Prepares the gear for cartridge removal. + +|install + |Creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. Runs only on the first installation of the cartridge. + +|post-install + |Configures the cartridge after the cartridge starts. Runs only on the first installation of the cartridge. + +|metrics + |Gathers cartridge level metrics. +|=== + +[[embedded_ruby_processing]] +=== Embedded Ruby (ERB) Processing +Embedded Ruby (ERB) is a templating system that embeds Ruby into a text document. To provide more flexible configuration and environment variable options, OpenShift enables you to provide certain values as ERB templates. For more information on ERB templates, see the link:http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html[ERB documentation at ruby-doc.org]. + +OpenShift renders ERB templates at +$$safe_level 2$$+ and processes them in two passes. For more information on Ruby safe levels, see the link:http://www.ruby-doc.org/docs/ProgrammingRuby/html/taint.html[Programming Ruby documentation at ruby-doc.com]. + +.ERB Processing Passes + +. The first pass processes entries in the [filename]#$cartridge_name/env/# directory. This pass is mandatory, and occurs before OpenShift runs the [filename]#$cartridge_name/bin/setup# script. + + +. The second pass processes entries specified in the process_templates entry of the #$cartridge_name/metadata/managed_files.yml# file. This pass occurs after OpenShift runs the [filename]#$cartridge_name/bin/setup# script, but before it runs the [filename]#$cartridge_name/bin/install# script. This enables the [filename]#setup# script to create or modify ERB templates as required, and for the [filename]#install# script to use the processed values. + +.Environment Variable Template +==== + +ifdef::openshift-online[] +An [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: + +---- +<%= ENV['OPENSHIFT_LOG_DIR'] %> +---- + +---- +/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/mongodb/log/ +---- +endif::[] + +ifdef::openshift-enterprise[] +For OpenShift Enterprise release 2.0, an [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: + +---- +<% ENV['OPENSHIFT_HOMEDIR'] + "/mongodb/log/" %> +---- + +For OpenShift Enterprise release 2.1 and later, an [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: + +---- +<%= ENV['OPENSHIFT_LOG_DIR'] %> +---- + +The value of [envar]#LOG_DIR# for each cartridge is set to the same value as [envar]#OPENSHIFT_LOG_DIR#. + +endif::[] + +From that ERB file, OpenShift creates an [envar]#env/OPENSHIFT_MONGODB_DB_LOG_DIR# environment variable containing: +==== + +.[filename]#php.ini# Configuration Template +==== + +A [filename]#conf/php.ini.erb# file contains: + +---- +upload_tmp_dir = "<%= "#{ENV['OPENSHIFT_PHP_DIR']}tmp/" %>" +session.save_path = "<%= "#{ENV['OPENSHIFT_PHP_DIR']}sessions/" %>" +---- + +From that ERB file, OpenShift creates a [filename]#conf/php.ini# file containing: + +---- +upload_tmp_dir = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/tmp/" +session.save_path = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/sessions/" +---- +==== + +Other possible uses for ERB templates are +includes+ values in *httpd* configuration files, database configuration values for storing persistent data in the [filename]#OPENSHIFT_DATA_DIR# directory, and the application name value in the [filename]#pom.xml# file. + +[[setup_script]] +=== setup Script + +The [filename]#setup# script creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. The [filename]#setup# script must be re-entrant. OpenShift runs the script for every upgrade that is not backward compatible. Add logic you want to run only once to the [filename]#install# script, not the [filename]#setup# script. + +Add files created during setup to the setup_rewritten section of the [filename]#$cartridge_name/metadata/managed_files.yml# file. During an upgrade, OpenShift deletes these files prior to running the [filename]#setup# script. + +If you use ERB templates to configure software, OpenShift processes these files for environment variable substitution after running the [filename]#setup# script. + +[cols="2,7,"] +|=== +|*Synopsis* |+setup [--version ]+ + +|*Options* |The +--version + option selects which version of the cartridge to install. If you do not supply a version, OpenShift installs the version given in the [variable]#Version# element of the [filename]#$cartridge_name/metadata/manifest.yml# file. +|*Lock context* | Unlocked +|=== + + +[[install_script]] +=== install Script +The [filename]#install# script creates and configures files that OpenShift copies from the cartridge repository to the gear's directory. OpenShift runs the [filename]#install# script only on the first installation of a cartridge. + +Put logic for one-time operations, for example generating passwords, creating ssh keys, and adding environment variables, in the [filename]#install# script. + +Report client results and messages with the [filename]#install# script, not the [filename]#setup# script. + +The [filename]#install# script may substitute a version dependent of the _template_ or _template.git_ directories. + +[cols="2,7,"] +|=== +|*Synopsis* |+install [--version ]+ + +|*Options* |The +--version + option selects which version of the cartridge to install. If you do not supply a version, OpenShift installs the version given in the [variable]#Version# element of the [filename]#$cartridge_name/metadata/manifest.yml# file. +|*Lock context* | Unlocked +|=== + +[[post-install_script]] +=== post-install Script +The [filename]#post-install# script configures your cartridge after the cartridge starts. OpenShift only runs the [filename]#post-install# script for the first installation of the cartridge. + +[cols="2,7,"] +|=== +|*Synopsis* |+post-install [--version ]+ + +|*Options* |The +--version + option selects which version of the cartridge to install. If you do not supply a version, OpenShift installs the version given in the [variable]#Version# element of the [filename]#$cartridge_name/metadata/manifest.yml# file. +|*Lock context* | Unlocked +|=== + +[[teardown_script]] +=== teardown Script +The [filename]#teardown# script prepares the gear for cartridge removal. The script only runs when OpenShift removes the cartridge from a gear; it does not run when OpenShift deletes the gear. The gear continues to operate without the functionality of the removed cartridge. + +[cols="2,7,"] +|=== +|*Synopsis* |+teardown+ + +|*Lock context* | Unlocked +|=== + +[[control_script]] +=== control Script +The [filename]#control# script enables OpenShift or the application developer to control the state of a cartridge and its packaged software. + +[cols="2,7,"] +|=== + + +|*Synopsis* |+control + +|*Options* | The ++ option is the action the cartridge performs. + +|*Lock context* | Locked +|=== + +.Control Script Actions +[cols="3,7",options="header"] +|=== +| Action| Result +| update-configuration, pre-build, build, deploy, post-deploy| See link:openshift_build_process.html[OpenShift Build Process] for more information. +| start| Starts the software the cartridge controls. +| stop| Stops the software the cartridge controls. +| status| Returns a zero (0) exit status if the cartridge code is running. +| reload| Instructs the cartridge and its packaged software to reload their configuration information. This action only operates if the cartridge is running. +| restart| Stops the current process and starts a new one for the packaged software. +| threaddump| Signals the packaged software to perform a thread dump, if applicable. +| tidy| Releases unused resources. +| pre-snapshot| Prepares the cartridge for a snapshot. +| post-snapshot| Tidies the cartridge after a snapshot. +| pre-restore| Prepares the cartridge for restoration. +| post-restore| Tidies the cartridge after restoration. +|=== + +*Using the tidy Action* + +By default, the +tidy+ action performs the following operations: + +* Garbage collects the Git repository. +* Removes all files in the [filename]#/tmp# directory. + +Add additional operations to the +tidy+ action by editing the +tidy()+ function in the [filename]#$cartridge_name/bin/control# file. Because applications have limited resources, it is recommended that you tidy thoroughly. + +.Additional +tidy+ Operations +---- +rm $OPENSHIFT_{Cartridge-Short_Name}_DIR/logs/log.[0-9] +cd $OPENSHIFT_REPO_DIR ; mvn clean +---- + +*Using the +status+ Action* + +When the status of your packaged software is queried , use a zero (0) exit status to indicate correct operation. Direct information to an application developer using [literal]#stdout#. Return errors with a non-zero exit status using [literal]#stderr#. + + + +OpenShift maintains the expected state of an application in the [filename]#~/app-root/runtime/.state# file. Do not use this file to determine the status of the packaged software as it contains the expected state of the application, not the current state. + +.Values for [filename]#.state# +[cols="2,7",options="header"] +|=== +| Value| Status +| building| Application is building +| deploying| Application is deploying +| idle| Application is shutdown due to inactivity +| new| A gear exists, but no application is installed +| started| Application started +| stopped| Application is stopped + +|=== + +ifdef::openshift-enterprise[] +[[metrics script]] +=== metrics Script + +With the release of OpenShift Enterprise 2.1, a metrics entry can be added to the cartridge's [filename]#$cartridge_name/metadata/manifest.yml# file to inform OpenShift Enterprise that it supports metrics. + +.Metrics Entry +---- +Metrics: +- enabled +---- + +The [filename]#metrics# script must be an executable file in the [filename]#$cartridge_name/bin/# directory. + +*Message Format* + +A metrics message must include the following fields and be written to standard out (STDOUT): + +---- +type=metric = +---- + +.Metrics Message Example +==== + +---- +type=metric thread.count=5 +---- +==== +endif::[] + + +[[exit_status_codes]] +=== Exit Status Codes + +OpenShift follows the convention that scripts return zero (0) for success and non-zero for failure. + +OpenShift supports special handling of several non-zero exit codes. These codes enable OpenShift to refine its behavior, for example when returning *HTTP* status codes through the REST API or when deciding whether to continue or abort an operation. + +If a cartridge script returns a value not included in the following tables, OpenShift treats the error as fatal to the cartridge. + +.User Errors +[cols="2,7",options="header"] +|=== +| Exit Code| Usage +| 1| Non-specific error +| 97| Invalid user credentials +| 99| User does not exist +| 100| An application with specified name already exists +| 101| An application with specified name does not exist and cannot be operated on +| 102| A user with login already exists +| 103| Given namespace is already in use +| 104| User's gear limit has been reached +| 105| Invalid application name +| 106| Invalid namespace +| 107| Invalid user login +| 108| Invalid SSH key +| 109| Invalid cartridge types +| 110| Invalid application type specified +| 111| Invalid action +| 112| Invalid API +| 113| Invalid auth key +| 114| Invalid auth iv +| 115| Too many cartridges of one type per user +| 116| Invalid SSH key type +| 117| Invalid SSH key name or tag +| 118| SSH key name does not exist +| 119| SSH key or key name not specified +| 120| SSH key name already exists +| 121| SSH key already exists +| 122| Last SSH key for user +| 123| No SSH key for user +| 124| Could not delete default or primary key +| 125| Invalid template +| 126| Invalid event +| 127| A domain with specified namespace does not exist and cannot be operated on +| 128| Could not delete domain because domain has valid applications +| 129| The application is not configured with this cartridge +| 130| Invalid parameters to estimates controller +| 131| Error during estimation +| 132| Insufficient Access Rights +| 133| Could not delete user +| 134| Invalid gear profile +| 135| Cartridge not found in the application +| 136| Cartridge already embedded in the application +| 137| Cartridge cannot be added or removed from the application +| 138| User deletion not permitted for normal or non-subaccount user +| 139| Could not delete user because user has valid domain or applications +| 140| Alias already in use +| 141| Unable to find nameservers for domain +| 150| A plan with specified id does not exist +| 151| Billing account was not found for user +| 152| Billing account status not active +| 153| User has more consumed gears than the new plan allows +| 154| User has gears that the new plan does not allow +| 155| Error getting account information from billing provider +| 156| Updating user plan on billing provider failed +| 157| Plan change not allowed for subaccount user +| 158| Domain already exists for user +| 159| User has additional filesystem storage that the new plan does not allow +| 160| User max gear limit capability does not match with current plan +| 161| User gear sizes capability does not match with current plan +| 162| User max untracked additional filesystem storage per gear capability does not match with current plan +| 163| Gear group does not exist +| 164| User is not allowed to change storage quota +| 165| Invalid storage quota value provided +| 166| Storage value not within allowed range +| 167| Invalid value for nolinks parameter +| 168| Invalid scaling factor provided. Value out of range. +| 169| Could not completely distribute scales_from to all groups +| 170| Could not resolve DNS +| 171| Could not obtain lock +| 172| Invalid or missing private key is required for SSL certificate +| 173| Alias does exist for this application +| 174| Invalid SSL certificate +| 175| User is not authorized to add private certificates +| 176| User has private certificates that the new plan does not allow +| 180| This command is not available in this application +| 181| User maximum tracked additional filesystem storage per gear capability does not match with current plan +| 182| User does not have gear_sizes capability provided by current plan +| 183| User does not have max_untracked_addtl_storage_per_gear capability provided by current plan +| 184| User does not have max_tracked_addtl_storage_per_gear capability provided by current plan +| 185| Cartridge X can not be added without cartridge Y +| 186| Invalid environment variables: expected array of hashes. +| 187| Invalid environment variable X. Valid keys name (required), value +| 188| Invalid environment variable name X: specified multiple times +| 189| Environment name X not found in application +| 190| Value not specified for environment variable X +| 191| Specify parameters name/value or environment_variables +| 192| Environment name X already exists in application +| 193| Environment variable deletion not allowed for this operation +| 194| Name can only contain letters, digits and underscore and cannot begin with a digit +| 210| Cannot override existing location for Git repository +| 211| Parent directory for Git repository does not exist +| 212| Could not find #libra_id_rsa# +| 213| Could not read from SSH configuration file +| 214| Could not write to SSH configuration file +| 215| Host could not be created or found +| 216| Error in Git pull +| 217| Destroy aborted +| 218| Not found response from request +| 219| Unable to communicate with server +| 220| Plan change is not allowed for this account +| 221| Plan change is not allowed at this time for this account. Wait a few minutes and try again. If problem persists contact Red Hat support. +| 253| Could not open configuration file +| 255| Usage error +|=== + +.Uncommon Server Errors +[cols="2,7",options="header"] +|=== +| Exit Code| Usage +| 140| No nodes available. If the problem persists contact Red Hat support. +| 141| Cartridge exception. +| 142| Application is registered to an invalid node. If the problem persists contact Red Hat support. +| 143| Node execution failure. If the problem persists contact Red Hat support. +| 144| Error communicating with user validation system. If the problem persists contact Red Hat support. +| 145| Error communicating with DNS system. If the problem persists contact Red Hat support. +| 146| Gear creation exception. +|=== + +[[communication_between_openShift_and_cartridges]] +=== Communication Between OpenShift and Cartridges + +A cartridge can provide services for use by multiple gears in one application. OpenShift enables you to publish these services. Each message writes to [literal]#stdout# or [literal]#stderr# with an exit status, one message per line. + +.Service Messages +---- +ENV_VAR_ADD: = +CART_DATA: = +CART_PROPERTIES: = +APP_INFO: +---- + diff --git a/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc new file mode 100644 index 000000000000..4fd20372be80 --- /dev/null +++ b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc @@ -0,0 +1,64 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[creating_template_directories_for_language_cartridges]] +== Creating Template Directories for Language Cartridges +Use the [filename]#$cartridge_name/template/# or [filename]#$cartridge_name/template.git/# directory to provide a basic example of an application written in the language or framework your cartridge packages. Welcome the application developer to your cartridge and inform them that the cartridge is operating correctly. + +If you provide a [filename]#$cartridge_name/template.git/# directory, OpenShift copies the directory for the application developer. + +If you provide a [filename]#$cartridge_name/template/# directory, OpenShift uses it to create a Git repository for the application developer. Ensure that your +setup+ and +install+ scripts account for the path change from [filename]#template# to [filename]#template.git#. + +Create [filename]#.gitignore# files in empty directories to ensure the directories are retained when OpenShift builds the Git repository. + +.Ruby Template Directory +A Ruby 1.8 cartridge with Passenger support has a [filename]#template/public/# directory and a [filename]#config.ru# file to define the web application. + +.... ++- template +| +- config.ru +| +- public +| | +- .gitignore +| .openshift +| +- markers +| |- ... +.... + +[[marker_files]] +=== Marker Files +The [filename]#$cartridge_name/template/.openshift/markers/# directory contains example marker files for application developers. These files set conditions for various stages of a cartridge's life cycle. You can add marker files as required to enable application developers to control aspects of your cartridge. + +.Ruby 1.8 Marker Files +|==== +|Marker |Action + +|force_clean_build |OpenShift removes previous output from the +bundle install --deployment+ command and reinstalls all gems according to the current [filename]#Gemfile# and [filename]#Gemfile.lock# files. + +|hot_deploy |OpenShift serves new application code without restarting the application's web server. + +|disable_auto_scaling |OpenShift does not automatically scale a scalable application. +|==== + +[[application_developer_action_hooks]] +=== Action Hooks +The [filename]#$cartridge_name/template/.openshift/action_hooks/# directory contains examples of application developer action hooks that run during the cartridge life cycle. + +.Action Hooks +.... +pre_start_`cartridge name` +post_start_`cartridge name` +pre_stop_`cartridge name` +.... + +OpenShift runs default [filename]#action_hooks# as indicated in the +control+ script. To add additional hooks, run them explicitly in the +control+ script. Ensure appropriate documentation is available for application developers to use the additional hooks correctly. + +If you find that action hooks are not working, they may not be executable. To fix this, run the following command: + +---- +git update-index --chmod=+x .openshift/action_hooks/ +---- + +The +--chmod=$$(+ | -)$$x+ command sets the execute permissions on the updated file specified. + diff --git a/cartridge_specification_guide/enabling_logshifter.adoc b/cartridge_specification_guide/enabling_logshifter.adoc new file mode 100644 index 000000000000..83c1b778177e --- /dev/null +++ b/cartridge_specification_guide/enabling_logshifter.adoc @@ -0,0 +1,35 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[enabling_logshifter]] +== Enabling Logshifter +Using _logshifter_ enables automatic log rotation and consolidation across cartridges in a gear. In OpenShift, cartridges can log to _Syslog_ using _logshifter_. For more information about _logshifter_, see the _logshifter_ [filename]#README# file. + +When writing a cartridge control script, it is typical to spawn a runtime process such as java or mongod. To take advantage of _logshifter_, redirect the standard out (STDOUT) and standard error (STEDRR) streams of the process to the [filename]#/usr/bin/logshifter# file. For example, for a Java-based cartridge. + +.Redirecting Logs with Logshifter +---- +:java ... |& /usr/bin/logshifter -tag my-cartridge & +---- + +Using this method, java is started in the background, and all output produced by the application is logged through _logshifter_. The [parameter]#-tag# argument must be a string unique to the cartridge. + +*Tips for PID Management* + +In the previous example, the standard pipe operator is used from a shell script to redirect logs from the cartridge process to _logshifter_. This works well for programs which are capable of managing a PID file internally. However, for cartridges which bootstrap a process and cannot manage a PID file by itself, using a simple pipe operator can be problematic. When piping programs using a shell, the programs are typically started in parallel, rendering the [variable]#$!# variable unreliable for determining the PID of the cartridge process. For these cases, setting up a named pipe can allow the cartridge to use _logshifter_ and also manage the PID of the process. The following example demonstrates the setup of a named pipe used by a Java cartridge which preserves the reliability of [variable]#$!# so the cartridge script can manage the PID file manually. + +.Setting Up Named Pipe +---- +LOGPIPE=${OPENSHIFT_HOMEDIR}/app-root/runtime/logshifter-my-cartridge +rm -f $LOGPIPE && mkfifo $LOGPIPE + +/usr/bin/logshifter -tag my-cartridge < $LOGPIPE & +java ... &> $LOGPIPE & +echo $! > $OPENSHIFT_MY_CARTRIDGE_DIR/my-cartridge.pid +---- + +Setting up the named pipe manually provides the most flexibility for managing both the _logshifter_ and cartridge processes. + + diff --git a/cartridge_specification_guide/environment_variables.adoc b/cartridge_specification_guide/environment_variables.adoc new file mode 100644 index 000000000000..cc434b22d52c --- /dev/null +++ b/cartridge_specification_guide/environment_variables.adoc @@ -0,0 +1,151 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[environment_variables]] +== Environment Variables +OpenShift uses environment variables to communicate information between cartridges, applications, and the system. + +OpenShift provides several system environment variables that are available for use at all cartridge entry points. + +Place cartridge environment variables in the [filename]#$cartridge_name/env/# directory. OpenShift loads cartridge variables after system environment variables, but before calling your code. + +[[system_environment_variables]] +=== System Environment Variables + +OpenShift provides several system environment variables. These variables are read-only. + +.System Environment Variables +[cols="4,7",options="header"] +|=== +|Name|Value + +| + HOME + | + Alias for [variable]#OPENSHIFT_HOMEDIR#. + +| + HISTFILE + | + Bash history file. + +| + OPENSHIFT_APP_DNS + | + The fully qualified domain name of the application using your cartridge. + +| + OPENSHIFT_APP_NAME + | + The name of the application using your cartridge. Assigned by the application developer. + +| + OPENSHIFT_APP_UUID + | + The UUID of the application using your cartridge. Assigned by OpenShift. + +| + OPENSHIFT_DATA_DIR + | + The directory where the application and your cartridge store data. + +| + OPENSHIFT_GEAR_DNS + | + The fully qualified domain name of the gear where your cartridge is installed. This may not be the same as [variable]#OPENSHIFT_APP_DNS#. + +| + OPENSHIFT_GEAR_NAME + | + The name of the gear where your cartridge is installed. Assigned by OpenShift. This may not be the same as [variable]#OPENSHIFT_APP_NAME#. + +| + OPENSHIFT_GEAR_UUID + | + The UUID of the gear where your cartridge is installed. Assigned by OpenShift. + +| + OPENSHIFT_HOMEDIR + | + The home directory of the gear where your cartridge is installed. Assigned by OpenShift. + +| + OPENSHIFT_REPO_DIR + | + The directory where the application repository is stored. OpenShift runs the application from this location. + +| + OPENSHIFT_TMP_DIR + | + The directory where the application and your cartridge store temporary data. + +| + TMP + | + Alias for [variable]#OPENSHIFT_TMP_DIR#. + +| + TMPDIR + | + Alias for [variable]#OPENSHIFT_TMP_DIR#. +|=== + +[[cartridge_environment_variables]] +=== Cartridge Environment Variables +OpenShift provides three environment variables for all cartridges by default. These variables are read-only. + +.Cartridge Environment Variables +[options="header"] +|=== +| Name|Value + +| + OPENSHIFT_{Cartridge-Short-Name}_DIR + | + The directory where cartridge information is installed. + +| + OPENSHIFT_{Cartridge-Short-Name}_IDENT + | + The identity of the cartridge, sourced from its [filename]#manifest.yml# file. The format is *Cartridge-Vendor:Version:Cartridge-Version*. + +| + OPENSHIFT_PRIMARY_CARTRIDGE_DIR + | + The directory where the primary cartridge on a gear is installed. For example, a scaling PHP application has both a PHP cartridge and a HAProxy cartridge installed on the head gear. In this case, the PHP cartridge is the primary cartridge. +|=== + + +[[custom_cartridge_environment_variables]] +=== Custom Cartridge Environment Variables +You can add custom environment variables to a cartridge by adding them to the cartridge's [filename]#$cartridge_name/env/# directory or creating them with the cartridge's [filename]#setup# and [filename]#install# scripts. + +Entries in a cartridge's [filename]#$cartridge_name/env/# directory do not override system-provided environment variables. Using system-provided environment variable names in the [filename]#$cartridge_name/env/# directory prevents the cartridge from installing correctly. + +Prefix custom environment variables with [variable]#OPENSHIFT_{cartridge short name}# to prevent overwriting other cartridge variables in the packaged software's process environment space. + +Suffix directory environment variables with _DIR and the value with a backslash (/). + +You can provide Embedded Ruby (ERB) templates for environment variables in the [filename]#$cartridge_name/env/# directory. OpenShift processes ERB templates in this directory before calling the cartridge's [filename]#setup# script. + +OpenShift sets the PATH variable using the path [filename]#/etc/openshift/env/PATH3#. If you provide [variable]#OPENSHIFT_{Cartridge-Short-Name}_PATH_ELEMENT#, OpenShift uses the value to build the PATH when your scripts run or an application developer performs an interactive log on. + + +[IMPORTANT] +==== +OpenShift does not validate cartridge-provided environment variables. A cartridge can fail to function if its environment variable files contain invalid data. +==== + +*Packaged Software Environment Variables* + +If your cartridge packages software with its own environment variables, add these variables to the cartridge's [filename]#$cartridge_name/env/# directory or include them in the shim code of the scripts in the [filename]#$cartridge_name/bin/# directory. + +.Jenkins Environment Variables +---- +JENKINS_URL +JENKINS_USERNAME +JENKINS_PASSWORD +---- + diff --git a/cartridge_specification_guide/exposing_services.adoc b/cartridge_specification_guide/exposing_services.adoc new file mode 100644 index 000000000000..63a963cb1e2d --- /dev/null +++ b/cartridge_specification_guide/exposing_services.adoc @@ -0,0 +1,258 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[exposing_services]] +== Exposing Services +Most cartridges provide services by binding to ports. Cartridges must declare to which ports they bind, and provide variable names to describe: + +* The IP addresses provided to the cartridge for binding. +* The local gear ports to which the cartridge services bind. +* The public proxy ports that expose local gear ports for communication between related gears in an application, such as the TCP proxy public endpoint. (Optional) +* TCP endpoint mappings that establish a front end for application users. (Optional) + +[[tCP_endpoints]] +=== TCP Endpoints +TCP endpoints are services that are exposed by a cartridge, and are accessible by other cartridges or gears in an application. They may be any protocol which uses TCP, such as *http* or *mysql*. These services may also be exposed to application users through mappings. OpenShift only creates endpoint ports for scalable applications. + +The endpoints can be defined in the [variable]#Endpoints# section of the [filename]#$cartridge_name/metadata/manifest.yml# file. + +.Endpoints Entry +---- +Endpoints: + - Private-IP-Name: + Private-Port-Name: + Private-Port: + Public-Port-Name: + [variable]#Protocols#: [,] + [variable]#Mappings#: + - Frontend: '' + Backend: '' + Options: { ... } + - <...> + - <...> +---- + +When a cartridge is installed on a gear, it automatically assigns IP addresses to each IP variable name ensuring that assigned addresses can bind to the specified port. + +If an endpoint specifies a public port variable, a public port proxy mapping is created using a random external port accessible through the gear's DNS entry. + +*Endpoint Environment Variables* + +Endpoint values are exposed to cartridge scripts and application code through environment variables. These environment variables are formed from the [variable]#Cartridge-Short-Name# element and from the endpoint variable names specified in the [filename]#manifest.yml# file. + +.Environment Variable Format +---- +OPENSHIFT_{Cartridge-Short-Name}_{name of IP variable} => +OPENSHIFT_{Cartridge-Short-Name}_{name of port variable} => +OPENSHIFT_{Cartridge-Short-Name}_{name of public port variable} => +---- + +*Endpoint Protocols* + +You can define the protocols for services using the [variable]#Protocols# variable. [variable]#Protocols# takes a comma-separated list of protocol types from the following available options: + +.Endpoint Protocols +[cols="3,7",options="header"] +|=== +|Protocol|Description + +|tcp|TCP + +|http|HTTP + +|https|HTTP Secure (HTTP over SSL/TLS) + +|ws|WebSocket + +| + wss + | + WebSocket Secure (WebSocket over SSL/TLS) + +| + tls + | + SNI Proxy + +| + mongodb + | + MongoDB + +| + mysql + | + MySQL + +| + postgresql + | + PostgreSQL +|=== + +If the [variable]#Protocols# list is not set, the default behavior matches the pre-[variable]#Protocols# behavior. For example, if an endpoint has [variable]#Mappings#, assume HTTP; otherwise, assume TCP. The front-end modules also translate [variable]#Mappings# options. For example, if a [variable]#Mappings# entry has [literal]#websocket# set in its [variable]#Options#, then [literal]#ws# is added to the [variable]#Protocols# list. + +*Endpoint Mappings* + +If an endpoint specifies [variable]#Mappings#, a front-end httpd route to the cartridge is created for each mapping entry using the provided options. The Frontend key is a front-end path element connected to a back-end URI specified by the [variable]#Backend# key. The [variable]#Options# hash enables additional route configuration options. + +.Endpoint Mapping Options +[cols="3,7",options="header"] +|=== +|Option|Description + +|websocket|Enable WebSocket on a particular path + +| + gone + | + Mark the path as gone (URI is ignored) + +| + forbidden + | + Mark the path as forbidden (URI is ignored) + +| + noproxy + | + Mark the path as not proxied (URI is ignored) + +| + redirect + | + Use redirection to URI instead of proxy (URI must be a path) + +| + file + | + Ignore request and load file path contained in URI (must be a path) + +| + tohttps + | + Redirect request to HTTPS and use the path contained in the URI (must be a path) +|=== + +[[endpoint_example]] +=== TCP Endpoint Example +This section provides an example [variable]#Endpoints# entry in a [filename]#$cartridge_name/metadata/manifest.yml# file, and demonstrates how OpenShift uses this entry to create environment variables, public proxy port mappings, and *httpd* routes. + +.Endpoints Entry +---- +Name: CustomCart +Cartridge-Short-Name: CUSTOMCART + +... + +Endpoints: + - Private-IP-Name: HTTP_IP + Private-Port-Name: WEB_PORT + Private-Port: 8080 + Public-Port-Name: WEB_PROXY_PORT + [variable]#Protocols#: [ws] + [variable]#Mappings#: + - Frontend: '/web_front' + Backend: '/web_back' + - Frontend: '/socket_front' + Backend: '/socket_back' + Options: { "websocket": true } + + - Private-IP-Name: HTTP_IP + Private-Port-Name: ADMIN_PORT + Private-Port: 9000 + Public-Port-Name: ADMIN_PROXY_PORT + [variable]#Protocols#: [http] + [variable]#Mappings#: + - Frontend: '/admin_front' + - Backend: '/admin_back' + + - Private-IP-Name: INTERNAL_SERVICE_IP + Private-Port-Name: 5544 + Public-Port-Name: INTERNAL_SERVICE_PORT +---- + +*Environment Variables* + +Several environment variables are created for the cartridge using the information in the [variable]#Endpoints# entry. + +.Environment Variables +---- +# Internal IP/port allocations +OPENSHIFT_CUSTOMCART_HTTP_IP= +OPENSHIFT_CUSTOMCART_WEB_PORT=8080 +OPENSHIFT_CUSTOMCART_ADMIN_PORT=9000 +OPENSHIFT_CUSTOMCART_INTERNAL_SERVICE_IP= +OPENSHIFT_CUSTOMCART_INTERNAL_SERVICE_PORT=5544 + +# Public proxy port mappings +OPENSHIFT_CUSTOMCART_WEB_PROXY_PORT= +OPENSHIFT_CUSTOMCART_ADMIN_PROXY_PORT= +---- + +*Proxy Port Mapping* + +Proxy port mapping is assigned using the information in the [variable]#Endpoints# entry. + +.Proxy Port Mapping +---- +: => OPENSHIFT_CUSTOMCART_HTTP_IP:OPENSHIFT_CUSTOMCART_WEB_PORT +: => OPENSHIFT_CUSTOMCART_HTTP_IP:OPENSHIFT_CUSTOMCART_ADMIN_PORT +---- + +*httpd Routing* + +The *httpd* routes are assigned using the [variable]#Endpoints# entry. + +.httpd Routing +---- +http:///web_front => http://OPENSHIFT_CUSTOMCART_HTTP_IP:8080/web_back +http:///socket_front => http://OPENSHIFT_CUSTOMCART_HTTP_IP:8080/socket_back +http:///admin_front => http://OPENSHIFT_CUSTOMCART_HTTP_IP:9000/admin_back +---- + +[[custom_http_services]] +=== Custom HTTP Services +With ERB templates you can expose cartridge services using an application's URL by placing the Apache configuration code in the [filename]#httpd.d# directory. + +After OpenShift runs the cartridge [filename]#setup# script, it processes each ERB template and writes the contents of the node's *httpd* configuration. + +.mongodb.conf.erb File +---- +Alias /health <%= ENV['OPENSHIFT_HOMEDIR'] + "/mongodb/httpd.d/health.html" %> +Alias / <%= ENV['OPENSHIFT_HOMEDIR'] + "/mongodb/httpd.d/index.html" %> +---- + +[[enabling_custom_paths_for_Websockets]] +=== Enabling Custom Paths for Websockets +Websockets are used to create real-time events initiated by an OpenShift application. + +The ability to add a custom path for websocket URLs to a cartridge must be enabled in that cartridge's _manifest.yml_ file before it can be used in a new application. Add the following information to the [filename]#/usr/libexec/openshift/cartridges/Cart_Name/metadata/manifest.yml# file of the desired cartridge: + +---- +- Private-IP-Name: IP2 + Private-Port-Name: PORT2 + Private-Port: 8080 + Public-Port-Name: PROXY_PORT2 + [variable]#Protocols#: + - http + - ws + [variable]#Mappings#: + - Frontend: '/file_path' + Backend: '/file_path2' + Options: + websocket: true +---- + +This adds a second endpoint to a cartridge with [literal]#ws# listed in the protocols and websockets set to +true+. + +After a cartridge has been modified to use custom paths for websocket URLs, a new application can then be created with the modified cartridge. The application is accessible using the new endpoint, as shown in the following example: + +---- +ws://app-domain.example.com:8000/file_path +---- + + + diff --git a/cartridge_specification_guide/images/4411.png b/cartridge_specification_guide/images/4411.png new file mode 100644 index 000000000000..3e630b839800 Binary files /dev/null and b/cartridge_specification_guide/images/4411.png differ diff --git a/cartridge_specification_guide/images/icon.svg b/cartridge_specification_guide/images/icon.svg new file mode 100644 index 000000000000..10467e12dd94 --- /dev/null +++ b/cartridge_specification_guide/images/icon.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/cartridge_specification_guide/images/icons/caution.png b/cartridge_specification_guide/images/icons/caution.png new file mode 100644 index 000000000000..9a8c515a109f Binary files /dev/null and b/cartridge_specification_guide/images/icons/caution.png differ diff --git a/cartridge_specification_guide/images/icons/example.png b/cartridge_specification_guide/images/icons/example.png new file mode 100644 index 000000000000..1199e864f850 Binary files /dev/null and b/cartridge_specification_guide/images/icons/example.png differ diff --git a/cartridge_specification_guide/images/icons/important.png b/cartridge_specification_guide/images/icons/important.png new file mode 100644 index 000000000000..be685cc4ecc7 Binary files /dev/null and b/cartridge_specification_guide/images/icons/important.png differ diff --git a/cartridge_specification_guide/images/icons/note.png b/cartridge_specification_guide/images/icons/note.png new file mode 100644 index 000000000000..f087c73b7aef Binary files /dev/null and b/cartridge_specification_guide/images/icons/note.png differ diff --git a/cartridge_specification_guide/images/icons/originalnote.png b/cartridge_specification_guide/images/icons/originalnote.png new file mode 100644 index 000000000000..7c1f3e2fa7ef Binary files /dev/null and b/cartridge_specification_guide/images/icons/originalnote.png differ diff --git a/cartridge_specification_guide/images/icons/warning.png b/cartridge_specification_guide/images/icons/warning.png new file mode 100644 index 000000000000..d41edb9adbf2 Binary files /dev/null and b/cartridge_specification_guide/images/icons/warning.png differ diff --git a/cartridge_specification_guide/locking_cartridges.adoc b/cartridge_specification_guide/locking_cartridges.adoc new file mode 100644 index 000000000000..23471ecc67b6 --- /dev/null +++ b/cartridge_specification_guide/locking_cartridges.adoc @@ -0,0 +1,71 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[locking_cartridges]] +== Locking Cartridges +Cartridge instances on a gear are either locked or unlocked at any given time. Locking a cartridge enables cartridge scripts to have greater access to the gear's files and directories. Application developers have read and write access to unlocked files, and read-only access to locked files. This means that application scripts and hooks cannot override cartridge code when the cartridge is locked. + +OpenShift controls the lock state of cartridges, moving them between locked and unlocked at various points in the cartridge life cycle. + +A cartridge with no locked_files entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file is permanently unlocked. This approach is not recommended, but it may be sufficient for simple cartridges. + + +[NOTE] +==== +Cartridge file locking is not a security measure. It is designed to prevent application developers from accidentally breaking their applications by modifying cartridge files. +==== + +[[lock_Cconfiguration]] +=== Cartridge Lock Configuration +The locked_files entry in the [filename]#$cartridge_name/metadata/managed_files.yml# file lists files and directories that OpenShift locks at certain points during the cartridge life cycle. + +If a file in the [parameter]#locked_files# list does not exist, OpenShift creates the file before your +setup+ script is called. OpenShift also creates missing directories if required. + +If files require application developers to have read and write access to them while an application is deploying and running, do not allow OpenShift to create them from the [parameter]#locked_files# list. For example, create [filename]#~/.node-gyp# and [filename]#~/.npm# in a node.js cartridge using a +setup+ or +install+ script. + +Entries that begin with [filename]#~/# start at the gear directory. All other entries start at the cartridge directory. Entries that end with a forward slash (/) are treated as directories. Entries that end with an asterisk (*) are treated as lists of files. Entries that end with any other character are treated as files. + +[NOTE] +==== +OpenShift does not change entry types. For example, if you enter a directory without a forward slash (/) at the end, OpenShift treats it as a file. A cartridge can fail to operate if its locked_files entries are not accurate. +==== + +.PHP locked_files Configuration Entry +---- +locked_files: +- ~/.pearrc +- bin/ +- conf/* +---- + +[cols=".^2,7",options="header"] +|=== + +|File |Description + +|[filename]#~/.pearrc#| When locked, you can edit this file but application developers cannot. +|[filename]#php/bin/# |The directory is locked but not the files it contains. Only you can add files to the directory, but both you and application developers can edit those files. +|[filename]#php/conf/*# |The directory is not locked, but the files in the directory are locked. Both you and application developers can add files to the directory, but only you can edit them. +|=== + +*Reserved Files* + +All visible files and directories in a gear's home directory are reserved. Certain hidden files are also reserved. While a cartridge is unlocked, you can create any unreserved hidden file or directory in the gear's home directory. + +//[cols="1"] +//|=== + +//|[filename]#~/.ssh# +//|[filename]#~/.sandbox# +//|[filename]#~/.tmp# +//|[filename]#~/.env# +//|=== + + +* [filename]#~/.ssh# +* [filename]#~/.sandbox# +* [filename]#~/.tmp# +* [filename]#~/.env# + diff --git a/cartridge_specification_guide/managed_files.adoc b/cartridge_specification_guide/managed_files.adoc new file mode 100644 index 000000000000..5621ca051468 --- /dev/null +++ b/cartridge_specification_guide/managed_files.adoc @@ -0,0 +1,80 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[managed_files]] +== Managed Files +Managed files are files that have non-default settings, or that require special handling by OpenShift. + +The [filename]#$cartridge_name/metadata/managed_files.yml# file lists managed files and strings that OpenShift uses during different stages of the cartridge life cycle. + +*File Patterns* + +Most entries in the [filename]#$managed_files.yml# file use file patterns. OpenShift treats these patterns like shell globs. Dir.glob processes entries that contain asterisk (*) symbols using the [parameter]#File::FNM_DOTMATCH# flag. It treats entries that end in a forward slash (/) as directories, and other entries as files. For more information on globs, see link:$$http://ruby-doc.org/core-1.9.3/Dir.html#method-c-glob$$[]. + +Entries that begin with [filename]#~/# start at the gear directory. All other entries start at the cartridge directory. + +*Strings* + +Some entries allow string values. These values return directly without any modification. + +.Supported Managed File Entries +|=== +|Entry |Type|Usage|Reference + +| + [parameter]#locked_files# + | + File Pattern + | + Files that an application developer can read but not update + |link:/cartridge_spec_guide/locking_cartridges[Locking Cartridges] +| + [parameter]#snapshot_exclusions# + | + File Pattern + | + Array of file names not to backup from the gear when +rhc snapshot+ runs + |link:/cartridge_spec_guide/backing_up_and_restoring_cartridges[Backing Up and Restoring Cartridges] +| + [parameter]#setup_rewritten# + | + File Pattern + | + Files that are removed before running +setup+ + |link:/cartridge_spec_guide/cartridge_scripts[Cartridge Scripts] +| + [parameter]#process_templates# + | + File Pattern + | + ERB templates that are rendered after running +setup+ + |link:/cartridge_spec_guide/cartridge_scripts#embedded_ruby_processing[Embedded Ruby (ERB) Processing] +| + [parameter]#restore_transforms# + | + Strings + | + Set of regex transforms for rewriting file names when +rhc restore+ is run. + |link:/cartridge_spec_guide/backing_up_and_restoring_cartridges[Backing Up and Restoring Cartridges] +|=== + +The following example demonstrates the structure of a basic [filename]#$managed_files.yml# file: + +.managed_files.yml +---- +locked_files: +- env/ +- ~/.foorc +snapshot_exclusions: +- mydir/* +restore_transforms: +- s|${OPENSHIFT_GEAR_NAME}/data|app-root/data| +process_templates: +- +**/*.erb +setup_rewritten: +- conf/* +---- + diff --git a/cartridge_specification_guide/openshift_build_process.adoc b/cartridge_specification_guide/openshift_build_process.adoc new file mode 100644 index 000000000000..11c08424ad10 --- /dev/null +++ b/cartridge_specification_guide/openshift_build_process.adoc @@ -0,0 +1,120 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[openShift_build_process]] +== OpenShift Build Process +When changes to an application's Git repository are pushed, OpenShift builds and deploys the application using the updated repository. The build and deploy process changes if the application is scaling or if it uses a builder cartridge. + +[[default_build_lifecycle]] +=== Default Build Life Cycle +If no builder cartridge is present, OpenShift executes the default build life cycle when an application developer pushes changes to an application Git repository. The default life cycle consists of a +build+, +preparation+, +distribute+, and +deploy+ phase. + +In the default build life cycle, OpenShift manages the starting and stopping of the application, and moves the updated code into [filename]#$OPENSHIFT_REPO_DIR#. The primary cartridge and application developer action hooks in [filename]#$OPENSHIFT_REPO_DIR/.openshift/action_hooks# determine specific behaviors during this process. + +*Build Phase* + +During the build phase, OpenShift: + +. Runs the +gear stop+ command to stop the application. +. Runs the +control pre-receive+ command on the primary cartridge. +. Runs the +control pre-repo-archive+ command on the primary cartridge. +. Creates a new application directory: [filename]#$OPENSHIFT_HOMEDIR/app-deployments/$date_$time# and dependent subdirectories. ++ +[NOTE] +==== +If your cartridge requires a particular directory structure for dependencies, create a symbolic link for your cartridge directory structure into [filename]#$OPENSHIFT_DEPENDENCIES_DIR#. Use [filename]#$OPENSHIFT_BUILD_DEPENDENCIES_DIR# for build time only dependencies. +==== + +. Copies [filename]#$OPENSHIFT_HOMEDIR/app-root/runtime/dependencies# from the active application to [filename]#$OPENSHIFT_HOMEDIR/app-deployments/$date_$time/dependencies#. +. Removes previous applications starting from the oldest until the number set at [filename]#$OPENSHIFT_KEEP_DEPLOYMENTS# is reached. +. Copies the new application source code to [filename]#$OPENSHIFT_REPO_DIR#. This is the only point in the build life cycle when OpenShift copies the application source code. +. Runs the _control pre-build_ command on the primary cartridge. +. Runs the +pre-build+ user action hook, if present. +. Runs the +control build+ command on the primary cartridge. +. Runs the +build+ user action hook, if present. + +*Preparation Phase* + +During the preperation, OpenShift: + +. Runs the +prepare+ user action hook, if present. +. Calculates the application ID and checksum of the application contents. +. Creates [filename]#$OPENSHIFT_HOMEDIR/app-deployments/by-id/$deployment_id# and points to [filename]#../app-deployments/$date_time# + +*Distribute Phase* + +During the distribute phase, OpenShift synchronizes the new application with all child gears if the application is scalable. + +*Deploy Phase* + +During the deploy phase, OpenShift: + +. Updates [filename]#$OPENSHIFT_HOMEDIR/app-root/runtime/repo# so it points to [filename]#../../app-deployments/$date_$time/repo# +. Updates [filename]#$OPENSHIFT_HOMEDIR/app-root/runtime/dependencies# so it points to [filename]#../../app-deployments/$date_$time/dependencies# +. Runs the +control update-configuration+ command on the primary cartridge. +. Starts all secondary cartridges in the application. +. Runs the +control deploy+ command on the primary cartridge. +. Runs the +deploy+ user action hook, if present. +. Starts the primary cartridge using the +gear start+ command. +. Runs the +control post-deploy+ command on the primary cartridge. +. Runs the +post-deploy+ user action hook, if present. + + +[[default_scaling_build_lifecycle]] +=== Default Scaling Build Life Cycle +On the head gear, where the web proxy runs, the build phase for a scalable application is the same as the default build phase for a non-scaleable application. The deploy phase for a scalable applications is different. + +*Deploy Phase* + + +. OpenShift starts the secondary cartridges on the application's head gear. +. OpenShift runs the web proxy's +deploy+ hook on the head gear. +. The web proxy runs deployment steps on the application's secondary gears. For example, the default web proxy, HAProxy, preforms the following steps: +.. It stops the secondary gears. +.. It synchronizes the code and build artifacts from the head gear to the secondary gears. +.. It runs the primary cartridge's +control update-configuration+ command on the secondary gears. +.. It starts all the secondary cartridges on the secondary gears. +.. It runs the primary cartridge's +control deploy+ command on the secondary gears. +.. It runs the +deploy+ user action hook, if present, on the secondary gears. +.. It starts the primary cartridge on the secondary gears. The application is now running on the secondary gears. +.. It runs the primary cartridge's +control post-deploy+ command on the secondary gears. +.. It runs the +post-deploy+ user action hook, if present, on the secondary gears. +. OpenShift runs the primary cartridge's +control deploy+ command on the head gear. +. OpenShift runs the +deploy+ user action hook, if present, on the head gear. +. OpenShift starts the primary cartridge on the head gear. +. OpenShift runs the primary cartridge's +control post-deploy+ command on the head gear. +. OpenShift runs the +post-deploy+ user action hook, if present, on the head gear. + +The build is now complete, and the scaleable application is running. + +[[builder_cartridge_lifecycle]] +=== Builder Cartridge Life Cycle +If an application includes a builder cartridge, OpenShift does not perform build tasks. Instead, the builder cartridge runs the build process. + +During the Git +pre-receive+ hook, OpenShift runs the builder cartridge's +control pre-receive+ command. + +During the Git +post-receive+ hook, OpenShift runs the builder cartridge's +control post-receive+ command. + +[NOTE] +==== +Build processes use the application developer's gear resources to run. When implementing a builder cartridge, do not copy source code or build artifacts more than necessary. +==== + +[[archiving_applications]] +=== Archiving Applications +Current applications can be archived and re-deployed later. Archive an application with the following command: + +---- +$ rhc archive-deployment +---- + +[[binary_deployment]] +=== Binary Deployment +Binary deployment is very similar to build and deploy without the build. Instead, the built artifacts and dependencies are provided and the deploy steps start at +prepare+. Enable binary deployment with the following command: + +---- +$ rhc app configure --deployment-type binary +---- + diff --git a/cartridge_specification_guide/openshift_cartridge_reference.adoc b/cartridge_specification_guide/openshift_cartridge_reference.adoc new file mode 100644 index 000000000000..adda5c3ba4ad --- /dev/null +++ b/cartridge_specification_guide/openshift_cartridge_reference.adoc @@ -0,0 +1,351 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[openShift_cartridge_reference]] +== OpenShift Cartridge Reference +This topic contains reference material for OpenShift cartridges. + +[[cartridge_hierarchy]] +=== Cartridge Hierarchy +OpenShift cartridges use a hierarchy so that multiple cartridges can be collocated or combined on one gear. This hierarchy consists of a single, _primary_ cartridge, along with a combination of _embedded_ cartridges. The primary cartridge controls the application build life cycle, responds to scaling events, and provides external network accessibility. The embedded cartridges support the _primary_ cartridge and provide additional capabilities to applications. + +A good example of this hierarchy is the relationship between the _jenkins_ cartridge and the jenkins-client cartridge. While the _jenkins_ cartridge provides a fully functional browser based Jenkins service, the _jenkins-client_ cartridge is embedded in web applications to offload application builds to an existing Jenkins service. Note that the _jenkins-client_ cartridge by itself provides no value and must be combined with an existing _primary_ cartridge. + +[[cartridge_directory_structure]] +=== Cartridge Directory Structure +The required directories of a cartridge must conform to a set structure or the cartridge can fail to function properly. You can add additional directories and files as needed to support the function of your cartridge. + +* _Required_ files must exist for minimal OpenShift support of the cartridge. + + +* _Discretionary_ files are recommended, but not necessary. For example, [filename]#conf.d# is the standard file where a web framework installs its *httpd* configuration. + + +* _Optional_ files are not necessary. Use optional files to support additional cartridge functionality. + +.Cartridge Directory Structure +image::4411.png[Cartridge Directory Structure] + +To support multiple software versions within one cartridge, create symbolic links between the [filename]#$cartridge_name/bin/control# file and the [filename]#$cartridge_name/versions/$software_version/bin/control# file. Alternatively, use the [filename]#$cartridge_name/bin/control# file as a shim to call the [filename]#control# file for the desired version. + +When creating an instance of your cartridge for use by a gear, OpenShift copies the files, links, and directories from the cartridge library, with the exception of the [filename]#$cartridge_name/usr/# directory. The [filename]#$cartridge_name/usr/# directory is symbolically linked to the gear's cartridge instance. This link enables all cartridge instances to share libraries and other data. + +See link:locking_cartridges[Locking Cartridges] for more information on customizing a cartridge instance. + +[[cartridge_metadata_elements]] +=== Cartridge Metadata Elements + +OpenShift uses a [filename]#manifest.yml# file located in the [filename]#$cartridge_name/metadata/# directory to determine the features a cartridge requires. OpenShift also uses data from the [filename]#manifest.yml# file to provide information about the cartridge to users. + +.manifest.yml File +---- +Name: PHP +Cartridge-Short-Name: PHP +Cartridge-Version: '1.0.1' +Compatible-Versions: + - '1.0.1' +Cartridge-Vendor: redhat +Display-Name: PHP 5.4 +Description: "PHP is a general-purpose server-side scripting language..." +Version: '5.4' +Versions: + - '5.4' +License: "The PHP License, version 3.0" +License-Url: http://www.php.net/license/3_0.txt +Vendor: PHP Group +Categories: + - service + - php + - web_framework +Website: http://www.php.net +Help-Topics: + "Developer Center": https://openshift.redhat.com/community/developers +Cart-Data: + - Key: OPENSHIFT_... + Type: environment + Description: "How environment variable should be used" +Provides: + - php-5.4 + - "php" +Publishes: + get-php-ini: + Type: "FILESYSTEM:php-ini" + publish-http-url: + Type: "NET_TCP:httpd-proxy-info" + publish-gear-endpoint: + Type: "NET_TCP:gear-endpoint-info" +Subscribes: + set-db-connection-info: + Type: "NET_TCP:db:connection-info" + Required: false + set-nosql-db-connection-info: + Type: "NET_TCP:nosqldb:connection-info" + Required: false + set-mysql-connection-info: + Type: "NET_TCP:db:mysql" + Required : false + set-postgres-connection-info: + Type: "NET_TCP:db:postgres" + Required : false + set-doc-url: + Type: "STRING:urlpath" + Required : false +Scaling: + Min: 1 + Max: -1 +Group-Overrides: + - components: + - php-5.4 + - web_proxy +Endpoints: + - Private-IP-Name: IP1 + Private-Port-Name: HTTP_PORT + Private-Port: 8080 + Public-Port-Name: PROXY_HTTP_PORT + Mappings: + - Frontend: '/front' + Backend: '/back' +Additional-Control-Actions: + - threaddump +---- + +[[cartridge-short-name]] +==== Cartridge-Short-Name +OpenShift creates several environment variables when installing a cartridge. The [variable]#Cartridge-Short-Name# element forms part of these environment variable names. + +.Cartridge-Short-Name Entry for a PHP cartridge +---- +Cartridge-Short-Name: PHP +---- + +Environment variables use *PHP* in their name: + +---- +OPENSHIFT_PHP_DIR +OPENSHIFT_PHP_IP +OPENSHIFT_PHP_PORT +OPENSHIFT_PHP_PROXY_PORT +---- + +[[cartridge-version]] +==== Cartridge-Version +The [variable]#Cartridge-Version# element identifies the release version of a cartridge. The value uses the format: + +---- +[.[.[...]]] +---- + +For example: + +---- +Cartridge-Version: '1.0.3' +---- + +When you publish a new version of a cartridge, OpenShift uses the [variable]#Cartridge-Version# value to determine upgrade requirements for applications that use the cartridge. YAML treats [variable]#number.number# as a float but OpenShift requires a string for this value, so the value must be enclosed in single quotes ('). + +[[compatible-versions]] +==== Compatible-Versions +The [variable]#Compatible-Versions# element is a list of previous cartridge versions that are compatible with the current cartridge version. + +.Compatible-Versions Entry +---- +Compatible-Versions: ['1.0.1'] +---- + +To be compatible with a previous version, the code changes in the current cartridge version must not require a restart of the cartridge or of an application using the cartridge. + +If the previous cartridge version is not in the [variable]#Compatible-Versions# list when you update the cartridge to a new version, OpenShift stops the cartridge, installs the new code, runs +setup+, and restarts the cartridge. This process results in a short amount of downtime for applications that use the cartridge. + +[[cartridge-vendor]] +==== Cartridge-Vendor +The [variable]#Cartridge-Vendor# element identifies the creator of a cartridge. OpenShift uses this value to differentiate between similar cartridges installed on the system. You can use a company name or an individual identifier for this value. + +.Cartridge-Vendor Entry +---- +Cartridge-Vendor: redhat +---- + +[[version]] +==== Version +The [variable]#Version# element is the default version of the software packaged in the cartridge. + +.Version Entry +---- +Version: '5.3' +---- + +[[versions]] +==== Versions +The [variable]#Versions# element is the list of software versions packaged in the cartridge. + +.Versions Entry +---- +Versions: ['5.3'] +---- + +[[categories]] +==== Categories +The [variable]#Categories# element is a list of classifications for a particular cartridge, and contains two distinct groups: + +* _system_ categories +* _descriptive_ categories + +===== System Categories + +The _system_ categories are special to the platform and influence the system behavior, and contain subcategories that are described in the following table. + +.Subcategories of _system_ categories +[cols="2,7",options="header"] +|=========== +|Subcategory |Description +|web_framework |Describes cartridges that accept inbound HTTP, HTTPS, and WebSocket requests. SSL termination occurs at the platform layer before cartridge interaction. The original inbound protocol is passed to the cartridge using the [literal]#X-Forwarded-Proto# header. An application can have one cartridge from the _web_framework_ category. + +|web_proxy| Describes cartridges that route web traffic to the application's gears. When a scalable application is created with a cartridge from the _web_framework_ category, a _web_proxy_ cartridge is automatically added to enable the auto scaling feature. Therefore, when a _web_framework_ cartridge has to scale beyond a single gear, the _web_proxy_ cartridge automatically routes to the endpoint defined by the [literal]#Public-Port-Name# with the [parameter]#PROXY_PORT# value. The _web_proxy_ cartridge is automatically updated over HTTP with routing rules of the new gears as they are added. An application can have one cartridge from the _web_proxy_ category. + +|service |Describes add-on cartridges that are not based on HTTP, such as MySQL. The _service_ category cartridges can scale independently, but may not be addressable outside of the platform. Therefore, OpenShift applications must have at least one _web_framework_ category cartridge so that the application's DNS registration contains at least one addressable HTTP endpoint. However, most applications consist of a _web_framework_ category cartridge and other cartridges from the service category. Therefore, using the _service_ category to classify a cartridge, such as MySQL, installs the cartridge on a separate gear from that of the _web_framework_ cartridge. This allows both cartridges to scale independently. + +|plugin| This is similar to the _embedded_ category, but for scalable applications. It describes cartridges that can be collocated with other cartridges in scalable applications. The _plugin_ category uses defined [literal]#Group-Overrides# to determine the collocation between cartridges. For example, the [literal]#Group-Overrides# can specify that a Cron cartridge must be collocated with the _web_framework_ category cartridge. + +|embedded| Describes cartridges that are always collocated or installed with any other _primary_ cartridge in non-scalable applications. For example, the Jenkins client cartridge can be combined with any web application cartridge to offload the builds to a Jenkins service. + +|plug-in| This is similar to the _embedded_ category, but for scalable applications. It describes cartridges that can be collocated with other cartridges in scalable applications. The _plugin_ category uses defined [literal]#Group-Overrides# to determine the collocation between cartridges. For example, the [literal]#Group-Overrides# can specify that a Cron cartridge must be collocated with the _web_framework_ category cartridge. + +|domain_scope| Describes cartridges that can only have a single instance within a domain. For example, the Jenkins server cartridge contains the _domain_scope_ category to ensure that there is only one Jenkins server application within an entire domain. The Jenkins client cartridge is embedded in all other applications to enable builds that are handled by the Jenkins server. +|=========== + + +[[descriptive_categories]] +===== Descriptive Categories +The _descriptive_ categories are arbitrary classifications that improve the searching of cartridges in the Management Console and the client tools to improve the overall user experience. In the Management Console, the _descriptive_ categories are used as tags that allow users to search and filter the available cartridges. + +When using the client tools, the _descriptive_ categories are used to apply matching logic to cartridge operations. For example, if a user runs the +rhc add-cartridge php+ command, the _descriptive_ categories are searched along with the names of the cartridges. + +[[group-overrides]] +==== Group-Overrides +By default, each cartridge in a scalable application resides on its own gear within its own group instance. [variable]#Group-Overrides# can be used when you wish to have two cartridges located on the same set of gears. For example, if you create a Cron cartridge and wish to collocate that with a _web_framework_ category cartridge, you can do so as shown in the following example. + +.Group-Overrides with Cron and web_framework Cartridges +---- +Group-Overrides: +- components: + - web_framework + - cron +---- + +In cases where you wish to collocate a _web_framework_ category cartridge with a _web_proxy_ category cartridge, you can do so as shown in the following example. + +.Group-Overrides with web_framework and web_proxy Cartridges +---- +Group-Overrides: +- components: + - web_proxy + - web_framework +---- + +[[scaling]] +==== Scaling +When a cartridge is added to a scalable application, the [parameter]#Min# and [parameter]#Max# parameters define the scaling limits for that cartridge. If both the [parameter]#Min# and [parameter]#Max# values are set to 1, this means that the cartridge cannot scale. If the [parameter]#Max# value is set to -1, the cartridge can scale up to the user's maximum gear limit. These limits are applicable for both automatic and manual scaling of cartridges. + +Note that when using [variable]#Group-Overrides# to collocate two or more scalable cartridges, the scaling limits of both cartridges must match. However, there may be cases where this limitation may not be ideal; for example, a _web_proxy_ category cartridge collocated with a _web_framework_ category cartridge. In such a case, it is not recommended to have the _web_proxy_ cartridge be located on every gear that holds the _web_framework_ cartridge. The [parameter]#Multiplier# parameter allows you to place a cartridge only on certain gears within a group instance, rather than all of them. For example, if the [parameter]#Multiplier# is set to 3, every third gear within the group instance gets the cartridge installed on it. If it is set to 1, then the cartridge gets installed on all gears within the group instance. + +[[source-url]] +==== Source-Url +The [variable]#Source-Url# element is the location from which OpenShift downloads cartridge files during application creation. + +.Supported Source Schemes +[options="header"] +|=== +|Scheme|Method|Expected Inputs + +| + git + | + clone + | + git repo + +| + https + | + GET + | + zip, tar, tag.gz, tgz + +| + http + | + GET + | + zip, tar, tag.gz, tgz + +| + file + | + file copy + | + cartridge directory tree +|=== + +.Source-Url Entry +---- +Source-Url Entry +Source-Url: https://github.com/example/killer-cartridge.git +Source-Url: git://github.com/chrisk/fakeweb.git +Source-Url: https:://www.example.com/killer-cartridge.zip +Source-Url: https://github.com/example/killer-cartridge/archive/master.zip +---- + +[[source-md5]] +==== Source-Md5 +The Source-Md5 element is an MD5 digest. If OpenShift downloads a cartridge not using a Git scheme, it verifies the downloaded file against this MD5 digest. + +.Source-Md5 Entry +---- +Source-Md5 Entry +Source-Md5: 835ed97b00a61f0dae2e2b7a75c672db +---- + +[[additional-control-actions]] + +==== Additional-Control-Actions + +The Additional-Control-Actions element is a list of optional actions a cartridge supports. OpenShift can only call optional actions if they are included in this element. + +.Additional-Control-Actions Entry +---- +Additional-Control-Actions: + - threaddump +---- + +[[endpoints]] +==== Endpoints + +See link:exposing_services[Exposing Services]. + +[[example_openshift.conf.erb_file]] +=== Example openshift.conf.erb File +*httpd* is a common base for OpenShift cartridges. You can use this example [filename]#conf.d/openshift.conf.erb# file as a starting point for writing a cartridge based on *httpd*. + +---- +ServerRoot "<%= ENV['OPENSHIFT_HOMEDIR'] + "/ruby-1.8" %>" +DocumentRoot "<%= ENV['OPENSHIFT_REPO_DIR'] + "/public" %>" +Listen <%= ENV['OPENSHIFT_RUBY_IP'] + ':' + ENV['OPENSHIFT_RUBY_PORT'] %> +User <%= ENV['OPENSHIFT_GEAR_UUID'] %> +Group <%= ENV['OPENSHIFT_GEAR_UUID'] %> + +ErrorLog "|/usr/sbin/rotatelogs <%= ENV['OPENSHIFT_HOMEDIR']%>/ruby-1.8/logs/error_log-%Y%m%d-%H%M%S-%Z 86400" +CustomLog "|/usr/sbin/rotatelogs <%= ENV['OPENSHIFT_HOMEDIR']%>/logs/access_log-%Y%m%d-%H%M%S-%Z 86400" combined + +PassengerUser <%= ENV['OPENSHIFT_GEAR_UUID'] %> +PassengerPreStart http://<%= ENV['OPENSHIFT_RUBY_IP'] + ':' + ENV['OPENSHIFT_RUBY_PORT'] %>/ +PassengerSpawnIPAddress <%= ENV['OPENSHIFT_RUBY_IP'] %> +PassengerUseGlobalQueue off +/public> + AllowOverride all + Options -MultiViews + + +---- + diff --git a/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc new file mode 100644 index 000000000000..8c3498919257 --- /dev/null +++ b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc @@ -0,0 +1,84 @@ +OpenShift Documentation Project +DOC_BRANCH_VERSION +:data-uri: +:icons: + +[[upgrading_custom_and_community_Cartridges]] +== Upgrading Custom and Community Cartridges +The OpenShift runtime contains a system for upgrading custom cartridges on a gear to the latest available version and for applying gear-level changes that affect cartridges. + +ifdef::openshift-online[] +The +oo-admin-upgrade+ command provides the command line interface for the upgrade system and can upgrade all the gears in an OpenShift environment, all the gears on a node, or a single gear. This command queries the OpenShift broker to determine the locations of the gears to migrate and uses MCollective calls to trigger the upgrade for a gear. +endif::[] + +ifdef::openshift-enterprise[] +The +oo-admin-upgrade+ command on the broker host provides the command line interface for the upgrade system and can upgrade all the gears in an environment, all the gears on a node, or a single gear. This command queries the OpenShift broker to determine the locations of the gears to migrate and uses MCollective calls to trigger the upgrade for a gear. +endif::[] + +*Upgrade Process Overview* + +. Load the gear upgrade extension, if configured. +. Inspect the gear state. +. Run the gear extension's _pre-upgrade_ script, if it exists. +. Compute the upgrade itinerary for the gear. +. If the itinerary contains an incompatible upgrade, stop the gear. +. Upgrade the cartridges in the gear according to the itinerary. +. Run the gear extension's _post-upgrade_ script, if it exists. +. If the itinerary contains an incompatible upgrade, restart and validate the gear. +. Clean up after the upgrade by deleting _pre-upgrade_ state and upgrade metadata. + +[[upgrade_itinerary]] +=== Upgrade Itinerary +The upgrade process must be re-entrant; if it fails or times out, a subsequent upgrade operation must pick up where the last one left off. The upgrade itinerary stores information about which cartridges in a gear to upgrade and which type of upgrade to perform. + +There are two types of cartridge upgrade processes: compatible and incompatible. The [literal]#Compatible-Versions# element in a cartridge's [filename]#$cartridge_name/metadata/manifest.yml# file determines whether the new version is compatible with a previous version. The main difference between the compatible and incompatible upgrade processes is that an incompatible cartridge's gear stops during an upgrade, while a compatible cartridge's gear continues to run. + +*Upgrade Itinerary Configuration* + +. Read in the current [variable]#IDENT# of the cartridge. +. Determine the name and software version of the cartridge in the cartridge repository; this provides the manifest for the latest version of the cartridge. If a manifest does not exist in the cartridge repository or does not include the software version, skip the cartridge. +. If the latest manifest is for the same cartridge version as the version currently installed on the gear, skip the cartridge unless the [parameter]#ignore_cartridge_version# parameter is set. If the [parameter]#ignore_cartridge_version# parameter is set, record an incompatible upgrade for the cartridge in the itinerary. +. If the latest manifest includes the current cartridge version in the [literal]#Compatible-Versions# element, record a compatible upgrade for the cartridge in the itinerary. Otherwise, record an incompatible upgrade for the cartridge in the itinerary. + +[[compatible_upgrades]] +=== Compatible Upgrades + +If the upgrade itinerary records a compatible upgrade for a cartridge, OpenShift uses the following process: + +*Compatible Upgrade Process* + +. Overlay the new version of the cartridge on the gear. +. Remove the files declared in the [literal]#Processed-Templates# element of the cartridge's [filename]#managed-files.yml#. +. Unlock the cartridge directory. +. Secure the cartridge directory. +. Run the cartridge's +upgrade+ script, if it exists. +. Lock the cartridge directory. + +[[incompatible_upgrades]] +=== Incompatible Upgrades +If the upgrade itinerary records an incompatible upgrade for a cartridge, OpenShift uses the following process: + +*Incompatible Upgrade Process* + +. Remove the files and directories declared in the [literal]#Setup-Rewritten# element of the cartridge's [filename]#managed_files.yml#. +. Overlay the new version of the cartridge on the gear. +. Unlock the cartridge directory. +. Secure the cartridge directory. +. Run the cartridge's +upgrade+ script, if it exists. +. Run the cartridge's +setup+ script. +. Process the cartridge's ERB templates. +. Lock the cartridge directory. +. Create new endpoints for the cartridge. +. Connect the frontend. + +[[cartridge_upgrade_script]] +=== Cartridge Upgrade Script +You can provide a cartridge +upgrade+ script in the [filename]#$cartridge_name/bin/# directory to run during the upgrade process. The +upgrade+ script enables you to perform actions during the upgrade process that the compatible or incompatible processes do not perform. If you provide an +upgrade+ script, OpenShift passes it the following arguments: + + +* The software version of the cartridge. +* The current cartridge version. +* The cartridge version being upgraded to. + +A non-zero exit code from this script results in the upgrade operation failing. +