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:
[[email protected] ~]$ 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.
[[email protected] ~]$ 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:
[[email protected] ~]$ 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:
[[email protected] ~]$ oc new-app mysql~http://gitserver.onionlinux.com/mygitrepo
[[email protected] ~]$ 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:
[[email protected] ~]$ oc new-app mysql:8.0~http://gitserver.onionlinux.com/mygitrepo
[[email protected] ~]$ 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:
[[email protected] ~]$ oc new-app myapp~http://gitserver.onionlinux.com/mygitrepo
[[email protected] ~]$ oc new-app -i myapp http://gitserver.onionlinux.com/mygitrepo
[[email protected] ~]$ 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:
[[email protected] ~]$ 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:
[[email protected] ~]$ oc new-app --strategy docker \ > http://gitserver.onionlinux.com/mydockerfileproject
The following example illustrates using the –strategy option for an S2I build:
[[email protected] ~]$ 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:
[[email protected] ~]$ 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:
[[email protected] ~]$ 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 [email protected] 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
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:
[[email protected] ~]$ 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:
[[email protected] ~]$ 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
[[email protected] ~]$ 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:
- Triggering a new S2I build because the builder image was updated.
- Triggering a new deployment of pods for an application because the application container image was updated in an external registry.
The easiest way to create an image stream is by using the oc import-image command with the
--confirm option. The following example creates an image stream named
myis for the
acme/awesome container image that comes from the insecure registry at
[[email protected] ~]$ oc import-image myis --confirm --from registry.acme.example.com:5000/acme/awesome --insecure
We can create your own image streams in the current project using both the oc new-app command as well as using OpenShift templates.
For more information about OpenShift projects, you can go here.
You can read more basic about Kubernetes and OpenShift Architecture in my another post Architecture of Kubernetes & OpenShift.