Merge pull request openshift#9247 from adellape/arbdockerimg

Rename 'Other Container Images' topic, add security warning

Author: adellape

_topic_map.yml

@@ -983,11 +983,6 @@ Topics:
     File: mongodb
   - Name: MariaDB
     File: mariadb
-- Name: Docker Images
-  Dir: docker_images
-  Topics:
-  - Name: Overview
-    File: index
 - Name: Other Images
   Dir: other_images
   Topics:
@@ -997,6 +992,8 @@ Topics:
     File: jenkins
   - Name: Jenkins Slaves
     File: jenkins_slaves
+  - Name: Other Container Images
+    File: other_container_images
 - Name: xPaaS Middleware Images
   Dir: xpaas_images
   Distros: openshift-online,openshift-enterprise,openshift-dedicated

creating_images/guidelines.adoc

@@ -21,7 +21,8 @@ consumable and easy to use on {product-title}.
 The following guidelines apply when creating a container image in general, and are
 independent of whether the images are used on {product-title}.
 
-*Reuse Images*
+[discrete]
+===== Reuse Images
 
 Wherever possible, we recommend that you base your image on an appropriate
 upstream image using the `FROM` statement. This ensures your image can easily
@@ -33,7 +34,8 @@ make it clear to users exactly which version of an image your image is based on.
 Using a tag other than `latest` ensures your image is not subjected to breaking
 changes that might go into the `latest` version of an upstream image.
 
-*Maintain Compatibility Within Tags*
+[discrete]
+===== Maintain Compatibility Within Tags
 
 When tagging your own images, we recommend that you try to maintain backwards
 compatibility within a tag. For example, if you provide an image named
@@ -49,7 +51,8 @@ new version at will, but not be inadvertently broken by the new incompatible
 image. Any downstream consumer using _foo:latest_ takes on the risk of any
 incompatible changes being introduced.
 
-*Avoid Multiple Processes*
+[discrete]
+===== Avoid Multiple Processes
 
 We recommend that you do not start multiple services, such as a database and
 *SSHD*, inside one container. This is not necessary because containers
@@ -63,7 +66,8 @@ less frequently and independently. Signal handling flows are also clearer with a
 single process as you do not need to manage routing signals to spawned
 processes.
 
-*Use `exec` in Wrapper Scripts*
+[discrete]
+===== Use `exec` in Wrapper Scripts
 
 See the "Always `exec` in Wrapper Scripts" section of the
 http://www.projectatomic.io/docs/docker-image-author-guidance[Project Atomic
@@ -82,7 +86,8 @@ init system (PID 1)"] blog article for a deep dive on PID 1 and *init*
 systems.
 
 
-*Clean Temporary Files*
+[discrete]
+===== Clean Temporary Files
 
 All temporary files you create during the build process should be removed. This
 also includes any files added with the `ADD` command.  For example, we strongly
@@ -119,7 +124,8 @@ them, where possible, so they do not end up written to a layer.
 In addition, performing multiple commands in a single `RUN` statement reduces
 the number of layers in your image, which improves download and extraction time.
 
-*Place Instructions in the Proper Order*
+[discrete]
+===== Place Instructions in the Proper Order
 
 Docker reads the *_Dockerfile_* and runs the instructions from top to
 bottom. Every instruction that is successfully executed creates a layer which
@@ -155,21 +161,24 @@ Then each time you changed *_myfile_* and reran `docker build`, the `ADD`
 operation would invalidate the `RUN` layer cache, so the `yum` operation would
 need to be rerun as well.
 
-*Mark Important Ports*
+[discrete]
+===== Mark Important Ports
 
 See the "Always `EXPOSE` Important Ports" section of the
 http://www.projectatomic.io/docs/docker-image-author-guidance[Project Atomic
 documentation] for more information.
 
-*Set Environment Variables*
+[discrete]
+===== Set Environment Variables
 
 It is good practice to set environment variables with the `ENV` instruction.
 One example is to set the version of your project. This makes it easy for people
 to find the version without looking at the *_Dockerfile_*. Another example is
 advertising a path on the system that could be used by another process, such as
 `*JAVA_HOME*`.
 
-*Avoid Default Passwords*
+[discrete]
+===== Avoid Default Passwords
 
 It is best to avoid setting default passwords. Many people will extend the image
 and forget to remove or change the default password. This can lead to security
@@ -183,7 +192,8 @@ message is displayed when the container is started. The message should inform
 the user of the value of the default password and explain how to change it, such
 as what environment variable to set.
 
-*Avoid SSHD*
+[discrete]
+===== Avoid SSHD
 
 It is best to avoid running *SSHD* in your image. You can use the `docker exec`
 command to access containers that are running on the local host. Alternatively,
@@ -195,7 +205,8 @@ command to access containers that are running on the {product-title} cluster.
 Installing and running *SSHD* in your image opens up additional vectors for
 attack and requirements for security patching.
 
-*Use Volumes for Persistent Data*
+[discrete]
+===== Use Volumes for Persistent Data
 
 Images should use a https://docs.docker.com/reference/builder/#volume[Docker
 volume] for persistent data. This way {product-title} mounts the network storage
@@ -227,7 +238,8 @@ NOTE: Even with persistent 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.
 
-*External Guidelines*
+[discrete]
+===== External Guidelines
 
 See the following references for other guidelines:
 
@@ -239,15 +251,18 @@ See the following references for other guidelines:
 The following are guidelines that apply when creating container images specifically
 for use on {product-title}.
 ifdef::openshift-online[]
-*Privileges and Volume Builds*
+[discrete]
+===== Privileges and Volume Builds
 
 Docker images cannot be built using the `VOLUME` directive in the `DOCKERFILE`.
 Images using a read/write file system need to use persistent volumes or
 `emptyDir` volumes instead of local storage. Instead of specifying a volume in
 the Dockerfile, specify a directory for local storage and mount either a
 persistent volume or `emptyDir` volume to that directory when deploying the pod.
 endif::[]
-*Enable Images for Source-To-Image (S2I)*
+
+[discrete]
+===== Enable Images for Source-To-Image (S2I)
 
 For images that are intended to run application code provided by a third party,
 such as a Ruby image designed to run Ruby code provided by a developer, you can
@@ -263,8 +278,9 @@ defines S2I scripts for building various versions of Python applications.
 For more details about how to write S2I scripts for your image, see the
 xref:s2i.adoc#creating-images-s2i[S2I Requirements] topic.
 
+[discrete]
 [[use-uid]]
-*Support Arbitrary User IDs*
+===== Support Arbitrary User IDs
 
 By default, {product-title} runs containers using an arbitrarily assigned user
 ID. This provides additional security against processes escaping the container
@@ -279,12 +295,10 @@ execute permissions.
 Adding the following to your Dockerfile sets the directory and file permissions
 to allow users in the root group to access them in the built image:
 
-====
 ----
 RUN chgrp -R 0 /some/directory && \
     chmod -R g=u /some/directory
 ----
-====
 
 Because the container user is always a member of the root group, the container
 user can read and write these files. The root group does not have any special
@@ -355,8 +369,9 @@ as any user].
 ====
 endif::[]
 
+[discrete]
 [[use-services]]
-*Use Services for Inter-image Communication*
+===== Use Services for Inter-image Communication
 
 For cases where your image needs to communicate with a service provided by
 another image, such as a web front end image that needs to access a database
@@ -370,7 +385,8 @@ balancing for requests.
 For more information see https://kubernetes.io/docs/concepts/services-networking/service/[this documentation].  (NOTE to docs team:  this link should really go to something in the openshift docs once we have it)
 ////
 
-*Provide Common Libraries*
+[discrete]
+===== Provide Common Libraries
 
 For images that are intended to run application code provided by a third party,
 ensure that your image contains commonly used libraries for your platform. In
@@ -381,8 +397,9 @@ dependencies to be downloaded during application assembly time, speeding up
 application image builds. It also simplifies the work required by application
 developers to ensure all of their dependencies are met.
 
+[discrete]
 [[use-env-vars]]
-*Use Environment Variables for Configuration*
+===== Use Environment Variables for Configuration
 
 Users of your image should be able to configure it without having to create a
 downstream image based on your image. This means that the runtime configuration
@@ -430,7 +447,8 @@ in Docker containers:
 - Docker documentation - https://docs.docker.com/engine/admin/runmetrics/[Runtime Metrics]
 - Blog article - http://fabiokung.com/2014/03/13/memory-inside-linux-containers[Memory inside Linux containers]
 
-*Set Image Metadata*
+[discrete]
+===== Set Image Metadata
 
 Defining image metadata helps {product-title} better consume your container images,
 allowing {product-title} to create a better experience for developers using your
@@ -440,7 +458,8 @@ image, or offer suggestions on other images that may also be needed.
 See the xref:metadata.adoc#creating-images-metadata[Image Metadata] topic for more information on
 supported metadata and how to define them.
 
-*Clustering*
+[discrete]
+===== Clustering
 
 You must fully understand what it means to run multiple instances of your image.
 In the simplest case, the load balancing function of a service handles routing
@@ -453,7 +472,8 @@ Consider how your instances accomplish this communication when running in
 IP addresses change anytime the pod starts, stops, or is moved. Therefore, it is
 important for your clustering scheme to be dynamic.
 
-*Logging*
+[discrete]
+===== Logging
 
 It is best to send all logging to standard out. {product-title} collects
 standard out from containers and sends it to the centralized logging service
@@ -463,7 +483,8 @@ with an appropriate keyword, which makes it possible to filter the messages.
 If your image logs to a file, users must use manual operations to enter the
 running container and retrieve or view the log file.
 
