anchor.diff:  toc::[]
   
   == Overview
  -When creating Docker images to run on OpenShift, there are a number of best practices to consider as an image author to ensure a good experience for consumers of those images. Because images are intended to be immutable and used as is, the following guidelines help ensure that your images are highly consumable and easy to use on OpenShift.
  +When creating Docker images to run on OpenShift, there are a number of best practices to consider as an image author to ensure a good experience for consumers of those images. Because images are intended to be immutable and used as-is, the following guidelines help ensure that your images are highly consumable and easy to use on OpenShift.
   
   == General Docker Guidelines
   The following guidelines apply when creating a Docker image in general, and are independent of whether the images are used on OpenShift. Also see the following references for more comprehensive guidelines:
  
positive.code: For more information on how Volumes are used in OpenShift, see https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/volumes.md[this documentation]. (NOTE to docs team:  this link should really go to something in the openshift docs, once we have it)
  ////
  
  NOTE: Even with persisted volumes, each instance of your image has its own volume, and the filesystem is not shared between instances.  This means the volume cannot be used to share state in a cluster.
  
  == OpenShift-Specific Guidelines
  The following are guidelines that apply when creating Docker images specifically for use on OpenShift.
  
negative.code: 
  It is best to avoid running [sysitem]#SSHD# in your image. For accessing running containers, You can use the `docker exec` command locally to access containers that are running. Alternatively, you can use the OpenShift tooling since it allows you to execute arbitrary commands in images that are running. Installing and running [sysitem]#SSHD# in your image opens up additional vectors for attack and requirements for security patching.
  
  *Use Volumes for Persistent Data*
  
  Images should use a https://docs.docker.com/reference/builder/#volume[Docker volume] for persistent data. This way OpenShift mounts the network storage to the node running the container, and if the container moves to a new node the storage is reattached to that node. By using the volume for all persistent storage needs, the content is preserved even if the container is restarted or moved. If your image writes data to arbitrary locations within the container, that content might not be preserved.
  
  All data that needs to be preserved even after the container is destroyed must be written to a volume.  With Docker 1.5, there will be a `readonly` flag for containers which can be used to strictly enforce good practices about not writing data to ephemeral storage in a container. Designing your image around that capability now will make it easier to take advantage of it later.
  
  