How to Deploy an Application to an OpenShift Cluster

OpenShift Container platform is designed for building and deploying containerized applications. It supports two main use cases.

• An existing containerized application, build outside of openshift and deployed on OpenShift platform.
• A complete application life cycle, from initial development to production is managed using OpenShift tools.

To create resources required for build and deployment of an application in OpenShift, we use oc new app command.

different resources are created according to the desired use cases.

• If we have an existing containerized application that we want to deploy to OpenShift, use the oc new-app command to create a deployment configuration to manage the deployment process that runs the existing container image in the OpenShift cluster. In the below example, I am referring to a container image using the –docker-image option:

[user1@onionlinux ~]$ oc new-app --docker-image=registry.access.redhat.com/rhel7-mysql57

• If we want OpenShift to manage the entire application life cycle, use the oc new-app command to create a build configuration to manage the build process that creates the application container image. And it also creates a deployment configuration to manage the deployment process that runs the generated container image in the OpenShift cluster. In the below example we are delegating to the OpenShift cluster the entire life cycle: cloning a Git repository, building a container image, and deploying it to an OpenShift cluster.

[user1@onionlinux ~]$ oc new-app \
> https://github.com/oninlinux/openshift/tree/master/apps/nodejs

The oc new-app command also creates some auxiliary resources, such as services and image streams.

oc new-app Command Options

The oc new-app command takes, in its simplest form, a single URL argument that points to either a container image or a Git repository. It accesses the URL to determine how to interpret the argument and perform either a build or a deployment.

The oc new-app command may not be able to make the decision we want. For example:

• If a Git repository contains source code that targets mysql, but the OpenShift cluster supports deploying either mysql version 5.6 or 8.0, the build process fails because it is not clear which version to use.
• If a Git repository contains both a Dockerfile and an index.php file, OpenShift cannot identify which approach to take unless explicitly mentioned.

The oc new-app command provides a number of options to further specify exactly how to build the application:

Managing the complete Application Life Cycle with OpenShift

OpenShift manages an application life cycle using the Source-to-Image (S2I) process. S2I takes application source code from a Git repository, combines it with a base container image, builds the source, and creates a container image with the application ready to run.

The oc new-app command takes a Git repository URL as the input argument and inspects the application source code to determine which builder image to use to create the application container image:

[user1@onionlinux ~]$ oc new-app http://gitserver.onionlinux.com/mygitrepo

The oc new-app command can optionally take the builder image stream name as an argument, either as part of the Git URL, prefixed by a tilde (~), or using the –image-stream argument (short form: -i).

The following two commands illustrate using a mysql S2I builder image:

[user1@onionlinux ~]$ oc new-app mysql~http://gitserver.onionlinux.com/mygitrepo

[user1@onionlinux ~]$ oc new-app -i mysql http://gitserver.onionlinux.com/mygitrepo

Optionally, follow the image stream name with a specific tag, which is usually the version number of the programming language runtime. For example:

[user1@onionlinux ~]$ oc new-app mysql:8.0~http://gitserver.onionlinux.com/mygitrepo

[user1@onionlinux ~]$ oc new-app -i mysql:8.0 \
> http://gitserver.onionlinux.com/mygitrepo

Specifying the Image Stream Name

Some developers prefer the -i option to the tilde notation because the tilde character is not very readable, depending on the screen font. The following three commands yield the same results:

[user1@onionlinux ~]$ oc new-app myapp~http://gitserver.onionlinux.com/mygitrepo

[user1@onionlinux ~]$ oc new-app -i myapp http://gitserver.onionlinux.com/mygitrepo

[user1@onionlinux ~]$ oc new-app -i myapp --strategy source --code http://gitserver.onionlinux.com/mygitrepo

While the oc new-app command aims to be a convenient way to deliver applications, developers need to be aware that the command will try to “guess” the source language of the given Git repository.

The tilde (~) and –image-stream (-i) options do not work in the same way, the -i option requires the git client to be installed locally since the language detection needs to clone the repository so it can inspect the project and the tilde (~) notation does not.

Deploying Existing Dockerfiles with OpenShift

In many cases, you have existing container images built using Dockerfiles. If the Dockerfiles are accessible from a Git repository, the oc new-app command can create a build configuration that performs the Dockerfile build inside the OpenShift cluster and then pulls the resulting container image to the internal registry:

[user1@onionlinux ~]$ oc new-app http://gitserver.onionlinux.com/mydockerfileproject

OpenShift accesses the source URL to determine if it contains a Dockerfile. If the same project contains source files for programming languages, OpenShift might create a builder configuration for an S2I build instead of a Dockerfile build. To avoid ambiguity, use the –strategy option:

[user1@onionlinux ~]$ oc new-app --strategy docker \
> http://gitserver.onionlinux.com/mydockerfileproject

The following example illustrates using the –strategy option for an S2I build:

[user1@onionlinux ~]$ oc new-app --strategy source \
> http://gitserver.onionlinux.com/user/mygitrepo

Other options, such as –image-stream and –code, can be used in the same command with –strategy.

The oc new-app command also provides some options to create applications from a template, or applications built by a Jenkins pipeline.

Resources Created by the oc new-app Command

The oc new-app command adds the following resources to the current project to support building and deploying an application:

• A build configuration to build the application container image from either source code or a Dockerfile.
• A deployment configuration using the image stream as input to create application pods.
• An image stream pointing to either the generated image in the internal registry or to an existing image in an external registry.
• A service for all ports that the application container image exposes. If the application container image does not declare any exposed ports, then the oc new-app command does not create a service.

These resources start a series of processes which in turn create more resources in the project, such as application pods to run containerized applications.

The following command creates an application from source code in the PHP programming language:

[user1@onionlinux ~]$ oc new-app --name hello -i php --code \
> http://gitserver.onionlinux.com/mygitrepo

The following command creates an application based on the mysql image with the label set to db=mysql:

[user1@onionlinux ~]$ oc new-app mysql MYSQL_USER=user1 MYSQL_PASSWORD=password MYSQL_DATABASE=testdb -l db=mysql

After the build and deployment processes complete, use the oc get all command to display all resources the project. The output shows a few more resources beyond those created by the oc new-app command:

NAME       TYPE      FROM      LATEST
bc/hello   Source    Git       3 

NAME             TYPE      FROM          STATUS       STARTED             DURATION
builds/hello-1   Source    Git@3a0af02   Complete     About an hour ago   1m36s 

NAME       DOCKER REPO                                   TAGS      UPDATED
is/hello   docker-registry.default.svc:5000/onion/myapp 

NAME       REVISION   DESIRED   CURRENT   TRIGGERED BY
dc/hello   1          1         1         config,image(hello:latest) 

NAME        DESIRED   CURRENT   READY     AGE
rc/hello-1  1         1         1         3m  

NAME        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
svc/hello   172.30.2.186   <none>        8080/TCP   2m31s 

NAME               READY     STATUS        RESTARTS   AGE
po/hello-1-build   0/1       Completed     0          2m32s 
po/hello-1-tmf1    1/1       Running       0          1m45s 

	The build configuration created by the oc new-app command.
	The first build is triggered by the oc new-app command.
	The image stream created by the oc new-app command. It points to the container image created by the S2I process.
	The deployment configuration created by the oc new-app command.
	The replication controller configuration created by the first deployment. Subsequent deployments might also create deployer pods.
	The service created by the oc new-app command as a result of the PHP S2I builder image exposing port 8080/TCP.
	Build pods from the most recent builds are retained by OpenShift because you might want to inspect these logs. Any deployer pods are deleted after successful termination.
	The application pod created by the first deployment.

An application may expect a number of resources that are not created by the oc new-app command, such as routes, secrets, and persistent volume claims. These resources can be created using other oc commands before or after using the oc new-app command.

All resources created by the oc new-app command includes the app label. The value of the app label matches the short name of the application Git repository or existing container image. To specify a different value for the app label, use the –name option, for example:

[user1@onionlinux ~]$ oc new-app --name test http://gitserver.onionlinux.com/mygitrepo

We can delete resources created by the oc new-app command using a single oc delete command and the app label, without resorting to deleting the entire project, and without affecting other resources that may exist in the project. The following command deletes all resources created by the previous oc new-app command:

[user1@onionlinux ~]$ oc delete all -l app=test

we can use the argument of the –name option to specify the base name for the resources created by the oc new-app command, such as build configurations, deployment configurations and services.

The oc new-app command can be executed multiple times inside the same OpenShift project to create multicontainer applications one piece at a time. For example:

• Run the oc new-app command with the URL to a mysql database container image to create a database pod and a service.
• Run the oc new-app command with the URL to the Git repository for a AngularJs application that requires access to the database, using the service created by the first invocation.

Later we can export all resources created by both commands to a template file.

To inspect resource definitions without creating the resources in the current project, use the -o option:

[user1@onionlinux ~]$ oc new-app -o json registry.onionlinux.com/mycontainerimage

The resource definitions are sent to the standard output and can be redirected to a file. The resulting file can then be customized or inserted into a template definition.

OpenShift provides a number of predefined templates for common scenarios such as a database plus an application.

To get a complete list of options supported by the oc new-app command, and to see a list of examples, run the oc new-app -h command.

Referring to Container Images Using Image Streams and Tags

The OpenShift community recommends using image stream resources to refer to container images instead of using direct references to container images. An image stream resource points to a container image either in the internal registry or in an external registry, and stores metadata such as available tags and image content checksums.

Having container image metadata in an image stream allows OpenShift to perform operations, such as image caching, based on this data instead of going to a registry server every time. It also allows using either notification or pooling strategies to react to image content updates.

Build configurations and deployment configurations use image stream events to perform operations such as:

[user1@onionlinux ~]$ oc import-image myis --confirm --from registry.acme.example.com:5000/acme/awesome --insecure