Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Flexible Images or Using S2I for Image Configuration

 

November 29, 2017
Eliska Slobodova
Related topics:
ContainersLinuxKubernetes
Related products:
Red Hat OpenShiftRed Hat OpenShift Container PlatformRed Hat Enterprise Linux

Share:

    Container images usually come with pre-defined tools or services with minimal or limited possibilities of further configuration. This brought us into a way of thinking of how to provide images that contain reasonable default settings but are, at the same time, easy to extend. And to make it more fun, this would be possible to achieve both on a single Linux host and in an orchestrated OpenShift environment.

    Source-to-image (S2I) has been introduced three years ago to allow developers to build containerized applications by simply providing source code as an input. So why couldn’t we use it to make configuration files as an input instead? We can, of course!

    Creating an Extensible Image

    Creating S2I builder images was already described in an article by Maciej Szulik and creating images that are extensible and flexible enough to be adjusted with custom configuration is not much different. So let’s focus on the bits that are essential for making an image configurable.

    Required Scripts

    The two scripts that every builder image must provide are; assemble and run, both are included in the s2i/bin/ directory.

    assemble

    The assemble script defines how the application image is assembled.

    Let’s look at the official Software Collections nginx S2I builder image to see its default behavior. When you open the assemble script (snippet below), you see that by default the nginx builder image looks in the nginx-cfg/ and nginx-default-cfg/ directories within the provided source code where it expects to find your configuration files used for creating a customized application image.

    if [ -d ./nginx-cfg ]; then
      echo "---> Copying nginx configuration files..."
      if [ "$(ls -A ./nginx-cfg/*.conf)" ]; then
        cp -v ./nginx-cfg/*.conf "${NGINX_CONFIGURATION_PATH}"
        rm -rf ./nginx-cfg
      fi
    fi
    
    if [ -d ./nginx-default-cfg ]; then
      echo "---> Copying nginx default server configuration files..."
      if [ "$(ls -A ./nginx-default-cfg/*.conf)" ]; then
        cp -v ./nginx-default-cfg/*.conf "${NGINX_DEFAULT_CONF_PATH}"
        rm -rf ./nginx-default-cfg
      fi
    fi

    run

    The run script is responsible for running the application container. In the nginx case, once the application container is run, the nginx server is started on the foreground.

    exec /usr/sbin/nginx -g "daemon off;"

    Labels

    To tell s2i where it should expect the scripts, you need to define a label in the Dockerfile:

    LABEL io.openshift.s2i.scripts-url="image:///usr/libexec/s2i"

    Alternatively, you can also specify custom assemble and run scripts by collocating them with your source/config files;  the scripts baked in the builder image would then be overridden.

    Optional Scripts

    Since S2I provides quite a complex set of capabilities, you should always provide documentation on how users are expected to use your image. Test configuration (or application) might come in handy as well.

    usage

    This script outputs instructions on how to use the image when the container is run.

    test/run and test/test-app

    These scripts will test the application source code and run of the builder image.

    To make the creation of these images easier, you can take advantage of the S2I container image template.

    Extending an Image with Custom Configuration

    Now let’s have a look at how you can use such an image in the real world.

    Again, we’re going to take the above nginx image to demonstrate how to adjust it to build a containerized application with custom configuration.

    One of the advantages of using source-to-image for configuration is that it can be used on any standalone Linux platform as well as in an orchestrated OpenShift environment.

    On Red Hat Enterprise Linux, it is as easy as running the following command:

    $ s2i build https://github.com/sclorg/nginx-container.git --context-dir=1.12/test/test-app/ registry.access.redhat.com/rhscl/nginx-112-rhel7 nginx-sample-app

    The s2i build command takes the configuration files in the test/test-app/ directory and injects them in the output nginx-sample-app image.

    Note that by default, s2i takes a repository as an input and looks for files in its root directory. In this case, the configuration files are in a subdirectory, hence specifying the --context-dir.

    $ docker run --rm -p 8080:8080 nginx-sample-app

    Running the container will then show you a website informing you that your Nginx server is working.

    And similarly in OpenShift:

    $ oc new-app registry.access.redhat.com/rhscl/nginx-112-rhel7~https://github.com/sclorg/nginx-container.git --context-dir=1.12/test/test-app/ --name nginx-test-app

    The oc new-app command creates and deploys a new image nginx-test-app modified with the configuration provided in the test/test-app/ directory.

    After creating a route, you should see the same message as above.

    Advantages of Using an S2I Builder Image for Extension

    To sum it up, there are a number of reasons to leverage S2I for your project.

    • Flexibility - You can customize a service to fit your needs by providing a configuration file that rewrites the values used in a container by default. And it doesn’t end there: do you want to install an additional plugin that is not included in your database image by default or install and run arbitrary commands? S2I-enabled images allow for this.
    • Any platform - You can use S2I for building standalone containers on several Linux platforms that provide the s2i RPM package, including Red Hat Enterprise Linux, CentOS, and Fedora or take advantage of the s2i binary. The S2I build strategy is one of the integrated build strategies in OpenShift, so you can easily leverage it for building containers deployed in an orchestrated environment as well.
    • Separated images and service configuration - Although having a clear distinction between images and service configuration allows you to perform adjustments that are more complex, the build reproducibility remains preserved at the same time.

    Pull and Run a Flexible Image Now

    The following images are now available as S2I builders from the Red Hat Container Catalog and can be easily extended as demonstrated above:

    • MongoDB
    • MariaDB
    • Nginx
    • Varnish

    More images will appear in the Catalog soon. In the meantime, you can try out their upstream counterparts.

    The source-to-image project contains extensive documentation with examples, so head over to the project’s GitHub page if you’d like to learn more.

    Resources

    • https://github.com/openshift/source-to-image
    • http://docs.projectatomic.io/container-best-practices/#_builder_images
    • https://github.com/container-images/s2i-container-image-template
    • https://blog.openshift.com/override-s2i-builder-scripts/
    • https://cloud.redhat.com/blog/create-s2i-builder-image

    Join the Red Hat Developer Program (it’s free) and get access to related cheat sheets, books, and product downloads.

    Last updated: November 1, 2023

    Recent Posts

    • More Essential AI tutorials for Node.js Developers

    • How to run a fraud detection AI model on RHEL CVMs

    • How we use software provenance at Red Hat

    • Alternatives to creating bootc images from scratch

    • How to update OpenStack Services on OpenShift

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue