검색

Chapter 2. Source-to-Image (S2I)

download PDF

2.1. Overview

This topic group includes information on the different S2I (Source-to-Image) supported images available for OpenShift Container Platform users.

2.2. Java

2.2.1. Overview

OpenShift Container Platform provides S2I builder images for building Java applications. These builder images take your application source or binary artifacts, build the source using Maven, if the source was provided, and assemble the artifacts with any required dependencies to create a new, ready-to-run image containing your Java application. This resulting image can be run on OpenShift Container Platform or run directly with Docker.

The builder images are intended for use with Maven-based Java standalone projects that are run via main class.

2.2.2. Versions

The current version of the Java S2I builder images support OpenJDK 1.8 and 11, Jolokia 1.6.2, and Maven 3.6.

2.2.3. Images

The RHEL 7 and RHEL 8 images are available through the Red Hat Registry.

Note

registry.redhat.io requires authentication. For details on how to configure your environment for registry.redhat.io, see Red Hat Container Registry Authentication.

RHEL 7 based images

$ docker pull registry.redhat.io/redhat-openjdk-18/openjdk18-openshift
$ docker pull registry.redhat.io/openjdk/openjdk-11-rhel7

RHEL 8 based images

$ docker pull registry.redhat.io/ubi8/openjdk-8
$ docker pull registry.redhat.io/ubi8/openjdk-11

To use these images on OpenShift Container Platform, you can either access them directly from the Red Hat Registry or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the image stream definition.

2.2.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.2.5. Configuration

By default, the Java S2I builder image uses Maven to build the project with the following goals and options:

mvn -e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga -Dfabric8.skip=true --batch-mode -Djava.net.preferIPv4Stack=true -s /tmp/artifacts/configuration/settings.xml -Dmaven.repo.local=/tmp/artifacts/m2  package

Based on these defaults, the builder image compiles the project and copies all the transitive dependencies into the output directory without running tests. Additionally, if the project has a profile named openshift, it is activated for the build.

You can override these default goals and options by specifying the following environment variables:

Variable nameDescription

MAVEN_S2I_ARTIFACT_DIRS

Relative paths of source directories to scan for build output, which are copied to DEPLOY_DIR. Defaults to target.

JAVA_MAIN_CLASS

A main class to use as the argument for java. When this environment variable is given, all jar files in JAVA_APP_DIR are added to the classpath and JAVA_LIB_DIR.

MAVEN_ARGS

The arguments that are passed to the mvn command. Defining this variable replaces the defaults, which are -e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga package.

MAVEN_ARGS_APPEND

Additional Maven arguments.

This is a selection of the environment variables available for configuring the behavior of the OpenJDK containers. For a comprehensive list, see Section 2.2.9, “Java Environment Variables”.

2.2.6. Building and Deploying Java Applications

Important

The OpenJDK image stream must first be installed. If you ran a standard installation, the image stream will be present.

The same S2I builder image can be used to build a Java application from source or from binary artifacts.

2.2.7. Building and Deploying from Source

The Java S2I builder image can be used to build an application from source by running oc new-app against a source repository:

$ oc new-app registry.redhat.io/redhat-openjdk-18/openjdk18-openshift~https://github.com/jboss-openshift/openshift-quickstarts --context-dir=undertow-servlet

By default, tests are not run. To build an application and run tests as part of the build, override the default MAVEN_ARGS, as shown in the following command:

$ oc new-app registry.redhat.io/redhat-openjdk-18/openjdk18-openshift~<git_repo_URL> --context-dir=<context_dir> --build-env='MAVEN_ARGS=-e -Popenshift -Dcom.redhat.xpaas.repo.redhatga package'

If a Java project consists of multiple Maven modules, it can be useful to explicitly specify the artifact output directory. Specifying the directory where the Maven project outputs the artifacts enables the S2I build to pick them up.

To specify the modules to build and the artifact output directory, use the following command:

$ oc new-app registry.redhat.io/redhat-openjdk-18/openjdk18-openshift~<git_repo_URL> --context-dir=<context_dir> --build-env='MAVEN_S2I_ARTIFACT_DIRS=relative/path/to/artifacts/dir' --build-env='MAVEN_ARGS=install -pl <groupId>:<artifactId> -am'

2.2.8. Building and Deploying from Binary Artifacts

You can use the Java S2I builder image to build an application using binary artifacts that you provide.

  1. Create a new binary build:

    $ oc new-build --name=<application_name> registry.redhat.io/redhat-openjdk-18/openjdk18-openshift --binary=true
  2. Start a build and specify the path to the binary artifacts on your local machine:

    $ oc start-build <application_name> --from-dir=/path/to/artifacts --follow
  3. Create an application:

    $ oc new-app <application_name>

2.2.9. Java Environment Variables

The following tables provide a comprehensive list of Java environment variables used for configuring the behavior of the OpenJDK containers.

Table 2.1. Configuration environment variables
Variable nameDescriptionExample value

AB_JOLOKIA_CONFIG

If set, uses this file, including path, as Jolokia JVM agent properties, as described in the Jolokia reference manual. If not set, the /opt/jolokia/etc/jolokia.properties is created using the settings as defined in the manual. Otherwise, the rest of the settings in this document are ignored.

/opt/jolokia/custom.properties

AB_JOLOKIA_DISCOVERY_ENABLED

Enable Jolokia discovery. Defaults to false.

true

AB_JOLOKIA_HOST

Host address to bind to. Defaults to 0.0.0.0.

127.0.0.1

AB_JOLOKIA_ID

Agent ID to use. Defaults to $HOSTNAME, which is the container ID.

openjdk-app-1-xqlsj

AB_JOLOKIA_OFF

If set, disables activation of Jolokia, for example, echos an empty value. By default, Jolokia is enabled.

true

AB_JOLOKIA_OPTS

Additional options to be appended to the agent configuration. They should be given in the format key=value,key=value,…​.

backlog=20

AB_JOLOKIA_PASSWORD

Password for basic authentication. By default, authentication is switched off.

mypassword

AB_JOLOKIA_PORT

Port to listen to. Defaults to 8778.

5432

AB_JOLOKIA_USER

User for basic authentication. Defaults to jolokia.

myusername

AB_PROMETHEUS_ENABLE

Enable the use of the Prometheus agent.

true

AB_PROMETHEUS_JMX_EXPORTER_PORT

Port to use for the Prometheus JMX Exporter.

9799

CONTAINER_CORE_LIMIT

A calculated core limit as described in CFS Bandwidth Control.

2

CONTAINER_MAX_MEMORY

Memory limit given to the container.

1024

GC_ADAPTIVE_SIZE_POLICY_WEIGHT

The weighting given to the current GC time versus previous GC times.

90

GC_CONTAINER_OPTIONS

Specify the Java GC to use. The value of this variable should contain the necessary JRE command-line interface options to specify the required GC, which overrides the default of -XX:+UseParallelOldGC.

-XX:+UseG1GC

GC_MAX_HEAP_FREE_RATIO

Maximum percentage of heap free after GC to avoid shrinking.

40

GC_MAX_METASPACE_SIZE

The maximum metaspace size.

100

GC_METASPACE_SIZE

The initial metaspace size.

20

GC_MIN_HEAP_FREE_RATIO

Minimum percentage of heap free after GC to avoid expansion.

20

GC_TIME_RATIO

Specifies the ratio of the time spent outside the garbage collection, for example, the time spent for application execution, to the time spent in the garbage collection.

4

HTTPS_PROXY

The location of the https proxy. This takes precedence over http_proxy and HTTP_PROXY, and is used for both Maven builds and Java runtime.

myuser@127.0.0.1:8080

HTTP_PROXY

The location of the http proxy. This is used for both Maven builds and Java runtime.

127.0.0.1:8080

JAVA_APP_DIR

The directory where the application resides. All paths in your application are relative to this directory.

