Tutorial: deploy a small web app on OpenShift and expose it with a Route

In this tutorial you deploy a small static website to an OpenShift or OKD cluster using only the oc client. The cluster builds the image for you from a public Git repository, runs it, and publishes it on an HTTPS address. You need an account on a cluster and permission to create a project.

The example uses the Apache httpd builder image from Red Hat’s public registry and the sample repository sclorg/httpd-ex, which contains an index.html. Both work with OpenShift’s default security settings: the server listens on port 8080 and runs as a random, non-root user.

1. Log in and create a project

oc login https://api.cluster.example.com:6443 -u developer
oc new-project hello-web

2. Build and deploy from Git

oc new-app with the builder~repository syntax creates a BuildConfig, image streams, a Deployment and a Service in one go. The build clones the repository, copies the files into the builder image and pushes the result to the internal registry.

oc new-app registry.access.redhat.com/ubi9/httpd-24~https://github.com/sclorg/httpd-ex.git --name=hello

3. Watch the build and the rollout

oc logs -f bc/hello
oc get pods -w

Press Ctrl+C to stop watching. You should see a build pod that ends in Completed and an application pod in Running with 1/1 ready. If the build fails, the log usually says why; if the pod restarts, check oc logs deploy/hello and oc get events --sort-by=.lastTimestamp.

4. Look at what was created

oc status
oc get deployment,svc,is,bc

The service is internal only. It has a stable cluster IP and DNS name inside the cluster but cannot be reached from your browser yet.

5. Publish it with an HTTPS Route

An edge route terminates TLS at the cluster’s router and forwards plain HTTP to your pod. Without your own certificate, the router uses its default certificate for the cluster’s application domain. Setting the insecure policy to Redirect sends visitors who type http:// to the HTTPS address.

oc create route edge hello --service=hello --port=8080 --insecure-policy=Redirect
oc get route hello

The HOST/PORT column shows the generated host name under the cluster’s application domain. Open https:// plus that host name in a browser, or test from the terminal:

HOST=$(oc get route hello -o jsonpath='{.spec.host}')
curl -sI "https://$HOST"

If the page does not load, check that the route points at the right service and port (oc describe route hello) and that the pod is ready. An HTTP 503 page from the router usually means no ready pod is behind the service.

6. Scale and add a health check

oc scale deployment/hello --replicas=2
oc set probe deployment/hello --readiness --get-url=http://:8080/
oc rollout status deployment/hello

With a readiness probe, the router only sends traffic to pods that answer on port 8080, so rollouts do not serve errors while a new pod is starting.

7. Change the app and rebuild

Fork the sample repository, edit index.html, point the build at your fork and start a new build. When the build pushes a new image to the image stream, the deployment rolls out the new version.

oc patch bc/hello --type=merge -p '{"spec":{"source":{"git":{"uri":"https://github.com/YOUR-USER/httpd-ex.git"}}}}'
oc start-build hello --follow
oc rollout status deployment/hello

8. Clean up

Warning: this deletes the whole project and everything in it. Run oc project first to confirm you are about to delete hello-web on the cluster you expect.

oc project
oc delete project hello-web

What you learned

• oc new-app can build from Git with S2I and deploy in a single command.
• Services are internal; a Route publishes a service on a host name with TLS handled by the router.
• Builds, image streams and deployments are linked, so a new build leads to a new rollout.

Official documentation

• Creating applications by using the CLI
• Securing routes
• Performing basic builds