Chapter 3. 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 Enterprise 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 $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.

3.1. Cartridge Lock Configuration

The locked_files entry in the $cartridge_name/metadata/managed_files.yml file lists files and directories that OpenShift Enterprise locks at certain points during the cartridge life cycle.
If a file in the locked_files list does not exist, OpenShift Enterprise creates the file before your setup script is called. OpenShift Enterprise 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 Enterprise to create them from the locked_files list. For example, create ~/.node-gyp and ~/.npm in a node.js cartridge using a setup or install script.
Entries that begin with ~/ 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 Enterprise does not change entry types. For example, if you enter a directory without a forward slash (/) at the end, OpenShift Enterprise treats it as a file. A cartridge can fail to operate if its locked_files entries are not accurate.

Example 3.1. PHP locked_files Configuration Entry

locked_files:
- ~/.pearrc
- bin/
- conf/*
Explanation:
  • ~/.pearrc: when locked, you can edit this file but application developers cannot.
  • 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.
  • 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.

Reserved Hidden Files

  • ~/.ssh
  • ~/.sandbox
  • ~/.tmp
  • ~/.env