diff --git a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc index dd6b66743269..d194342d1b9a 100644 --- a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc +++ b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc @@ -1,11 +1,9 @@ += Backing Up and Restoring Cartridges 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: @@ -14,7 +12,7 @@ OpenShift provides +snapshot+ and +restore+ features for user applications. Thes * Copy or rename an application by taking a snapshot, creating a new application, then restoring the snapshot data to the new application. [[snapshot]] -=== Snapshot +== Snapshot When an application developer runs the +rhc snapshot save+ command, OpenShift creates an archive of the application and performs the following steps: @@ -53,7 +51,7 @@ snapshot_exclusions: OpenShift uses the +tar+ command when performing snapshots. See the +tar+ man page +--exclude-from+ option for more information. [[restore]] -=== Restore +== Restore When an application developer runs the +rhc snapshot restore+ command, OpenShift restores the application from an archive in the following steps: diff --git a/cartridge_specification_guide/cartridge_events.adoc b/cartridge_specification_guide/cartridge_events.adoc index 721b14dbf5bf..9a4ceb323c87 100644 --- a/cartridge_specification_guide/cartridge_events.adoc +++ b/cartridge_specification_guide/cartridge_events.adoc @@ -1,17 +1,15 @@ += Cartridge Events 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. +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 +== 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: @@ -37,7 +35,7 @@ For each _Publishes_ entry, OpenShift runs a script named [filename]#$cartridge_ 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 +== 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: @@ -71,7 +69,7 @@ For each matching _Subscribes_ entry, OpenShift runs a script named [filename]#$ 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 +== 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* diff --git a/cartridge_specification_guide/cartridge_scripts.adoc b/cartridge_specification_guide/cartridge_scripts.adoc index d3bef16827f6..6f67142436e2 100644 --- a/cartridge_specification_guide/cartridge_scripts.adoc +++ b/cartridge_specification_guide/cartridge_scripts.adoc @@ -1,10 +1,9 @@ += Cartridge Scripts 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. @@ -39,7 +38,7 @@ Cartridge scripts are located in the [filename]#$cartridge_name/bin/# directory, |=== [[embedded_ruby_processing]] -=== Embedded Ruby (ERB) 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]. @@ -53,7 +52,6 @@ OpenShift renders ERB templates at +$$safe_level 2$$+ and processes them in two .Environment Variable Template ==== - ifdef::openshift-online[] An [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: @@ -65,7 +63,6 @@ An [filename]#env/OPENSHIFT_MONGODB_DB_LOG_DIR.erb# file contains: /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: @@ -80,22 +77,20 @@ For OpenShift Enterprise release 2.1 and later, an [filename]#env/OPENSHIFT_MONG ---- 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: ==== +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: ---- @@ -107,7 +102,7 @@ session.save_path = "/var/lib/openshift/aa9e0f66e6451791f86904eef0939e/php/sessi 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 +== 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. @@ -125,7 +120,7 @@ If you use ERB templates to configure software, OpenShift processes these files [[install_script]] -=== 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. @@ -143,7 +138,7 @@ The [filename]#install# script may substitute a version dependent of the _templa |=== [[post-install_script]] -=== 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,"] @@ -155,7 +150,7 @@ The [filename]#post-install# script configures your cartridge after the cartridg |=== [[teardown_script]] -=== 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,"] @@ -166,7 +161,7 @@ The [filename]#teardown# script prepares the gear for cartridge removal. The scr |=== [[control_script]] -=== 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,"] @@ -235,7 +230,7 @@ OpenShift maintains the expected state of an application in the [filename]#~/app ifdef::openshift-enterprise[] [[metrics script]] -=== 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. @@ -395,7 +390,7 @@ If a cartridge script returns a value not included in the following tables, Open |=== [[communication_between_openShift_and_cartridges]] -=== 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. diff --git a/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc index 4fd20372be80..c6347ee28e47 100644 --- a/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc +++ b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc @@ -1,10 +1,9 @@ += Creating Template Directories for Language Cartridges 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. @@ -27,7 +26,7 @@ A Ruby 1.8 cartridge with Passenger support has a [filename]#template/public/# d .... [[marker_files]] -=== 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 @@ -42,7 +41,7 @@ The [filename]#$cartridge_name/template/.openshift/markers/# directory contains |==== [[application_developer_action_hooks]] -=== 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 diff --git a/cartridge_specification_guide/enabling_logshifter.adoc b/cartridge_specification_guide/enabling_logshifter.adoc index 83c1b778177e..e27cc02d4417 100644 --- a/cartridge_specification_guide/enabling_logshifter.adoc +++ b/cartridge_specification_guide/enabling_logshifter.adoc @@ -1,10 +1,9 @@ += Enabling Logshifter 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. @@ -30,6 +29,5 @@ 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. +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 index cc434b22d52c..9927e9186f50 100644 --- a/cartridge_specification_guide/environment_variables.adoc +++ b/cartridge_specification_guide/environment_variables.adoc @@ -1,10 +1,9 @@ += Environment Variables 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. @@ -12,7 +11,7 @@ OpenShift provides several system environment variables that are available for u 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 +== System Environment Variables OpenShift provides several system environment variables. These variables are read-only. @@ -93,7 +92,7 @@ OpenShift provides several system environment variables. These variables are rea |=== [[cartridge_environment_variables]] -=== Cartridge Environment Variables +== Cartridge Environment Variables OpenShift provides three environment variables for all cartridges by default. These variables are read-only. .Cartridge Environment Variables @@ -119,7 +118,7 @@ OpenShift provides three environment variables for all cartridges by default. Th [[custom_cartridge_environment_variables]] -=== 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. diff --git a/cartridge_specification_guide/exposing_services.adoc b/cartridge_specification_guide/exposing_services.adoc index 63a963cb1e2d..c8c63f6f1428 100644 --- a/cartridge_specification_guide/exposing_services.adoc +++ b/cartridge_specification_guide/exposing_services.adoc @@ -1,10 +1,9 @@ += Exposing Services 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. @@ -13,7 +12,7 @@ Most cartridges provide services by binding to ports. Cartridges must declare to * TCP endpoint mappings that establish a front end for application users. (Optional) [[tCP_endpoints]] -=== 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. @@ -137,7 +136,7 @@ If an endpoint specifies [variable]#Mappings#, a front-end httpd route to the ca |=== [[endpoint_example]] -=== TCP 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 @@ -226,7 +225,7 @@ Alias / <%= ENV['OPENSHIFT_HOMEDIR'] + "/mongodb/httpd.d/index.html" %> ---- [[enabling_custom_paths_for_Websockets]] -=== 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: @@ -253,6 +252,3 @@ After a cartridge has been modified to use custom paths for websocket URLs, a ne ---- ws://app-domain.example.com:8000/file_path ---- - - - diff --git a/cartridge_specification_guide/locking_cartridges.adoc b/cartridge_specification_guide/locking_cartridges.adoc index 23471ecc67b6..4e2b8c3c306e 100644 --- a/cartridge_specification_guide/locking_cartridges.adoc +++ b/cartridge_specification_guide/locking_cartridges.adoc @@ -1,10 +1,9 @@ += Locking Cartridges 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. @@ -18,7 +17,7 @@ Cartridge file locking is not a security measure. It is designed to prevent appl ==== [[lock_Cconfiguration]] -=== Cartridge Lock Configuration +== 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. diff --git a/cartridge_specification_guide/managed_files.adoc b/cartridge_specification_guide/managed_files.adoc index 5621ca051468..485c590e9226 100644 --- a/cartridge_specification_guide/managed_files.adoc +++ b/cartridge_specification_guide/managed_files.adoc @@ -1,10 +1,9 @@ += Managed Files 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. diff --git a/cartridge_specification_guide/openshift_build_process.adoc b/cartridge_specification_guide/openshift_build_process.adoc index 11c08424ad10..053ce9bee811 100644 --- a/cartridge_specification_guide/openshift_build_process.adoc +++ b/cartridge_specification_guide/openshift_build_process.adoc @@ -1,14 +1,13 @@ += OpenShift Build Process 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 +== 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. @@ -63,7 +62,7 @@ During the deploy phase, OpenShift: [[default_scaling_build_lifecycle]] -=== Default Scaling Build Life Cycle +== 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* @@ -90,7 +89,7 @@ On the head gear, where the web proxy runs, the build phase for a scalable appli The build is now complete, and the scaleable application is running. [[builder_cartridge_lifecycle]] -=== Builder Cartridge Life Cycle +== 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. @@ -103,7 +102,7 @@ Build processes use the application developer's gear resources to run. When impl ==== [[archiving_applications]] -=== Archiving Applications +== Archiving Applications Current applications can be archived and re-deployed later. Archive an application with the following command: ---- @@ -111,7 +110,7 @@ $ rhc archive-deployment ---- [[binary_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: ---- diff --git a/cartridge_specification_guide/openshift_cartridge_reference.adoc b/cartridge_specification_guide/openshift_cartridge_reference.adoc index adda5c3ba4ad..9fb3f5ad0cb9 100644 --- a/cartridge_specification_guide/openshift_cartridge_reference.adoc +++ b/cartridge_specification_guide/openshift_cartridge_reference.adoc @@ -1,20 +1,19 @@ += OpenShift Cartridge Reference 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 +== 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 +== 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. @@ -35,7 +34,7 @@ When creating an instance of your cartridge for use by a gear, OpenShift copies See link:locking_cartridges[Locking Cartridges] for more information on customizing a cartridge instance. [[cartridge_metadata_elements]] -=== 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. @@ -112,7 +111,7 @@ Additional-Control-Actions: ---- [[cartridge-short-name]] -==== 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 @@ -130,7 +129,7 @@ OPENSHIFT_PHP_PROXY_PORT ---- [[cartridge-version]] -==== Cartridge-Version +=== Cartridge-Version The [variable]#Cartridge-Version# element identifies the release version of a cartridge. The value uses the format: ---- @@ -146,7 +145,7 @@ 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 +=== 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 @@ -159,7 +158,7 @@ To be compatible with a previous version, the code changes in the current cartri 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 +=== 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 @@ -168,7 +167,7 @@ Cartridge-Vendor: redhat ---- [[version]] -==== Version +=== Version The [variable]#Version# element is the default version of the software packaged in the cartridge. .Version Entry @@ -177,7 +176,7 @@ Version: '5.3' ---- [[versions]] -==== Versions +=== Versions The [variable]#Versions# element is the list of software versions packaged in the cartridge. .Versions Entry @@ -186,13 +185,13 @@ Versions: ['5.3'] ---- [[categories]] -==== 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 +==== 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. @@ -217,13 +216,13 @@ The _system_ categories are special to the platform and influence the system beh [[descriptive_categories]] -===== 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 +=== 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 @@ -245,13 +244,13 @@ Group-Overrides: ---- [[scaling]] -==== 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 +=== Source-Url The [variable]#Source-Url# element is the location from which OpenShift downloads cartridge files during application creation. .Supported Source Schemes @@ -298,7 +297,7 @@ Source-Url: https://github.com/example/killer-cartridge/archive/master.zip ---- [[source-md5]] -==== 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 @@ -308,8 +307,7 @@ Source-Md5: 835ed97b00a61f0dae2e2b7a75c672db ---- [[additional-control-actions]] - -==== 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. @@ -320,12 +318,12 @@ Additional-Control-Actions: ---- [[endpoints]] -==== Endpoints +=== Endpoints See link:exposing_services[Exposing Services]. [[example_openshift.conf.erb_file]] -=== 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*. ---- diff --git a/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc index 8c3498919257..5f0796b37e56 100644 --- a/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc +++ b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc @@ -1,10 +1,9 @@ += Upgrading Custom and Community Cartridges 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[] @@ -28,7 +27,7 @@ endif::[] . Clean up after the upgrade by deleting _pre-upgrade_ state and upgrade metadata. [[upgrade_itinerary]] -=== 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. @@ -41,7 +40,7 @@ There are two types of cartridge upgrade processes: compatible and incompatible. . 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 +== Compatible Upgrades If the upgrade itinerary records a compatible upgrade for a cartridge, OpenShift uses the following process: @@ -55,7 +54,7 @@ If the upgrade itinerary records a compatible upgrade for a cartridge, OpenShift . Lock the cartridge directory. [[incompatible_upgrades]] -=== Incompatible Upgrades +== Incompatible Upgrades If the upgrade itinerary records an incompatible upgrade for a cartridge, OpenShift uses the following process: *Incompatible Upgrade Process* @@ -72,7 +71,7 @@ If the upgrade itinerary records an incompatible upgrade for a cartridge, OpenSh . Connect the frontend. [[cartridge_upgrade_script]] -=== 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: