OpenShift Partner Getting Started Guide

The Container Development Kit (CDK) is a pre-built environment for running and developing containers using Red Hat OpenShift. It runs as a virtual machine and supports a number of different virtualization providers and host operating systems.

There are two pieces that must be downloaded, with both being found at http://developers.redhat.com/products/cdk/download/.

Details on the CDK installation process can be found on the Red Hat Customer Portal. Additional information on interacting with the CDK VMs can be found at the Vagrant Documentation.

If a VM is not feasible or desired, OpenShift can be run directly inside of Docker on the host machine. There are two steps required:

Once the oc command finishes, information will be provided on how to access the server. For example:

As expected, running docker ps shows a number of deployed containers, all of which service the running installation:

The simplest way to get an existing image into OpenShift is to retrieve the image from Docker Hub. OpenShift will automatically create a new image stream and map to the image in Docker Hub.

When creating a new application, OpenShift can be passed the location of a git repository to automatically trigger a new image build. The type of build performed will depend on what is found in the repository.

If a Dockerfile is present, OpenShift will perform the following steps:

OpenShift’s Source-to-Image (S2I for short) functionality takes the ability to build images from a repository one step further by removing the need for an explicit Dockerfile.

Not all Docker images can be used as the basis for an S2I build. Builder Images, as they are known, have minimal but specific requirements regarding files that OpenShift will invoke during the build. More information on creating new builder images can be found in the create_builder_image section.

There are two ways to determine the base image that will be used in the build:

Once the git repository (and optionally, an explicit base image) are specified, OpenShift takes the following steps:

As with Building from a Dockerfile in OpenShift, the other components of a service are automatically created, a build is triggered, and a new deployment performed.

Now that an application is deployed, see the Anatomy of a Project section guide for more information on the different resources that were created, or the Basic Usage guide for other ways to interact with the newly deployed application. Information on enhancing container images to utilize OpenShift’s features can be found in the Integrating with OpenShift guide.

The CLI provides two useful commands for listing and inspecting resources in the OpenShift installation.

When a container is created in OpenShift, it is initially assigned an IP address and an internal service name within the scope of its project. The service name allows it to be accessed by other applications running inside of the same project. This becomes a useful default for large projects that have a number of internal services but only a small amount of public endpoints.

An explicit step is required to make a container publicly accessible. The application must be exposed by creating a route. When a route is exposed, the host name can be specified. In most cases, the DNS resolution for the hostname is handled outside of OpenShift. If a hostname is not provided, OpenShift will generate an xip.io address that can be used local to the OpenShift instance.

By default, HAProxy is used to manage the routes, however plugins for other providers are available Routes may optionally be configured with TLS credentials for secure communications.

Routes are created through the expose command. Arguments are supported for customizing the route (the most common being --hostname when using an existing DNS server), but for development purposes, the defaults are usually sufficient:

In the above example, OpenShift generated a corresponding xip.io address that can be used to access the service. A quick test from the host running the OpenShift VM shows the service can be accessed:

More information on routes can be found in the corresponding section of the OpenShift documentation.

Along with routes, a common configuration made to pods is the addition of persistent storage volumes. As this is a lengthy topic, it can be found in the Persistent Storage section of this guide.

While debugging an application, there are many times where it can be useful open a terminal into a running container. Both the web UI and command line interface support this directly; there is no need to look up IP addresses or manually deal with SSH keys.

The rsh command is used to connect to a specific pod by its name. The pod names can be retrieved using the get command under the pods resource type:

Similar to opening a remote shell, the OpenShift interfaces provide built-in support for copying files from a local system into a running container.

Apropos of its name, the rsync command will attempt to use rsync to transmit files if the service is available on the destination container. If it is not, OpenShift will fall back to sending a tarfile with the contents. Keep in mind that the normal restrictions when using tar over rsync will be present; the destination directory must exist and the entire contents will be transmitted rather than only sending changed files.

The rsync command works similar to the tranditional rsync command, accepting the source and destination directories. Instead of specifying a hostname or IP address, the pod name is used in the destination:

The first thing to keep in mind is that non-cluster admins do not have permissions to view the configured persisted volumes. This is considered an administrative task; users only needs to be concerned with their requested and assigned claims:

As a reference, the same command, when run as the cluster admin, displays details on the the volumes available:

For context, the following example will be run against an existing project with a previously deployed application. The actual behavior of the application is irrelevant; this example will look directly at the filesystem across multiple pods:

The last line above is important to note. Volumes are not allocated directly against a pod (or pods) but rather the deployment configuration responsible for their creation.

Before the volume is created, a quick sanity check run directly on the pod shows that the mount point does not already exist:

The volume command can be used to both request a volume and specify its attachment point into the running containers:

The output shows that a new claim has been created (pvc-axv7b) and the deployment configuration python-web has been edited.

There are a few things to verify at this point. Details about a claim can be found under the pvc resource type:

Notice that, despite the claim only requesting 512M, the provided capacity is 10G. The output of the get pv command above shows that the installation is only configured with 10Gi volumes, which makes it the "best fit" for the claim.

The volume command can also provide details on the attached volume, including which deployment configurations have volumes and where they are mounted:

Repeating the earlier test on the pod, there is now a /demo mount point available:

To reinforce the concept that the volume is attached to the deployment configuration, and thus all pods spawned by it, the application can be scaled and used to show the mount points refer to the same volume:

The newly created pod, ka3y2, will have the same configuration as the previous pod since they were created from the same deployment configuration. In particular, this includes the mounted volume:

Proof that they refer to the same volume can be seen by adding a file to the volume on one of the pods and verifying its existence on the other:

In addition to demonstrating the volume is shared across pods, it is also important to emphasize the "persistent" aspect of it. The volume command is also used to detach a volume from a configuration (and thus all of its pods):

Note that the --name demo-vol argument refers to the name specified during creation above.

Attempting to reconnect to the pod to verify the volume was detached shows a potentially surprising result:

Keep in mind that changing a pod’s volumes is no different than any other change to the configuration. The pods are not updated, but rather the old pods are scaled down while new pods, with the updated configuration, are deployed. The deployment configuration event log shows that a new deployment was created for the change (the format of the output below is heavily modified for readability, but the data was returned from the call):

The four events listed correspond to the examples run in this section:

Getting back to verifying the volume was removed, one of the new pods can be accessed to check for the presence of the mount point:

Detaching a volume from a deployment configuration does not release the volume or reclaim its space. Listing the volumes as above (again as a cluster admin) shows the volume is still in use:

Additionally, as the non-cluster admin user, the claim is still present as a resource:

The volume can be added back into the deployment configuration (or a different one if so desired) using a variation of the volume command initially used:

The difference in this call is that instead of specifying details about the claim being requested (such as its capacity), a specific claim is referenced (the name being found using the get pvc command above). For demo purposes, it has been mounted to a slightly different path and using a different volume name.

As with the previous configuration changes, new pods have been deployed. Connecting to one of these pods shows the contents of the volume were untouched:

The example above demonstrates that removing a volume does not release the volume nor delete its contents. That requires another step. Remember that claims are resources, similar to routes or deployment configurations, and can be deleted in the same fashion (using the updated name from the reattach example):

Listing the claims for the user shows none allocated:

The cluster administrator shows that the previously bound volume is now free:

The OpenShift documentation contains a section on image creation guidelines, so rather than repeat that information here, it’s recommended to be familiar with the practices in that document. Points of particular interest will be included in the rest of this guide.

There are some recommended practices for your images to ensure full compatibility with Red Hat Products.

It is impractical to rebuild an image for each possible configuration, especially if the image is owned by someone else. The recommended mechanism for configuring a service running in a container is through environment variables.

Environment variables are set in the deployment configuration. They can be set when the configuration is first created or can be added/modified/removed after an application has been deployed. It is important to realize that changes to the environment variables constitute a deployment configuration change. The existing pods are not modified; rather, new pods are deployed with the changed configuration and will automatically replace the existing ones (this is easily seen on the UI overview page with the graphical depictions of scaling up and down).

This paradigm is used both for images created for deployment as well as those intended to be used as builder images with source to image. For example, the Python builder image will, by default, attempt to run a file named app.py. If an application cannot be modified to use this naming scheme, the environment variable APP_FILE can be specified to indicate a new script to run when the container is launched.

One of the more common obstacles encountered with creating new images revolves around the user running the container process. By default, Docker containers are run as root. This can become a security issue as any process that breaks out of the container will retain the same privileges on the host machine; root in a container would have access to root on the host.

By default, OpenShift will issue a warning when loading an image defined to run as root and, in many cases, the deployment will fail with some form of permission error. These failures are due to the fact that OpenShift creates a random, non-privileged user (with no corresponding UID on the host machine) and runs the container with that user. This is an added security benefit provided by OpenShift and, while not difficult, must be acknowledged when creating images.

Since OpenShift is generating a random UID, the solution isn’t as simple as creating and using a user (by its name) within the container. There are potential security issues where a created user can still give itself root privileges. The use of a random ID, specified by OpenShift, also supports added security for multi-tenancy by forcing persistent storage volume UIDs to be unique for each project.

In short, since OpenShift runs containers as a randomized, non-privileged user, the image must be constructed with those limitations in mind.

The common solution is to make the necessary files and directories writable by the root group.

In this context, labels refer to the Docker concept of labels: metadata on an image. These are specified in the Dockerfile and are included in the built image.

Partner container certification requires that images include the following labels:

The container partner team provides a sample Dockerfile that can be used as a template for images suitable for certification. It can be found on GitHub.

Service accounts may be used to authenticate against the OpenShift API without the need to use a regular user’s credentials. This can be used for integrations that require extra information about the running system in which they are deployed, such as for discovery or monitoring purposes. Service accounts are identified by a username and its roles can be manipulated in the same way.

In order to properly configure permissions for a service account, some understanding of the security role system is required.

Security Context Constraints (SCC for short) define a set of access permissions. Users and service accounts are added to SCCs to permit them the privileges defined by the SCC.

A list of all defined SCCs can be retrieved using the get command and the scc resource type:

Specific details are displayed using the describe command. Below is the output for the default restricted SCC:

The SCC description includes information on what is permitted to users in the SCC. The Access section indicates which users are granted access to the SCC. Note that service accounts are treated as users in this context and will appear in this list as well.

Users are granted access to an SCC through the admin policy (adm policy) command:

Service accounts exist within the scope of a particular project. Given that, cluster admin privileges are not required. Like other API objects, they are created and deleted through the create command:

In the example above, the service account will be created in the currently active project. A different project may be specified using the -n flag.

All projects are configured with three default service accounts:

Service accounts can be added to SCCs in the same way as users with one notable exception. The username for the service account must be fully qualified as a service account and identifying the project in which it exists. The template for the user name is:

For example, to add the previously created service account (assuming it was under the project name demo):

There are two ways to retrieve an API token for the service account.

For instances where the default network behaviour does not meet the user’s needs, OpenShift supports the same plugin model as Kubernetes does for networking pods.

If an existing image stream is not found, OpenShift will create one. The image stream is used to provide images when creating new containers. Additionally, triggers can be created to automatically react to changes in an image stream contents and roll out updated pods.

The type name imagestreams (or is for short) is used with CLI query commands:

In the output above, the 172.30.53.244 address corresponds to the internal Docker registry created and managed by the OpenShift installation. It runs in a container under the default project, which can be accessed by a user with cluster admin privileges:

More information about the created input stream can be viewed using the describe command:

A replication controller is created when an application is deployed and is used to control the number of running pods. Each application deployment gets its own replication controller.

The resource type replicationcontrollers (or rc for short) is used with the CLI query commands:

The describe command displays extra information, including details on the image used to provision and details on the running and desired pods:

The next level up is the deployment configuration which describes when and how deployments of the application will be run.

The resource type deploymentconfigs (or dc for short) is used with the CLI query commands:

Information on the deployment’s triggers and update strategy, as well as details on deployments done using the configuration, are displayed by the describe command:

