Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

Deploy Your First Application

Create a project, deploy an app from a container image or Git with oc new-app, expose it with a route, and read the objects that OpenShift created for you.

In this lesson you deploy a small web application, give it a public URL and look at what OpenShift created on your behalf. You need a project on any cluster (the Developer Sandbox works) and the oc tool from the previous lesson.

Step 1: create a project

A project is your own workspace on the cluster: a Kubernetes namespace plus extra metadata and access rules. Create one and switch to it:

Terminal
oc new-project hello-demo --display-name="Hello demo" --description="My first app"

On a shared sandbox you may already have projects and not be allowed to create more; use one you were given with oc project <name>. Projects are explained fully in Projects and namespaces.

Step 2: deploy from a container image

The fastest path is an existing image. oc new-app accepts an image reference and creates the pieces needed to run it:

Terminal
oc new-app --name=hello --image=quay.io/example/hello-web:1.0

Replace the image with one you can pull. Pick an image that runs as a non-root user and listens on a port above 1024, because OpenShift runs containers with a random, unprivileged user ID by default (more in Security and Operators). Many images built for plain Docker assume root and fail here; that is the single most common first surprise.

oc new-app prints a summary of what it created. In current versions the result is:

  • a Deployment called hello that keeps the desired number of Pods running,
  • a Service that gives the Pods a stable internal address,
  • an ImageStream that tracks the image (a concept unique to OpenShift, see ImageStreams and tags).

Check progress:

Terminal
oc status
oc get pods
oc rollout status deployment/hello

Step 3: deploy from source code

If you give oc new-app a Git repository it detects the language and builds an image for you using Source-to-Image (S2I):

Terminal
oc new-app https://github.com/your-name/your-node-app.git --name=web

OpenShift inspects the repository (for example a package.json means Node.js), starts a build, pushes the result into the internal registry and then deploys it. You can watch it:

Terminal
oc logs -f buildconfig/web

You can also choose the builder explicitly with the <builder>~<repo> form:

Terminal
oc new-app nodejs~https://github.com/your-name/your-node-app.git --name=web

Builds and S2I gets its own lesson.

Step 4: expose it

A Service is only reachable inside the cluster. To reach the app from a browser you create a Route:

Terminal
oc expose service/hello
oc get route hello

The second command prints a host name made from the route name, the project name and the cluster's apps domain, something like hello-hello-demo.apps.<cluster-domain>. Open it with http:// first. For HTTPS you will edit the route to add TLS termination, which belongs to the networking chapter.

Terminal
oc create route edge hello-secure --service=hello

What did OpenShift create?

Terminal
oc get all
oc get imagestream
oc get route

The picture below shows the typical chain.

flowchart LR
  U["Browser"] --> R["Route<br/>public host name"]
  R --> S["Service<br/>stable cluster IP"]
  S --> P1["Pod"]
  S --> P2["Pod"]
  D["Deployment"] -. manages .-> P1
  D -. manages .-> P2
  I["ImageStream"] -. feeds image to .-> D

Figure: Route to Service to Pods, with a Deployment keeping Pods alive.

Older tutorials show a DeploymentConfig here. It is deprecated in modern OpenShift 4 releases; use Deployments for new work. The deployments lesson explains the difference.

Scale, look and clean up

Terminal
oc scale deployment/hello --replicas=3
oc get pods -l deployment=hello
oc logs deployment/hello
oc delete all -l app=hello

oc new-app labels everything it creates with app=<name>, so one label selector can find or remove the whole application. oc delete all removes the common workload kinds that match the label. Secrets, ConfigMaps and PersistentVolumeClaims are not deleted by it, so check those separately.

To remove the entire project at once:

Terminal
oc delete project hello-demo

Stand-in: what would new-app create?

The real command inspects images and repositories. The stand-in below only mimics its naming and labelling rules so you can predict what you will see. It is a simplified model, not the real algorithm.

Python Stand-in: objects created by new-app

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: how a Route finds a host name

Python Stand-in: building a default route host name

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The real router also honors a custom spec.host and wildcard rules; the stand-in shows only the default naming pattern.

Common first problems

  • ImagePullBackOff. Wrong image name, or a private registry without a pull secret.
  • CrashLoopBackOff right after start. The image expects to run as root or to write to a read-only path. Check oc logs.
  • Route returns "Application is not available". The Service selector does not match any ready Pod, or the Pod is not Ready. Check oc get endpoints hello.
  • Quota exceeded. On a sandbox, oc describe quota shows what you may use.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does oc new-project create?

    A project is a Kubernetes namespace plus OpenShift metadata and role bindings; it is the unit you work in.
  2. 2. Which object makes an application reachable from the internet through the router?

    A Route maps a public host name to a Service. The Service then sends traffic to Pods.
  3. 3. Why do many Docker images fail on OpenShift at first?

    The restricted security defaults run containers as an arbitrary unprivileged user, so images that need root or privileged ports break.
  4. 4. How can you delete everything oc new-app created for an app named hello?

    new-app labels objects with app=<name>, so a label selector finds them. Secrets and PVCs need separate cleanup.

Summary

  • Create or choose a project, then run oc new-app with an image or a Git URL.
  • It creates a Deployment, a Service and an ImageStream (plus a BuildConfig for source builds).
  • Use oc expose service/<name> to create a Route and get a public URL.
  • Containers run as a random non-root user, so images must support that.
  • Objects carry the label app=<name>, which helps with listing and cleanup.

Next: Cluster Architecture