Customize S2I Templates

This tutorial demonstrates how to create an Image Builder that contains an NGINX service. If you need to use runtime images in your project, refer to this document for more information about how to create a runtime image.

S2I template customization can be divided into two parts.

• Part 1: S2I Image Builder customization
  • assemble (required): the script that builds application artifacts from source code.
  • run (required): the run script that executes an application.
  • save-artifacts (optional): the save-artifacts script that manages all dependencies in an incremental building process.
  • usage (optional): the script that provides instructions.
  • test (optional): the script for testing.
• Part 2: definition of S2I template

You need to have the required elements for S2I template customization ready in advance.

Note

The Image Builder is compatible with that of OpenShift, and you can reuse it in KubeSphere. For more information about S2I Image Builders, refer to .

1. The S2I command line tool provides an easy-to-use command to initialize a base directory structure required by the Builder. Run the following commands to install the S2I CLI.

2. This tutorial uses nginx-centos7 as the name of the Image Builder. Run the s2i create command to initialize the base directory structure.

   s2i create nginx-centos7 s2i-builder-docs

3. The directory structure is initialized as follows.

   s2i-builder-docs/
      Dockerfile - a standard Dockerfile to define the Image Builder
      Makefile - a script for testing and building the Image Builder
      test/
         run - a script that runs the application to test whether the Image Builder is working properly
         test-app/ - directory of the test application
      s2i/bin
         assemble - a script that builds the application
         run - a script that runs the application
         usage - a script that prints the usage of the Image Builder

Step 2: Modify the Dockerfile

A Dockerfile installs all of the necessary tools and libraries that are needed to build and run an application. This file will also copy the S2I scripts into the output image.

Dockerfile

# nginx-centos7
FROM kubespheredev/s2i-base-centos7:1
# Here you can specify the maintainer for the image that you're building
LABEL maintainer="maintainer name <[email protected]>"
# Define the current version of the application
ENV NGINX_VERSION=1.6.3
LABEL io.k8s.description="Nginx Webserver" \
      io.k8s.display-name="Nginx 1.6.3" \
      io.kubesphere.expose-services="8080:http" \
      io.kubesphere.tags="builder,nginx,html"
# Install the nginx web server package and clean the yum cache
RUN yum install -y epel-release && \
    yum install -y --setopt=tsflags=nodocs nginx && \
    yum clean all
# Change the default port for nginx
RUN sed -i 's/80/8080/' /etc/nginx/nginx.conf
RUN sed -i 's/user nginx;//' /etc/nginx/nginx.conf
COPY ./s2i/bin/ /usr/libexec/s2i
RUN chown -R 1001:1001 /usr/share/nginx
RUN chown -R 1001:1001 /var/log/nginx
RUN chown -R 1001:1001 /var/lib/nginx
RUN touch /run/nginx.pid
RUN chown -R 1001:1001 /run/nginx.pid
RUN chown -R 1001:1001 /etc/nginx
USER 1001
# Set the default port for applications built using this image
EXPOSE 8080
# Modify the usage script in your application dir to inform the user how to run this image.
CMD ["/usr/libexec/s2i/usage"]

Note

S2I scripts will use the flags defined in the Dockerfile as parameters. If you need to use a base image different from those provided by KubeSphere, refer to .

1. Create an assemble script as follows to copy the configuration file and static contents to the target container.

   Note

   By default, s2i build places the application source code in /tmp/src. The above commands copy the application source code to the working directory /opt/app-root/src defined by kubespheredev/s2i-base-centos7:1.

2. Create a run script as follows. In this tutorial, it only starts the nginx server.

   #!/bin/bash -e
   exec /usr/sbin/nginx -g "daemon off;"

   Note

   This tutorial uses the exec command to execute the host process of nginx server to let all signals sent from docker be received by nginx while nginx can use the standard input and output streams of the container. Besides, the save-artifacts script allows a new build to reuse content from a previous version of application image. The save-artifacts script can be deleted because this tutorial does not implement incremental building.

3. Create a usage script as follows. It prints out instructions on how to use the image.

   #!/bin/bash -e
   cat <<EOF
   This is the nginx-centos7 S2I image:
   To use it, install S2I: https://github.com/kubesphere/s2i-operator
   You can then run the resulting image via:
   docker run -d -p 8080:8080 nginx-centos7-app
   and see the test via http://localhost:8080
   EOF

Step 4: Build and run

1. IMAGE_NAME = kubespheredev/nginx-centos7-s2ibuilder-sample
   # Create an Image Builder named above based on the Dockerfile that was created previously.
   .PHONY: build
   build:
    docker build -t $(IMAGE_NAME) .
   # The Image Builder can be tested using the following commands:
   .PHONY: test
   test:
    docker build -t $(IMAGE_NAME)-candidate .
    IMAGE_NAME=$(IMAGE_NAME)-candidate test/run

2. Run the make build command to build the Image Builder for NGINX.

3. With the Image Builder created, run the following command to create an application image.

   $ s2i build ./test/test-app kubespheredev/nginx-centos7-s2ibuilder-sample:latest sample-app
   ---> Building and installing application from source...
   Build completed successfully

   Note

   Following the logic defined in the assemble script, S2I creates an application image using the Image Builder as a base and injecting the source code from the test/test-app directory.

4. Run the following command to run the application image.

   docker run -p 8080:8080  sample-app

   You can access the Nginx application at http://localhost:8080.

Once you finish testing the S2I Image Builder locally, you can push the image to your custom image repository. You also need to create a YAML file as the S2I Builder template as follows.

s2ibuildertemplate.yaml

apiVersion: devops.kubesphere.io/v1alpha1
kind: S2iBuilderTemplate
metadata:
  labels:
    controller-tools.k8s.io: "1.0"
    builder-type.kubesphere.io/s2i: "s2i"
  name: nginx-demo
spec:
  containerInfo:
    - builderImage: kubespheredev/nginx-centos7-s2ibuilder-sample
  codeFramework: nginx # type of code framework
  defaultBaseImage: kubespheredev/nginx-centos7-s2ibuilder-sample # default Image Builder (can be replaced by a customized image)
  version: 0.0.1 # Builder template version
  description: "This is an S2I builder template for NGINX builds whose result can be run directly without any further application server." # Builder template description

Step 6: Use the S2I template on KubeSphere

1. Run the following command to submit the S2I template created above to KubeSphere.

2. You can find the customized S2I template available in Build Environment when you create an S2I build on KubeSphere.

Refer to the following detailed descriptions of S2I template parameters. The required parameters are marked with an asterisk.