Build and deploy from source with oc new-app and Source-to-Image

oc new-app is OpenShift’s shortcut for getting something running. Give it an image, a Git repository or a template and it generates the objects needed to build and run it. Behind it are two OpenShift-specific resources: the BuildConfig, which describes how to produce an image, and the image stream, which tracks the images produced.

From an existing image

oc new-app registry.access.redhat.com/ubi9/httpd-24 --name=static
oc new-app myregistry.example.com:5000/team/api:1.4 --name=api
oc new-app my-stream:v1

This creates a Deployment and, if the image declares exposed ports, a Service. Current oc releases create a Kubernetes Deployment; DeploymentConfig objects are deprecated since OpenShift 4.14, and --as-deployment-config only exists for old setups.

From source code with S2I

Source-to-Image (S2I) produces a ready-to-run image by injecting your source into a builder image that knows how to assemble it, for example by installing Python requirements or running npm install. You do not need a Dockerfile.

# Name the builder explicitly with builder~repository
oc new-app registry.access.redhat.com/ubi9/python-311~https://github.com/sclorg/django-ex.git#4.2.x --name=web

# Let oc detect the language (needs git installed locally)
oc new-app https://github.com/sclorg/httpd-ex.git

# A subdirectory and a private repository
oc new-app https://github.com/example/monorepo.git --context-dir=services/api --source-secret=git-cred

How the build strategy is chosen

• If the repository root (or --context-dir) has a Dockerfile, oc new-app creates a Docker build, which OpenShift runs with Buildah.
• If it has a Jenkinsfile, it creates a pipeline build. That strategy is deprecated in favor of OpenShift Pipelines (Tekton).
• Otherwise it creates a Source (S2I) build and picks a builder from marker files: package.json for Node.js, requirements.txt or setup.py for Python, pom.xml for Java, composer.json or index.php for PHP, Gemfile for Ruby, main.go for Go.
• With the builder~repository form, detection is skipped. Override the guess with --strategy=docker or --strategy=source.

Language detection looks for matching image streams on the cluster, typically in the openshift namespace. Run oc get imagestreams -n openshift to see what builders your cluster offers; the Cluster Samples Operator that installs them is deprecated and may be set to Removed, so naming the builder image explicitly is more predictable.

Pass settings at creation time

oc new-app registry.access.redhat.com/ubi9/python-311~https://github.com/example/api.git \
  --name=api \
  -e APP_MODE=production \
  --build-env PIP_INDEX_URL=https://pypi.example.com/simple \
  -l app.kubernetes.io/part-of=shop

-e sets runtime environment variables on the deployment, and --build-env sets variables only during the build. Put real secrets in a Secret afterward rather than on the command line.

Follow, restart and debug builds

oc get bc,builds
oc logs -f bc/web                 # follow the latest build
oc start-build web --follow       # start a new build and stream it
oc start-build web --from-dir=.   # build from local files, no git push needed
oc cancel-build bc/web
oc describe build web-3           # status, reason and events

A build runs in a pod, so common failures look familiar: a typo in the Git URL, a missing source secret for a private repository, a dependency download blocked by a proxy (set HTTP_PROXY with --build-env), or a builder image that cannot be pulled.

Image streams and automatic rollouts

An image stream does not store image data. It is a named view of image references, and builds and deployments can point at an image stream tag such as web:latest. When a build pushes a new image to that tag, the deployment created by oc new-app is triggered and rolls out the new image.

oc get is web
oc describe is web
oc tag web:latest web:approved        # promote a build by tagging
oc import-image python-311 --from=registry.access.redhat.com/ubi9/python-311:latest --confirm

Next step: publish it

oc new-app never creates a route. Publish the service with oc expose service/web for plain HTTP, or with oc create route edge for HTTPS.

Official documentation

• Creating applications by using the CLI
• Understanding image builds
• Managing image streams