myapplication/`

JAVA_ARGS

Arguments passed to the java application.

-

JAVA_CLASSPATH

The classpath to use. If not given, the startup script checks for a file JAVA_APP_DIR/classpath and uses its content literally as classpath. If this file does not exist, all jars in the app dir are added. (classes:JAVA_APP_DIR/*).

-

JAVA_DEBUG

If set, remote debugging is switched on. Disabled by default.

true

JAVA_DEBUG_PORT

Port used for remote debugging. Defaults to 5005.

8787

JAVA_DIAGNOSTICS

Set this variable to get some diagnostics information to standard output when things are happening. Disabled by default.

true

JAVA_INITIAL_MEM_RATIO

Used when no -Xms option is given in JAVA_OPTS. This is used to calculate a default initial heap memory based on the maximum heap memory. If used in a container without any memory constraints for the container, this option has no effect. If there is a memory constraint, -Xms is set to a ratio of the -Xmx memory as set here. The default is 25 which means 25% of the -Xmx is used as the initial heap size. You can skip this mechanism by setting this value to 0, in which case no -Xms option is added.

25

JAVA_LIB_DIR

Directory holding the Java jar files and an optional classpath file which holds the classpath as either a single line classpath (colon separated) or with jar files listed line-by-line. If not set, JAVA_LIB_DIR is the same as JAVA_APP_DIR.

-

JAVA_MAIN_CLASS

A main class to use as the argument for java. When this environment variable is given, all jar files in JAVA_APP_DIR are added to the classpath and JAVA_LIB_DIR.

com.example.MainClass

JAVA_MAX_INITIAL_MEM

Used when no -Xms option is given in JAVA_OPTS. This is used to calculate the maximum value of the initial heap memory. If used in a container without any memory constraints for the container, this option has no effect. If there is a memory constraint, -Xms is limited to the value set here. The default is 4096 MB, which means the calculated value of -Xms is never greater than 4096 MB. The value of this variable is expressed in MB.

4096

JAVA_MAX_MEM_RATIO

Used when no -Xmx option is given in JAVA_OPTS. This is used to calculate a default maximal heap memory based on a containers restriction. If used in a container without any memory constraints for the container, this option has no effect. If there is a memory constraint, -Xmx is set to a ratio of the container available memory as set here. The default is 50, which means 50% of the available memory is used as an upper boundary. You can skip this mechanism by setting this value to 0, in which case no -Xmx option is added.

-

JAVA_OPTS

JVM options passed to the java command.

-verbose:class

JAVA_OPTS_APPEND

User specified Java options to be appended to generated options in JAVA_OPTS.

-Dsome.property=foo

LOGGING_SCRIPT_DEBUG

Set to true to enable script debugging. Deprecates SCRIPT_DEBUG.

true

MAVEN_ARGS

Arguments to use when calling Maven, replacing the default package hawt-app:build -DskipTests -e. Be sure to run the hawt-app:build goal when not already bound to the package execution phase, otherwise the startup scripts do not work.

-e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga package

MAVEN_ARGS_APPEND

Additional Maven arguments.

-X -am -pl

MAVEN_CLEAR_REPO

If set, the Maven repository is removed after the artifact is built. This is useful for keeping the created application image small, but prevents incremental builds. This variable is overridden by S2I_ENABLE_INCREMENTAL_BUILDS. Defaults to false.

-

MAVEN_LOCAL_REPO

Directory to use as the local Maven repository.

/home/jboss/.m2/repository

MAVEN_MIRRORS

If set, multi-mirror support is enabled, and other MAVEN_MIRROR_* variables are prefixed. For example, DEV_ONE_MAVEN_MIRROR_URL and QE_TWO_MAVEN_MIRROR_URL.

dev-one,qe-two

MAVEN_MIRROR_URL

The base URL of a mirror used for retrieving artifacts.

http://10.0.0.1:8080/repository/internal/

MAVEN_REPOS

If set, multi-repo support is enabled, and other MAVEN_REPO_* variables are prefixed. For example, DEV_ONE_MAVEN_REPO_URL and QE_TWO_MAVEN_REPO_URL.

dev-one,qe-two

MAVEN_S2I_ARTIFACT_DIRS

Relative paths of source directories to scan for build output, which are copied to DEPLOY_DIR. Defaults to target.

target

MAVEN_S2I_GOALS

Space separated list of goals to be run with the maven build. For example, mvn $MAVEN_S2I_GOALS. Defaults to package.

package install

MAVEN_SETTINGS_XML

Location of custom Maven settings.xml file to use.

/home/jboss/.m2/settings.xml

NO_PROXY

A comma separated list of hosts, IP addresses or domains that can be accessed directly. This is used for both Maven builds and Java runtime.

foo.example.com,bar.example.com

S2I_ARTIFACTS_DIR

Location mount for artifacts persisted with save-artifacts script, which are used with incremental builds. This must not be overridden by end users.

${S2I_DESTINATION_DIR}/artifacts}

S2I_DESTINATION_DIR

Root directory for S2I mount, as specified by the io.openshift.s2i.destination label. This must not be overridden by end users.

/tmp

S2I_ENABLE_INCREMENTAL_BUILDS

Do not remove source and intermediate build files so they can be saved for use with future builds. Defaults to true.

true

S2I_IMAGE_SOURCE_MOUNTS

Comma separated list of relative paths in the source directory which should be included in the image. The list can include wildcards, which are expanded using find. By default, the contents of mounted directories are processed similarly to source folders, where the contents of S2I_SOURCE_CONFIGURATION_DIR, S2I_SOURCE_DATA_DIR, and S2I_SOURCE_DEPLOYMENTS_DIR are copied to their respective target directories. Alternatively, if an install.sh file is located in the root of the mount point, it is executed instead. Deprecates CUSTOM_INSTALL_DIRECTORIES.

extras/*

S2I_SOURCE_CONFIGURATION_DIR

Relative path to directory containing application configuration files to be copied over to the product configuration directory, see S2I_TARGET_CONFIGURATION_DIR. Defaults to configuration.

configuration

S2I_SOURCE_DATA_DIR

Relative path to directory containing application data files to be copied over to the product data directory, see S2I_TARGET_DATA_DIR. Defaults to data.

data

S2I_SOURCE_DEPLOYMENTS_DIR

Relative path to directory containing binary files to be copied over to the product deployment directory, see S2I_TARGET_DEPLOYMENTS_DIR. Defaults to deployments.

deployments

S2I_SOURCE_DIR

Location of mount for source code to be built. This must not be overridden by end users.

${S2I_DESTINATION_DIR}/src}

S2I_TARGET_CONFIGURATION_DIR

Absolute path to which files located in S2I_SOURCE_DIR/S2I_SOURCE_CONFIGURATION_DIR are copied.

/opt/eap/standalone/configuration

S2I_TARGET_DATA_DIR

Absolute path to which files located in S2I_SOURCE_DIR/S2I_SOURCE_DATA_DIR are copied.

/opt/eap/standalone/data

S2I_TARGET_DEPLOYMENTS_DIR

Absolute path to which files located in S2I_SOURCE_DIR/S2I_SOURCE_DEPLOYMENTS_DIR are copied. Additionally, this is the directory to which build output is copied.

/deployments

http_proxy

The location of the http proxy. This takes precedence over HTTP_PROXY and is used for both Maven builds and Java runtime.

http://127.0.0.1:8080

https_proxy

The location of the https proxy. This takes precedence over HTTPS_PROXY, http_proxy, and HTTP_PROXY, and is used for both Maven builds and Java runtime.

myuser:mypass@127.0.0.1:8080

no_proxy

A comma separated list of hosts, IP addresses or domains that can be accessed directly. This takes precedence over NO_PROXY and is used for both Maven builds and Java runtime.

*.example.com

prefix_MAVEN_MIRROR_ID

ID to be used for the specified mirror. If omitted, a unique ID is generated.

internal-mirror

prefix_MAVEN_MIRROR_OF

Repository IDs mirrored by this entry. Defaults to external:.

-

prefix_MAVEN_MIRROR_URL

The URL of the mirror.

http://10.0.0.1:8080/repository/internal

prefix_MAVEN_REPO_DIRECTORY_PERMISSIONS

Maven repository directory permissions.

775

prefix_MAVEN_REPO_FILE_PERMISSIONS

Maven repository file permissions.

664

prefix_MAVEN_REPO_HOST

Maven repository host, if not using fully defined URL, falls back to service.

repo.example.com

prefix_MAVEN_REPO_ID

Maven repository ID.

my-repo-id

prefix_MAVEN_REPO_LAYOUT

Maven repository layout.

default

prefix_MAVEN_REPO_NAME

Maven repository name.

my-repo-name

prefix_MAVEN_REPO_PASSPHRASE

Maven repository passphrase.

maven1!

prefix_MAVEN_REPO_PASSWORD

Maven repository password.

maven1!

prefix_MAVEN_REPO_PATH

Maven repository path, if not using fully defined URL, falls back to service.

/maven2/

prefix_MAVEN_REPO_PORT

Maven repository port, if not using fully defined URL, falls back to service.

8080

prefix_MAVEN_REPO_PRIVATE_KEY

Maven repository private key.

${user.home}/.ssh/id_dsa

prefix_MAVEN_REPO_PROTOCOL

Maven repository protocol, if not using fully defined URL, falls back to service.

http

prefix_MAVEN_REPO_RELEASES_CHECKSUM_POLICY

Maven repository releases checksum policy.

warn

prefix_MAVEN_REPO_RELEASES_ENABLED

Maven repository releases enabled.

true

prefix_MAVEN_REPO_RELEASES_UPDATE_POLICY

Maven repository releases update policy.

always

prefix_MAVEN_REPO_SERVICE

Maven repository service to lookup if prefix_MAVEN_REPO_URL is not specified.

buscentr-myapp

prefix_MAVEN_REPO_SNAPSHOTS_CHECKSUM_POLICY

Maven repository snapshots checksum policy.

warn

prefix_MAVEN_REPO_SNAPSHOTS_ENABLED

Maven repository snapshots enabled.

true

prefix_MAVEN_REPO_SNAPSHOTS_UPDATE_POLICY

Maven repository snapshots update policy.

always

prefix_MAVEN_REPO_URL

Maven repository fully defined URL.

http://repo.example.com:8080/maven2/

prefix_MAVEN_REPO_USERNAME

Maven repository username.

mavenUser

Table 2.2. Configuration environment variables with default values
Variable nameDescriptionValue

AB_JOLOKIA_AUTH_OPENSHIFT

Switch on client authentication for OpenShift TLS communication. The value of this parameter can be a relative distinguished name which must be contained in a presented client’s certificate. Enabling this parameter automatically switches Jolokia into https communication mode. The default CA cert is set to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.

true

AB_JOLOKIA_HTTPS

Switch on secure communication with https. By default, self-signed server certificates are generated if no serverCert configuration is given in AB_JOLOKIA_OPTS.

true

AB_JOLOKIA_PASSWORD_RANDOM

Determines whether a random AB_JOLOKIA_PASSWORD is generated. Set to true to generate a random password. The generated value is written to /opt/jolokia/etc/jolokia.pw.

true

AB_PROMETHEUS_JMX_EXPORTER_CONFIG

Path to configuration to use for the Prometheus JMX Exporter.

/opt/jboss/container/prometheus/etc/jmx-exporter-config.yaml

S2I_SOURCE_DEPLOYMENTS_FILTER

A space separated list of filters to be applied when copying deployments. Defaults to *.

*

2.2.10. Additional resources

2.3. .NET Core

2.3.1. Benefits of Using .NET Core

.NET Core is a general purpose development platform featuring automatic memory management and modern programming languages. It allows users to build high-quality applications efficiently. .NET Core is available on Red Hat Enterprise Linux (RHEL 7) and OpenShift Container Platform via certified containers. .NET Core offers:

  • The ability to follow a microservices-based approach, where some components are built with .NET and others with Java, but all can run on a common, supported platform in Red Hat Enterprise Linux and OpenShift Container Platform.
  • The capacity to more easily develop new .NET Core workloads on Windows; customers are able to deploy and run on either Red Hat Enterprise Linux or Windows Server.
  • A heterogeneous data center, where the underlying infrastructure is capable of running .NET applications without having to rely solely on Windows Server.
  • Access to many of the popular development frameworks such as .NET, Java, Ruby, and Python from within OpenShift Container Platform.

2.3.2. Supported Versions

The .NET Core Life Cycle lists the currently supported versions of .NET Core.

2.3.3. Images

The images are available through the Red Hat Registry.

If you ran a standard installation, the dotnet image stream will be present. To include the latest supported versions you can install the .NET image streams.

2.3.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.3.5. Environment Variables

The .NET Core images support several environment variables, which you can set to control the build behavior of your .NET Core application.

Note

You must set environment variables that control build behavior in the S2I build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.3. NET Core Environment Variables
Variable NameDescriptionDefault

DOTNET_STARTUP_PROJECT

Selects projects to run. This must be a project file (for example, csproj or fsproj) or a folder containing a single project file.

.

DOTNET_ASSEMBLY_NAME

Selects the assembly to run. This must not include the .dll extension. Set this to the output assembly name specified in csproj (PropertyGroup/AssemblyName).

The name of the csproj file.

DOTNET_RESTORE_SOURCES

Specifies the space-separated list of NuGet package sources used during the restore operation. This overrides all of the sources specified in the NuGet.config file.

 

DOTNET_TOOLS

Specifies a list of .NET tools to install before building the application. To install a specific version, add @<version> to the end of the package name.

 

DOTNET_NPM_TOOLS

Specifies a list of NPM packages to install before building the application.

 

DOTNET_TEST_PROJECTS

Specifies the list of test projects to test. This must be project files or folders containing a single project file. dotnet test is invoked for each item.

 

DOTNET_CONFIGURATION

Runs the application in Debug or Release mode. This value should be either Release or Debug.

Release

DOTNET_VERBOSITY

Specifies the verbosity of the dotnet build commands. When set, the environment variables are printed at the start of the build. This variable can be set to one of the msbuild verbosity values (q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]).

 

HTTP_PROXY, HTTPS_PROXY

Configures the HTTP/HTTPS proxy used when building and running the application.

 

NPM_MIRROR

Uses a custom NPM registry mirror to download packages during the build process.

 

ASPNETCORE_URLS

This variable is set to http://*:8080 to configure ASP.NET Core to use the port exposed by the image. Changing this is not recommended.

http://*:8080

DOTNET_RM_SRC

When set to true, the source code is not included in the image.

 

DOTNET_SSL_DIRS

Used to specify a list of folders and files with additional SSL certificates to trust. The certificates are trusted by each process that runs during the build and all processes that run in the image after the build, including the application that was built. The items can be absolute paths starting with / or paths in the source repository (for example, certificates).

 

DOTNET_RESTORE_DISABLE_PARALLEL

When set to true, disables restoring multiple projects in parallel. This reduces restore timeout errors when the build container is running with low CPU limits.

false

DOTNET_INCREMENTAL

When set to true, the NuGet packages are kept so they can be re-used for an incremental build.

false

DOTNET_PACK

When set to true, creates a tar.gz file at /opt/app-root/app.tar.gz that contains the published application.

 

2.3.6. Quickly Deploying Applications from .NET Core Source

Important

The .NET image stream must first be installed. If you ran a standard installation, the image stream will be present.

An image can be used to build an application by running oc new-app against a sample repository:

$ oc new-app dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.1 --context-dir app

2.4. Node.js

2.4.1. Overview

OpenShift Container Platform provides S2I enabled Node.js images for building and running Node.js applications. The Node.js S2I builder image assembles your application source with any required dependencies to create a new image containing your Node.js application. This resulting image can be run either by OpenShift Container Platform or by a container runtime.

2.4.2. Versions

Currently, OpenShift Container Platform provides versions 0.10, 4, and 6 of Node.js.

2.4.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.redhat.io/openshift3/nodejs-010-rhel7
$ docker pull registry.redhat.io/rhscl/nodejs-4-rhel7

CentOS 7 Based Image

This image is available on Docker Hub:

$ docker pull openshift/nodejs-010-centos7

To use these images, you can either access them directly from these image registries, or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.4.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.4.5. Configuration

The Node.js image supports a number of environment variables, which can be set to control the configuration and behavior of the Node.js runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.4. Development Mode Environment Variables
Variable nameDescription

DEV_MODE

When set to true, enables hot deploy and opens the debug port. Additionally, indicates to tooling that the image is in development mode. Default is false.

DEBUG_PORT

The debug port. Only valid if DEV_MODE is set to true. Default is 5858.

NPM_MIRROR

The custom NPM registry mirror URL. All NPM packages will be downloaded from the mirror link during the build process.

2.4.6. Hot Deploying

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. In order to immediately pick up changes made in your application source code, you must run your built image with the DEV_MODE=true environment variable.

You can set new environment variables when creating new applications, or updating environment variables for existing objects.

Warning

Only use the DEV_MODE=true environment variable while developing or debugging. Using this in your production environment is not recommended.

To change the source code of a running pod, open a remote shell into the container:

$ oc rsh <pod_id>

Entering into a running container changes your current directory to /opt/app-root/src, where the source code is located.

2.5. Perl

2.5.1. Overview

OpenShift Container Platform provides S2I enabled Perl images for building and running Perl applications. The Perl S2I builder image assembles your application source with any required dependencies to create a new image containing your Perl application. This resulting image can be run either by OpenShift Container Platform or by a container runtime.

2.5.2. Versions

Currently, OpenShift Container Platform supports versions 5.16, 5.20, and 5.24 of Perl.

2.5.3. Images

Images comes in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.redhat.io/openshift3/perl-516-rhel7
$ docker pull registry.redhat.io/rhscl/perl-520-rhel7
$ docker pull registry.redhat.io/rhscl/perl-524-rhel7

CentOS 7 Based Image

A CentOS image for Perl 5.16 is available on Docker Hub:

$ docker pull openshift/perl-516-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platformt resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.5.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.5.5. Configuration

The Perl image supports a number of environment variables which can be set to control the configuration and behavior of the Perl runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.5. Perl Environment Variables
Variable nameDescription

ENABLE_CPAN_TEST

When set to true, this variable installs all the cpan modules and runs their tests. By default, the testing of the modules is turned off.

CPAN_MIRROR

This variable specifies a mirror URL which cpanminus uses to install dependencies. By default, this URL is not specified.

PERL_APACHE2_RELOAD

Set this to true to enable automatic reloading of modified Perl modules. By default, automatic reloading is turned off.

HTTPD_START_SERVERS

The StartServers directive sets the number of child server processes created on startup. Default is 8.

HTTPD_MAX_REQUEST_WORKERS

Number of simultaneous requests that will be handled by Apache. The default is 256, but it will be automatically lowered if memory is limited.

2.5.6. Accessing Logs

Access logs are streamed to standard output and as such they can be viewed using the oc logs command. Error logs are stored in the /tmp/error_log file, which can be viewed using the oc rsh command to access the container.

2.5.7. Hot Deploying

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. To enable hot deployment in this image, you must set the PERL_APACHE2_RELOAD environment variable to true. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

2.6. PHP

2.6.1. Overview

OpenShift Container Platform provides S2I enabled PHP images for building and running PHP applications. The PHP S2I builder image assembles your application source with any required dependencies to create a new image containing your PHP application. This resulting image can be run either by OpenShift Container Platform or by a container runtime.

2.6.2. Versions

Currently, OpenShift Container Platform provides versions 5.5, 5.6, and 7.0 of PHP.

2.6.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.redhat.io/openshift3/php-55-rhel7
$ docker pull registry.redhat.io/rhscl/php-56-rhel7
$ docker pull registry.redhat.io/rhscl/php-70-rhel7

CentOS 7 Based Images

CentOS images for PHP 5.5 and 5.6 are available on Docker Hub:

$ docker pull openshift/php-55-centos7
$ docker pull openshift/php-56-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the image stream.

You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.6.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.6.5. Configuration

The PHP image supports a number of environment variables which can be set to control the configuration and behavior of the PHP runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

The following environment variables set their equivalent property value in the php.ini file:

Table 2.6. PHP Environment Variables
Variable NameDescriptionDefault

ERROR_REPORTING

Informs PHP of the errors, warnings, and notices for which you would like it to take action.

E_ALL & ~E_NOTICE

DISPLAY_ERRORS

Controls if and where PHP outputs errors, notices, and warnings.

ON

DISPLAY_STARTUP_ERRORS

Causes any display errors that occur during PHP’s startup sequence to be handled separately from display errors.

OFF

TRACK_ERRORS

Stores the last error/warning message in $php_errormsg (boolean).

OFF

HTML_ERRORS

Links errors to documentation that is related to the error.

ON

INCLUDE_PATH

Path for PHP source files.

.:/opt/openshift/src:/opt/rh/php55/root/usr/share/pear

SESSION_PATH

Location for session data files.

/tmp/sessions

DOCUMENTROOT

Path that defines the document root for your application (for example, /public).

/

The following environment variable sets its equivalent property value in the opcache.ini file:

Table 2.7. Additional PHP settings
Variable NameDescriptionDefault

OPCACHE_MEMORY_CONSUMPTION

The OPcache shared memory storage size.

16M

OPCACHE_REVALIDATE_FREQ

How often to check script time stamps for updates, in seconds. 0 results in OPcache checking for updates on every request.

2

You can also override the entire directory used to load the PHP configuration by setting:

Table 2.8. Additional PHP settings
Variable NameDescription

PHPRC

Sets the path to the php.ini file.

PHP_INI_SCAN_DIR

Path to scan for additional .ini configuration files

You can use a custom composer repository mirror URL to download packages instead of the default 'packagist.org':

Table 2.9. Composer Environment Variables
Variable NameDescription

COMPOSER_MIRROR

Set this variable to use a custom Composer repository mirror URL to download required packages during the build process. Note: This only affects packages listed in composer.json.

2.6.5.1. Apache Configuration

If the DocumentRoot of the application is nested in the source directory /opt/openshift/src, you can provide your own .htaccess file to override the default Apache behavior and specify how application requests should be handled. The .htaccess file must be located at the root of the application source.

2.6.6. Accessing Logs

Access logs are streamed to standard out and as such they can be viewed using the oc logs command. Error logs are stored in the /tmp/error_log file, which can be viewed using the oc rsh command to access the container.

2.6.7. Hot Deploying

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. In order to immediately pick up changes made in your application source code, you must run your built image with the OPCACHE_REVALIDATE_FREQ=0 environment variable.

For example, see the oc new-app command. You can use the oc env command to update environment variables of existing objects.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

2.7. Python

2.7.1. Overview

OpenShift Container Platform provides S2I enabled Python images for building and running Python applications. The Python S2I builder image assembles your application source with any required dependencies to create a new image containing your Python application. This resulting image can be run either by OpenShift Container Platform or by a container runtime.

2.7.2. Versions

Currently, OpenShift Container Platform provides versions 2.7, 3.3, 3.4, and 3.5 of Python.

2.7.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.redhat.io/rhscl/python-27-rhel7
$ docker pull registry.redhat.io/openshift3/python-33-rhel7
$ docker pull registry.redhat.io/rhscl/python-34-rhel7
$ docker pull registry.redhat.io/rhscl/python-35-rhel7

CentOS 7 Based Images

These images are available on Docker Hub:

$ docker pull centos/python-27-centos7
$ docker pull openshift/python-33-centos7
$ docker pull centos/python-34-centos7
$ docker pull centos/python-35-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.7.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.7.5. Configuration

The Python image supports a number of environment variables which can be set to control the configuration and behavior of the Python runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.10. Python Environment Variables
Variable nameDescription

APP_FILE

This variable specifies the file name passed to the Python interpreter which is responsible for launching the application. This variable is set to app.py by default.

APP_MODULE

This variable specifies the WSGI callable. It follows the pattern $(MODULE_NAME):$(VARIABLE_NAME), where the module name is a full dotted path and the variable name refers to a function inside the specified module. If you use setup.py for installing the application, then the module name can be read from that file and the variable defaults to application. There is an example setup-test-app available.

APP_CONFIG

This variable indicates the path to a valid Python file with a gunicorn configuration.

DISABLE_COLLECTSTATIC

Set it to a nonempty value to inhibit the execution of manage.py collectstatic during the build. Only affects Django projects.

DISABLE_MIGRATE

Set it to a nonempty value to inhibit the execution of manage.py migrate when the produced image is run. Only affects Django projects.

PIP_INDEX_URL

Set this variable to use a custom index URL or mirror to download required packages during build process. This only affects packages listed in the requirements.txt file.

WEB_CONCURRENCY

Set this to change the default setting for the number of workers. By default, this is set to the number of available cores times 4.

2.7.6. Hot Deploying

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. If you are using Django, hot deployment works out of the box.

To enable hot deployment while using Gunicorn, ensure you have a Gunicorn configuration file inside your repository with the reload option set to true. Specify your configuration file using the APP_CONFIG environment variable. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

2.8. Ruby

2.8.1. Overview

OpenShift Container Platform provides S2I enabled Ruby images for building and running Ruby applications. The Ruby S2I builder image assembles your application source with any required dependencies to create a new image containing your Ruby application. This resulting image can be run either by OpenShift Container Platform or by a container runtime.

2.8.2. Versions

Currently, OpenShift Container Platform provides versions 2.0, 2.2, and 2.3 of Ruby.

2.8.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The RHEL 7 images are available through the Red Hat registry:

$ docker pull registry.redhat.io/openshift3/ruby-20-rhel7
$ docker pull registry.redhat.io/rhscl/ruby-22-rhel7
$ docker pull registry.redhat.io/rhscl/ruby-23-rhel7

CentOS 7 Based Images

These images are available on Docker Hub:

$ docker pull openshift/ruby-20-centos7
$ docker pull openshift/ruby-22-centos7
$ docker pull centos/ruby-23-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.8.4. Build Process

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

  1. Starts a container from the builder image.
  2. Downloads the application source.
  3. Streams the scripts and application sources into the builder image container.
  4. Runs the assemble script (from the builder image).
  5. Saves the final image.

See S2I Build Process for a detailed overview of the build process.

2.8.5. Configuration

The Ruby image supports a number of environment variables which can be set to control the configuration and behavior of the Ruby runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.11. Ruby Environment Variables
Variable nameDescription

RACK_ENV

This variable specifies the environment within which the Ruby application is deployed; for example, production, development, or test. Each level has different behavior in terms of logging verbosity, error pages, and ruby gem installation. The application assets are only compiled if RACK_ENV is set to production; the default value is production.

RAILS_ENV

This variable specifies the environment within which the Ruby on Rails application is deployed; for example, production, development, or test. Each level has different behavior in terms of logging verbosity, error pages, and ruby gem installation. The application assets are only compiled if RAILS_ENV is set to production. This variable is set to ${RACK_ENV} by default.

DISABLE_ASSET_COMPILATION

When set to true, this variable disables the process of asset compilation. Asset compilation only happens when the application runs in a production environment. Therefore, you can use this variable when assets have already been compiled.

PUMA_MIN_THREADS, PUMA_MAX_THREADS

This variable indicates the minimum and maximum number of threads that will be available in Puma's thread pool.

PUMA_WORKERS

This variable indicates the number of worker processes to be launched in Puma’s clustered mode (when Puma runs more than two processes). If not explicitly set, the default behavior sets PUMA_WORKERS to a value that is appropriate for the memory available to the container and the number of cores on the host.

RUBYGEM_MIRROR

Set this variable to use a custom RubyGems mirror URL to download required gem packages during the build process. Note: This environment variable is only available for Ruby 2.2+ images.

2.8.6. Hot Deploying

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. The method for enabling hot deployment in this image differs based on the application type.

Ruby on Rails Applications

For Ruby on Rails application, run the built Rails application with the RAILS_ENV=development environment variable passed to the running pod. For an existing deployment configuration, you can use the oc set env command:

$ oc set env dc/rails-app RAILS_ENV=development

Other Types of Ruby Applications (Sinatra, Padrino, etc.)

For other types of Ruby applications, your application must be built with a gem that can reload the server every time a change to the source code is made inside the running container. Those gems are:

In order to be able to run your application in development mode, you must modify the S2I run script so that the web server is launched by the chosen gem, which checks for changes in the source code.

After you build your application image with your version of the S2I run script, run the image with the RACK_ENV=development environment variable. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

2.9. Customizing S2I Images

2.9.1. Overview

S2I builder images normally include assemble and run scripts, but the default behavior of those scripts may not be suitable for all users. This topic covers a few approaches for customizing the behavior of an S2I builder that includes default scripts.

2.9.2. Invoking Scripts Embedded in an Image

Typically, builder images provide their own version of the S2I scripts that cover the most common use-cases. If these scripts do not fulfill your needs, S2I provides a way of overriding them by adding custom ones in the .s2i/bin directory. However, by doing this you are completely replacing the standard scripts. In some cases this is acceptable, but in other scenarios you may prefer to execute a few commands before (or after) the scripts while retaining the logic of the script provided in the image. In this case, it is possible to create a wrapper script that executes custom logic and delegates further work to the default script in the image.

To determine the location of the scripts inside of the builder image, look at the value of io.openshift.s2i.scripts-url label. Use docker inspect:

$ docker inspect --format='{{ index .Config.Labels "io.openshift.s2i.scripts-url" }}' openshift/wildfly-100-centos7
image:///usr/libexec/s2i

You inspected the openshift/wildfly-100-centos7 builder image and found out that the scripts are in the /usr/libexec/s2i directory.

With this knowledge, invoke any of these scripts from your own by wrapping its invocation.

Example 2.1. .s2i/bin/assemble script

#!/bin/bash
echo "Before assembling"

/usr/libexec/s2i/assemble
rc=$?

if [ $rc -eq 0 ]; then
    echo "After successful assembling"
else
    echo "After failed assembling"
fi

exit $rc

The example shows a custom assemble script that prints the message, executes standard assemble script from the image and prints another message depending on the exit code of the assemble script.

When wrapping the run script, you must use exec for invoking it to ensure signals are handled properly. Unfortunately, the use of exec also precludes the ability to run additional commands after invoking the default image run script.

Example 2.2. .s2i/bin/run script

#!/bin/bash
echo "Before running application"
exec /usr/libexec/s2i/run
Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

© 2024 Red Hat, Inc.