-*Liveness and Readiness Probes*
+[discrete]
+===== Liveness and Readiness Probes
 
 Document example
 xref:../dev_guide/application_health.adoc#container-health-checks-using-probes[liveness
@@ -472,7 +493,8 @@ users to deploy your image with confidence that traffic will not be routed to
 the container until it is prepared to handle it, and that the container will be
 restarted if the process gets into an unhealthy state.
 
-*Templates*
+[discrete]
+===== Templates
 
 Consider providing an example xref:../dev_guide/templates.adoc#dev-guide-templates[template] with
 your image. A template will give users an easy way to quickly get your image

install_config/install/prerequisites.adoc

@@ -248,32 +248,35 @@ Ansible installation.
 [[security-warning]]
 === Security Warning
 
-{product-title} runs
-xref:../../architecture/core_concepts/containers_and_images.adoc#containers[containers]
-on your hosts, and in some cases, such as build operations and the registry
-service, it does so using privileged containers. Furthermore, those containers
-access your host's Docker daemon and perform `docker build` and `docker push`
-operations. As such, you should be aware of the inherent security risks
-associated with performing `docker run` operations on arbitrary images as they
-effectively have root access. This is particularly relevant for Docker
-xref:../../architecture/core_concepts/builds_and_image_streams.adoc#builds[builds].
-
-You can limit the exposure to harmful containers by assigning specific builds to
+// tag::container-image-security-warning[]
+{product-title} runs containers on hosts in the cluster, and in some cases, such
+as build operations and the registry service, it does so using privileged
+containers. Furthermore, those containers access the hosts' Docker daemon and
+perform `docker build` and `docker push` operations. As such, cluster
+administrators should be aware of the inherent security risks associated with
+performing `docker run` operations on arbitrary images as they effectively have
+root access. This is particularly relevant for `docker build` operations.
+
+Exposure to harmful containers cam be limited by assigning specific builds to
 nodes so that any exposure is limited to those nodes. To do this, see the
-xref:../../dev_guide/builds/advanced_build_operations.adoc#dev-guide-assigning-builds-to-nodes[Assigning
-builds to specific nodes] section of the developer guide and
-xref:../../install_config/build_defaults_overrides.adoc#overview[Configuring
-global build defaults and overrides] section of the installation and
-configuration guide. You can also use
+xref:../../dev_guide/builds/advanced_build_operations.adoc#dev-guide-assigning-builds-to-nodes[Assigning Builds to Specific Nodes] section of the Developer Guide. For cluster
+administrators, see the
+xref:../../install_config/build_defaults_overrides.adoc#overview[Configuring Global Build Defaults and Overrides] section of the Installation and
+Configuration Guide.
+
+You can also use
 xref:../../architecture/additional_concepts/authorization.adoc#security-context-constraints[security
 context constraints] to control the actions that a pod can perform and what it
-has the ability to access.
+has the ability to access. For instructions on how to enable images to run with
+*USER* in the Dockerfile, see
+xref:../../admin_guide/manage_scc.adoc#how-do-i[Managing Security Context
+Constraints] (requires a user with *cluster-admin* privileges).
 
 For more information, see these articles:
 
 - http://opensource.com/business/14/7/docker-security-selinux
 - https://docs.docker.com/engine/security/security/
-
+// end::container-image-security-warning[]
 
 [[envirornment-requirements]]
 == Environment Requirements

using_images/docker_images/index.adoc

@@ -0,0 +1,49 @@
+[[using-images-other-container-images]]
+= Other Container Images
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+
+== Overview
+
+If you want to use container images not found in the
+link:https://access.redhat.com/containers/[Red Hat Container Catalog], you can
+use other arbitrary container images in your {product-title} instance, for
+example those found on the https://registry.hub.docker.com/[Docker Hub].
+
+For {product-title}-specific guidelines on running containers using an
+arbitrarily assigned user ID, see
+xref:../../creating_images/guidelines.adoc#use-uid[Support Arbitrary User IDs]
+in the Creating Images guide.
+
+ifdef::openshift-enterprise[]
+[IMPORTANT]
+====
+For supportability details, see the Production Support Scope of Coverage as
+defined in the
+link:https://access.redhat.com/support/policy/updates/openshift/policies[{product-title} Support Policy].
+====
+endif::[]
+
+ifdef::openshift-online[]
+[IMPORTANT]
+====
+{product-title} runs containers using an arbitrarily assigned user ID. This
+behavior provides additional security against processes escaping the container
+due to a container engine vulnerability and thereby achieving escalated
+permissions on the host node. Due to this restriction, images that run as root
+will not deploy as expected on {product-title}.
+====
+endif::[]
+
+ifdef::openshift-enterprise,openshift-origin[]
+[[using-images-other-container-images-security-warning]]
+== Security Warning
+
+include::install_config/install/prerequisites.adoc[tag=container-image-security-warning]
+endif::[]