Container Service: Developing an Application - Application Permissions in OpenShift


The Container Service uses Red Hat's OpenShift to host containerized applications. OpenShift is a multi-tenanted system, meaning that it is designed to be used by many users simulataneously. As such, certain permissions that are available when you run a containerized application locally are not available when running in OpenShift. One of those is the ability to run as the root user. Applications in OpenShift cannot run as the root user. Instead, applications run as an anonymous user. This user is part of the root group, and has a fixed UID that is unique to your project.


What UID will Applications in my Project Run as?

Applications are run by the first uid in the range defined by this project-level annotation: To view this range for your project, use the following command:

oc get project {my-openshift-project} -o custom-columns="uid:.metadata.annotations.openshift\.io\/sa\.scc\.uid-range"

You will see output that looks similar to this:

Applications in this project will be run by the following UID: 1099990000


Applications with Named Users

Some applications specify named users in their Dockerfile. For example, the nginx container is run by the nginx user  If your application specifies a named user, it will have difficulty running in OpenShift, as pods in OpenShift are run by an anonymous user with a unique UID. See the heading above for more information. While the anonymous user is part of the root group, it may not have access to certain directories and files that are owned by the container's named user.

If you find yourself in this situation, there are several methods to allow your application to run successfully.  Any one of the options detailed below should allow your application to run successfully within OpenShift. Docker containers can be run locally with a specified UID--emulating what they will experience when running in the OpenShift environment--expedite testing. The following is an example of a docker run command with an emulated UID of 1099990000:

docker run -it -u 1099990000 {my-image-name}


Method 1: Modify your Dockerfile to change the underlying UID for the named user.

  1. Obtain the UID for your project using the command in the heading "What UID will Applications in my Project Run as?" above.
  2. Include a line in your Dockerfile to modify the named user to use the project's UID. For example, the following line will modify the nginx named user to use the UID of 1099990000 referenced above:

RUN useradd -g root -m -s /bin/bash -l -o -u 1099990000 nginx


Method 2: Modify the User's UID at Runtime

Similar to the process detailed above, this process modifies the named user to use the UID provided by your OpenShift project. It first makes /etc/passwd writable by members of the root group. Second, this method add start-up code to the container to change the named user's UID. A Red Hat blog post that details this method can be found here:

  1. To make /etc/passwd writable, add the following line to your Dockerfile: RUN chmod g+w /etc/passwd
  2. Once /etc/passwd is writable, a start-up script can modify the named user to use the UID of the project. Note, this must be done using a start-up script. OpenShift assigns the UID to your application at run-time, not during the build process. The following is an example of a start-up script that modifies the UID of the www-data user:
if [ "$(id -u)" -ge 1000 ] ; then
    sed -e "/^www-data:/c www-data:x:$(id -u):$(id -g):www-data:/var/www:/usr/sbin/nologin" /etc/passwd > /tmp/passwd
    cat /tmp/passwd > /etc/passwd
    rm /tmp/passwd


Method 3: Adjust File and Directory Permissions

Make all directories and files required for your application to function so that the root group has the necessary permissions. This process will be different for each application and is likely the most tedious of the three methods.

  1. Scan the application log files to determine where permissions need to be adjusted. These logs will typically show errors where the application does not have the permissions to read or write to certain directories and files. Frequently, these errors will be the cause of the container failing to start.
  2. For example, the Apache httpd container write logs to a directory that is owned by the www-data user. To make this directory writable to the root group, including the following commands in your Dockerfile:
    • RUN chown -R root:root /usr/local/apache2/logs
    • RUN chmod g+rw /usr/local/apache2/logs

  3. Attempt to re-run your application. You may need to repeat these steps several times to find all of the files and directories that require permission adjustments.

Last Updated: 
Monday, July 13, 2020