The last layer of interest is the created service. The service acts as the entry point into the running application, taking care of distributing requests to the appropriate pod.

The resource type services is used with the CLI query commands:

Details about a service include the internal IP address and ports in use:

A build configuration describes a single build definition and a set of triggers for when a new build should be created.

The fundamental piece of an OpenShift application is a container. A container is a way to isolate and limit process interactions with minimal overhead and footprint. In most cases, a container will be limited to a single process providing a specific service (e.g. web server, database).

A deployment configuration contains the details of a particular application deployment:

An image is a pre-built, binary file that contains all of the necessary components to run a single container; a container is the working instantiation of an image. Additionally, an image defines certain information on how to interact with containers created from the image, such as what ports are exposed by the container.

OpenShift uses the same image format as Docker; existing Docker images can easily be used to build containers through OpenShift. Additionally, OpenShift provides a number of ways to build images, either from a Dockerfile or directly from source hosted in a git repository.

An image stream is a series of Docker images identified by one or more tags. Image streams are capable of aggregating images from a variety of sources into a single view, including

Pods come from the Kubernetes concept of the same name. A pod is a set of one or more containers deployed together to act as if they are on a single host, sharing an internal IP, ports, and local storage.

It is important to realize that OpenShift treats pods as immutable. Any changes, be it the underlying image, pod configuration, or environment variable values, cause new pods to be created and phase out the existing pods. Being immutable also means that any state is not maintained between pods when they are recreated.

An OpenShift project corresponds to a Kubernetes namespace. They are used to organize and group objects in the system, such as services and deployment configurations, as well as provide security policies specific to those resources.

A replication controller is used to ensure a specified number of pods for an application are running at a given time. The replication controller automatically reacts to changes to deployed pods, both the removal of existing pods (deletion, crashing, etc.) or the addition of extra pods that are not desired. The pods are automatically added or removed from the service to ensure its uptime.

A route is the method to access a service through a hostname. By default, services are only accessible by other pods within the project. A route is created, or exposed, and configured to make the service publicly accessible through a hostname and optional secure communications.

A service functions as a load balancer and proxy to underlying pods. Services are assigned IP addresses and ports and will delegate requests to an appropriate pod that can field it.

Source-to-image is a feature that allows OpenShift to build a Docker image from a source code repository. An application is created within a project that includes a URL to the repository and an optional builder image to base the build on. Web hooks may also be configured to trigger OpenShift to build a new image when the source repository is modified.

The OpenShift Blog hosts posts on a variety of topics. In particular, the ecosystem tag highlights posts written by ISV teams to showcase their integrations.

OpenShift Commons provides a community for partners, users, customers, and contributors to build connections and share best practices, facilitating collaboration and awareness of project involvement with OpenShift. Additionally, regular briefings are hosted and allow for deeper dives into various topics.

Red Hat OpenShift Primed is a technical readiness designation that acknowledges the first steps of an ISV’s technology working with OpenShift by providing the ISV a designated logo and awareness through OpenShift online properties such as Hub and OpenShift Commons. To earn this designation, ISVs must demonstrate an initial commitment to OpenShift.

To sign up for the program, visit https://www.openshift.com/primed.

A natural progression from the Primed program is Red Hat Connect for Technical Partners.

The program is designed to assist companies who are actively seeking to develop, test, certify and support their products and solutions with the Red Hat portfolio. Participants in the program will gain access to a strong ecosystem of companies that are building software, hardware and cloud-based solutions for enterprise customers across the world.

Partners developing solutions for OpenShift should apply for access to the containers zone. All members of the program are required certify their images to gain access to the ecosystem.

Red Hat Container Certification is available for software vendors that offer commercial applications packaged and distributed as containers. The certification process is intended to help ensure that applications are built and packaged according to Red Hat’s enterprise standards.

In addition to the practices outlined under recommended practices, software vendors should ensure that their containers meet the following requirements.

The policy describing these standards can be found here (Red Hat Connect login required).

Red Hat Partner Engineering mantains an example Dockerfile here which hits all the basic requirements for certification.