diff --git a/content/en/docs/project-user-guide/image-builder/s2i-introduction.md b/content/en/docs/project-user-guide/image-builder/s2i-introduction.md new file mode 100644 index 000000000..ebb2df551 --- /dev/null +++ b/content/en/docs/project-user-guide/image-builder/s2i-introduction.md @@ -0,0 +1,39 @@ +--- +title: "S2I Workflow and Logic" +keywords: 'KubeSphere, Kubernetes, Docker, S2I, Source-to-Image' +description: 'Understand how S2I works and why it works in the expected way.' +linkTitle: "S2I Workflow and Logic" +weight: 10630 +--- + +Source-to-Image (S2I) is an automation tool for building images from source code. S2I injects source code into an Image Builder for compiling and then automatically packages the compiled code into a Docker image. + +For more information about how to use S2I in KubeSphere, refer to [Source to Image: Publish an App without a Dockerfile](../source-to-image/). Besides, you can refer to the code repositories [S2IOperator](https://github.com/kubesphere/s2ioperator#source-to-image-operator) and [S2IRun](https://github.com/kubesphere/s2irun#s2irun) for more details. + +## S2I Workflow and Logic + +### Image Builder + +For interpreted languages like Python and Ruby, the build-time and runtime environments for an application are typically the same. For example, a Ruby-based Image Builder usually contains Bundler, Rake, Apache, GCC, and other packages needed to set up a runtime environment. The following diagram describes the build workflow. + +![s2i-builder](/images/docs/project-user-guide/image-builder/s2i-intro/s2i-builder.png) + +### How S2I works + +S2I performs the following steps: + +1. Start a container from the Image Builder with the application source code injected into a specified directory. +2. Execute the `assemble` script from the Image Builder to build that source code into a ready-to-run application by installing dependencies and moving the source code into a working directory. +3. Set the `run` script provided by the Image Builder as the image entrypoint for starting the container, and then commit a new image as the application image to meet user needs. + +See the S2I workflow chart as below. + +![s2i-flow](/images/docs/project-user-guide/image-builder/s2i-intro/s2i-flow.png) + +### Runtime Image + +For compiled languages like Go, C, C++, or Java, the dependencies necessary for compiling will increase the size of resulting images. To build slimmer images, S2I uses a phased build workflow with unnecessary files removed from images. An artifact, which is an executable like a Jar file or binary file, will be extracted when building finishes in the Image Builder, and then injected into a Runtime Image for execution. + +See the building workflow as below. + +![s2i-runtime-build](/images/docs/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png) \ No newline at end of file diff --git a/content/en/docs/project-user-guide/image-builder/s2i-templates.md b/content/en/docs/project-user-guide/image-builder/s2i-templates.md new file mode 100644 index 000000000..28146dc55 --- /dev/null +++ b/content/en/docs/project-user-guide/image-builder/s2i-templates.md @@ -0,0 +1,330 @@ +--- +title: "Customize S2I Templates" +keywords: 'KubeSphere, Kubernetes, Docker, S2I, Source-to-Image' +description: 'Customize S2I templates and understand different template parameters.' +linkTitle: "Customize S2I Templates" +aliases: + - "docs/project-user-guide/application-workloads/s2i-template/" +weight: 10640 +--- + +Once you have understood the workflow and logic of Source-to-Image (S2I), you can customize Image Builder templates (i.e. S2I/B2I templates) based on your projects to extend S2I capabilities. KubeSphere provides several common Image Builder templates based on different languages, such as [Python](https://github.com/kubesphere/s2i-python-container/) and [Java](https://github.com/kubesphere/s2i-java-container/). + +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](https://github.com/kubesphere/s2irun/blob/master/docs/runtime_image.md) for more information about how to create a runtime image. + +## Prerequisites + +S2I template customization can be divided into two parts. + +- Part 1: S2I Image Builder customization + - assemble (required): the `assemble` 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. + +{{< notice 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 [S2IRun](https://github.com/kubesphere/s2irun/blob/master/docs/builder_image.md#s2i-builder-image-requirements). + +{{}} + +## Create an Image Builder + +### Step 1: Prepare an S2I directory + +1. The [S2I command line tool](https://github.com/openshift/source-to-image/releases) 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. + + ```bash + $ wget https://github.com/openshift/source-to-image/releases/download/v1.1.14/source-to-image-v1.1.14-874754de-linux-386.tar.gz + $ tar -xvf source-to-image-v1.1.14-874754de-linux-386.tar.gz + $ ls + s2i source-to-image-v1.1.14-874754de-linux-386.tar.gz sti + $ cp s2i /usr/local/bin + ``` + +2. This tutorial uses `nginx-centos7` as the name of the Image Builder. Run the `s2i create` command to initialize the base directory structure. + + ```bash + 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. + +Modify the Dockerfile as follows to define the Image Builder. + +#### 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 " + +# Define the current version of the application +ENV NGINX_VERSION=1.6.3 + +# Set the labels that are used for KubeSphere to describe the Image Builder. +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 the S2I scripts to /usr/libexec/s2i in the Image Builder +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"] +``` + +{{< notice 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 [S2I Scripts](https://github.com/kubesphere/s2irun/blob/master/docs/builder_image.md#s2i-scripts). + +{{}} + +### Step 3: Create S2I Scripts + +1. Create an `assemble` script as follows to copy the configuration file and static contents to the target container. + + ```bash + #!/bin/bash -e + + if [[ "$1" == "-h" ]]; then + exec /usr/libexec/s2i/usage + fi + + echo "---> Building and installing application from source..." + if [ -f /tmp/src/nginx.conf ]; then + mv /tmp/src/nginx.conf /etc/nginx/nginx.conf + fi + + if [ "$(ls -A /tmp/src)" ]; then + mv /tmp/src/* /usr/share/nginx/html/ + fi + ``` + + {{< notice 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. + + ```bash + #!/bin/bash -e + + exec /usr/sbin/nginx -g "daemon off;" + ``` + + {{< notice 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. + + ```bash + #!/bin/bash -e + cat < 48f8574c05df + Step 2/17 : LABEL maintainer="Runze Xia " + ---> Using cache + ---> d60ebf231518 + Step 3/17 : ENV NGINX_VERSION=1.6.3 + ---> Using cache + ---> 5bd34674d1eb + Step 4/17 : 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" + ---> Using cache + ---> c837ad649086 + Step 5/17 : RUN yum install -y epel-release && yum install -y --setopt=tsflags=nodocs nginx && yum clean all + ---> Running in d2c8fe644415 + + ………… + ………… + ………… + + Step 17/17 : CMD ["/usr/libexec/s2i/usage"] + ---> Running in c24819f6be27 + Removing intermediate container c24819f6be27 + ---> c147c86f2cb8 + Successfully built c147c86f2cb8 + Successfully tagged kubespheredev/nginx-centos7-s2ibuilder-sample:latest + ``` + +3. With the Image Builder created, run the following command to create an application image. + + ```bash + $ s2i build ./test/test-app kubespheredev/nginx-centos7-s2ibuilder-sample:latest sample-app + ---> Building and installing application from source... + Build completed successfully + ``` + + {{< notice 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. + + ```bash + docker run -p 8080:8080 sample-app + ``` + + You can access the Nginx application at `http://localhost:8080`. + + ![access-nginx](/images/docs/project-user-guide/image-builder/s2i-templates/access-nginx.png) + +### Step 5: Push the image and create an S2I template + +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 + +```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. + + ```bash + $ kubectl apply -f s2ibuildertemplate.yaml + s2ibuildertemplate.devops.kubesphere.io/nginx created + ``` + +2. You can find the customized S2I template available when you create an S2I build on KubeSphere. + + ![template-available](/images/docs/project-user-guide/image-builder/s2i-templates/template-available.png) + +## S2I Template Parameters Definition + +Refer to the following detailed descriptions of S2I template labels passed as parameters for frontend classification. + +| Label Name | Option | Definition | +| ------------------------------------- | ---------------------- | ------------------------------------------------------------ | +| builder-type.kubesphere.io/s2i: "s2i" | "s2i" | The type of this template is S2I, which builds images based on application source code. | +| builder-type.kubesphere.io/b2i | "b2i" | The type of this template is B2I, which builds images based on binary files or other artifacts. | +| binary-type.kubesphere.io | "jar", "war", "binary" | This type is complementary to the type of B2I and will be required when B2I is selected. For example, select the type of "jar" when a JAR package is provided. In KubeSphere v2.1.1 and later, it is also allowed to customize B2I templates. | + +Refer to the following detailed descriptions of S2I template parameters. The required parameters are marked with an asterisk. + +| Parameter | Type | Definition | +| ------------------------------------------ | -------- | ------------------------------------------------------------ | +| *containerInfo | []struct | The information about Image Builder. | +| *containerInfo.builderImage | string | S2I Image Builder, such as kubesphere/java-8-centos7:v2.1.0. | +| containerInfo.runtimeImage | string | S2I Runtime Image, such as kubesphere/java-8-runtime:v2.1.0. | +| containerInfo.buildVolumes | []string | The information about mounted volumes. The format is "volume_name:mount_path", such as ["s2i_java_cache:/tmp/artifacts","test_cache:test_path"]. | +| containerInfo.runtimeArtifacts | []struct | The list of original path and target path for the output artifact; only add it for phased building. | +| containerInfo.runtimeArtifacts.source | string | The original path of artifact in Image Builder. | +| containerInfo.runtimeArtifacts.destination | string | The target path of artifact in Runtime Image. | +| containerInfo.runtimeArtifacts.keep | bool | Whether to keep the data in the output image. | +| *defaultBaseImage | string | The default Image Builder. | +| *codeFramework | string | The code framework type, such as Java and Ruby. | +| environment | []struct | The list of environment variables in the building process. | +| environment.key | string | The name of environment variables. | +| environment.type | string | The type of environment variable keys. | +| environment.description | string | The description of environment variables. | +| environment.optValues | []string | The list of parameters for environment variables. | +| environment.required | bool | Whether the environment variable is required to be set. | +| environment.defaultValue | string | The default value of environment variables. | +| environment.value | string | The value of environment variables. | +| iconPath | string | The application name. | +| version | string | The version of S2I template. | +| description | string | The description of the template's functions and usage. | + diff --git a/content/zh/docs/project-user-guide/image-builder/s2i-introduction.md b/content/zh/docs/project-user-guide/image-builder/s2i-introduction.md new file mode 100644 index 000000000..1eab32b36 --- /dev/null +++ b/content/zh/docs/project-user-guide/image-builder/s2i-introduction.md @@ -0,0 +1,39 @@ +--- +title: "S2I 工作流程和逻辑" +keywords: 'KubeSphere, Kubernetes, Docker, S2I, Source-to-Image' +description: '了解 S2I 的工作原理及其为何按照预期工作。' +linkTitle: "S2I 工作流程和逻辑" +weight: 10630 +--- + +Source-to-Image (S2I) 是一个将源代码构建成镜像的自动化工具。S2I 将源代码注入负责编译的镜像构建器 (Image Builder) 中,然后自动将编译后的代码打包成 Docker 镜像。 + +有关如何在 KubeSphere 中使用 S2I 的更多信息,请参考 [Source to Image:无需 Dockerfile 发布应用](../source-to-image/)。此外,您还可以参考代码仓库 [S2IOperator](https://github.com/kubesphere/s2ioperator#source-to-image-operator) 和 [S2IRun](https://github.com/kubesphere/s2irun#s2irun) 查看更多详细信息。 + +## S2I 工作流程和逻辑 + +### 镜像构建器 + +对于 Python 和 Ruby 等解释型语言,程序的构建环境和运行时环境通常是相同的。例如,基于 Ruby 的镜像构建器通常包含 Bundler、Rake、Apache、GCC 以及其他构建运行时环境所需的安装包。构建的工作流程如下图所示: + +![s2i-builder](/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-builder.png) + +### S2I 工作原理 + +S2I 执行以下步骤: + +1. 根据镜像构建器运行容器,并将应用程序的源代码注入到指定目录中。 +2. 执行镜像构建器中的 `assemble` 脚本,通过安装依赖项以及将源代码转移到工作目录下,将源代码构建成可直接运行的应用程序。 +3. 将镜像构建器中提供的 `run` 脚本设置为启动容器的镜像入口点,然后提交新的镜像作为供用户使用的应用程序镜像。 + +S2I 流程图如下: + +![s2i-flow](/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-flow.png) + +### 运行时镜像 + +对于 Go、C、C++、Java 等编译型语言,编译时所需的依赖项会增加最终镜像的大小。为构建更轻量的镜像,S2I 实行分阶段构建,并从镜像中移除非必要的文件。镜像构建器完成构建后会导出制品,制品可能是 Jar 文件或二进制文件等可执行文件,然后会将制品注入运行时镜像 (Runtime Image) 用于执行。 + +构建的工作流程如下: + +![s2i-runtime-build](/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png) \ No newline at end of file diff --git a/content/zh/docs/project-user-guide/image-builder/s2i-templates.md b/content/zh/docs/project-user-guide/image-builder/s2i-templates.md new file mode 100644 index 000000000..7fd7d13f8 --- /dev/null +++ b/content/zh/docs/project-user-guide/image-builder/s2i-templates.md @@ -0,0 +1,328 @@ +--- +title: "Customize S2I Templates" +keywords: 'KubeSphere, Kubernetes, Docker, S2I, Source-to-Image' +description: 'Customize S2I templates and understand different template parameters.' +linkTitle: "Customize S2I Templates" +weight: 10640 +--- + +Once you have understood the workflow and logic of Source-to-Image (S2I), you can customize Image Builder templates (i.e. S2I/B2I templates) based on your projects to extend S2I capabilities. KubeSphere provides several common Image Builder templates, such as [Python](https://github.com/kubesphere/s2i-python-container/) and [Java](https://github.com/kubesphere/s2i-java-container/). + +This tutorial demonstrates how to create an Image Builder that contains an Nginx service. If you need to use Runtime Image in your project, refer to [this document](https://github.com/kubesphere/s2irun/blob/master/docs/runtime_image.md) for more information about how to create a Runtime Image. + +## Prerequisites + +S2I template customization can be divided into two parts. + +- Part 1: S2I Image Builder customization + - assemble (required): the `assemble` 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. + +{{< notice note >}} + +The Image Builder is compatible with that of OpenShift, and you can reuse it in KubeSphere. For more information about S2I Image Builder, refer to [S2IRun](https://github.com/kubesphere/s2irun/blob/master/docs/builder_image.md#s2i-builder-image-requirements). + +{{}} + +## Create an Image Builder + +### Step 1: Prepare S2I directory + +1. [S2I command line tool](https://github.com/openshift/source-to-image/releases) provides an easy-to-use command to initialize a base directory structure required by the Builder. Run the following commands to install S2I CLI. + + ```bash + $ wget https://github.com/openshift/source-to-image/releases/download/v1.1.14/source-to-image-v1.1.14-874754de-linux-386.tar.gz + $ tar -xvf source-to-image-v1.1.14-874754de-linux-386.tar.gz + $ ls + s2i source-to-image-v1.1.14-874754de-linux-386.tar.gz sti + $ cp s2i /usr/local/bin + ``` + +2. This tutorial uses `nginx-centos7` as the name of the Image Builder. Run the `s2i create` command to initialize the base directory structure. + + ```bash + 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. + +Modify the Dockerfile as follows to define the Image Builder. + +#### Dockerfile + +``` +# nginx-centos7 +FROM kubespheredev/s2i-base-centos7:1 + +# Here you can specify the maintainer for the image that you're building +LABEL maintainer="Runze Xia " + +# Define the current version of the application +ENV NGINX_VERSION=1.6.3 + +# Set the labels that are used for KubeSphere to describe the Image Builder. +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 the S2I scripts to /usr/libexec/s2i in the Image Builder +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"] +``` + +{{< notice 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 [S2I Scripts](https://github.com/kubesphere/s2irun/blob/master/docs/builder_image.md#s2i-scripts). + +{{}} + +### Step 3: Create S2I Scripts + +1. Create an `assemble` script as follows to copy configuration file and static contents to the target container. + + ```bash + #!/bin/bash -e + + if [[ "$1" == "-h" ]]; then + exec /usr/libexec/s2i/usage + fi + + echo "---> Building and installing application from source..." + if [ -f /tmp/src/nginx.conf ]; then + mv /tmp/src/nginx.conf /etc/nginx/nginx.conf + fi + + if [ "$(ls -A /tmp/src)" ]; then + mv /tmp/src/* /usr/share/nginx/html/ + fi + ``` + + {{< notice 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. + + ```bash + #!/bin/bash -e + + exec /usr/sbin/nginx -g "daemon off;" + ``` + + {{< notice 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. + + ```bash + #!/bin/bash -e + cat < 48f8574c05df + Step 2/17 : LABEL maintainer="Runze Xia " + ---> Using cache + ---> d60ebf231518 + Step 3/17 : ENV NGINX_VERSION=1.6.3 + ---> Using cache + ---> 5bd34674d1eb + Step 4/17 : 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" + ---> Using cache + ---> c837ad649086 + Step 5/17 : RUN yum install -y epel-release && yum install -y --setopt=tsflags=nodocs nginx && yum clean all + ---> Running in d2c8fe644415 + + ………… + ………… + ………… + + Step 17/17 : CMD ["/usr/libexec/s2i/usage"] + ---> Running in c24819f6be27 + Removing intermediate container c24819f6be27 + ---> c147c86f2cb8 + Successfully built c147c86f2cb8 + Successfully tagged kubespheredev/nginx-centos7-s2ibuilder-sample:latest + ``` + +3. With the Image Builder created, run the following command to create an application image. + + ```bash + $ s2i build ./test/test-app kubespheredev/nginx-centos7-s2ibuilder-sample:latest sample-app + ---> Building and installing application from source... + Build completed successfully + ``` + + {{< notice 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. + + ```bash + docker run -p 8080:8080 sample-app + ``` + + You can access the Nginx application at `http://localhost:8080`. + + ![access-nginx](/images/docs/project-user-guide/image-builder/s2i-templates/access-nginx.png) + +### Step 5: Push image and create S2I template + +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 + +```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 customized image) + version: 0.0.1 # Builder template version + description: "This is a S2I builder template for Nginx builds whose result can be run directly without any further application server.." # Builder template description +``` + +### Step 6: Use S2I template on KubeSphere + +1. Run the following command to submit the S2I template created above to KubeSphere. + + ```bash + $ kubectl apply -f s2ibuildertemplate.yaml + s2ibuildertemplate.devops.kubesphere.io/nginx created + ``` + +2. You can find the customized S2I template available when you create a S2I build on KubeSphere. + + ![template-available](/images/docs/project-user-guide/image-builder/s2i-templates/template-available.png) + +## S2I Template Parameters Definition + +Refer to the following detailed descriptions of S2I template labels passed as parameters to frontend classifications. + +| Label Name | Option | Definition | +| ------------------------------------- | -------------------- | ------------------------------------------------------------ | +| builder-type.kubesphere.io/s2i: "s2i" | "s2i" | The type of this template is S2I, which builds images based on application source code. | +| builder-type.kubesphere.io/b2i | "b2i" | The type of this template is B2I, which builds images based on binary files or other artifacts. | +| binary-type.kubesphere.io | "jar","war","binary" | This type is complementary to the type of B2I and will be required when B2I is selected. For example, select the type of "jar" when a JAR package is provided. In KubeSphere v2.1.1 and later, it is also allowed to customize B2I template. | + +Refer to the following detailed descriptions of S2I template parameters. The required parameters are marked with an asterisk. + +| Parameter | Type | Definition | +| ------------------------------------------ | -------- | ------------------------------------------------------------ | +| *containerInfo | []struct | The information about Image Builder. | +| *containerInfo.builderImage | string | S2I Image Builder, such as kubesphere/java-8-centos7:v2.1.0. | +| containerInfo.runtimeImage | string | S2I Runtime Image, such as kubesphere/java-8-runtime:v2.1.0. | +| containerInfo.buildVolumes | []string | The information about mounted volume. The format is "volume_name:mount_path", such as ["s2i_java_cache:/tmp/artifacts","test_cache:test_path"]. | +| containerInfo.runtimeArtifacts | []struct | The list of original path and target path for the output artifact; only add it for phased building. | +| containerInfo.runtimeArtifacts.source | string | The original path of artifact in Image Builder. | +| containerInfo.runtimeArtifacts.destination | string | The target path of artifact in Runtime Image. | +| containerInfo.runtimeArtifacts.keep | bool | Whether to keep the data in the output image. | +| *defaultBaseImage | string | The default Image Builder. | +| *codeFramework | string | The code framework type, such as Java, Ruby. | +| environment | []struct | The list of environment variables in the building process. | +| environment.key | string | The name of environment variables. | +| environment.type | string | The type of environment variable keys. | +| environment.description | string | The description of environment variables. | +| environment.optValues | []string | The list of parameters for environment variables. | +| environment.required | bool | Whether the environment variable is required to be set. | +| environment.defaultValue | string | The default value of environment variables. | +| environment.value | string | The value of environment variables. | +| iconPath | string | The application name. | +| version | string | The version of S2I template. | +| description | string | The description of the template's functions and usage. | + diff --git a/layouts/robots.txt b/layouts/robots.txt index 7ac65e231..aac6b3846 100644 --- a/layouts/robots.txt +++ b/layouts/robots.txt @@ -11,6 +11,7 @@ Disallow: /docs/project-administration/project-members/ Disallow: /docs/cluster-administration/storageclass/ Disallow: /docs/devops-user-guide/introduction/pipeline/ Disallow: /docs/devops-user-guide/introduction/credential/ +Disallow: /docs/project-user-guide/application-workloads/s2i-template/ {{ range .Pages }} {{ if .Params.disallow }} Disallow: {{ .RelPermalink }} diff --git a/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-builder.png b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-builder.png new file mode 100644 index 000000000..f6d6a6cd7 Binary files /dev/null and b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-builder.png differ diff --git a/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-flow.png b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-flow.png new file mode 100644 index 000000000..9415f752d Binary files /dev/null and b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-flow.png differ diff --git a/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png new file mode 100644 index 000000000..15ec3f9b2 Binary files /dev/null and b/static/images/docs/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png differ diff --git a/static/images/docs/project-user-guide/image-builder/s2i-templates/access-nginx.png b/static/images/docs/project-user-guide/image-builder/s2i-templates/access-nginx.png new file mode 100644 index 000000000..ec900371e Binary files /dev/null and b/static/images/docs/project-user-guide/image-builder/s2i-templates/access-nginx.png differ diff --git a/static/images/docs/project-user-guide/image-builder/s2i-templates/template-available.png b/static/images/docs/project-user-guide/image-builder/s2i-templates/template-available.png new file mode 100644 index 000000000..2edbc54d8 Binary files /dev/null and b/static/images/docs/project-user-guide/image-builder/s2i-templates/template-available.png differ diff --git a/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-builder.png b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-builder.png new file mode 100644 index 000000000..f6d6a6cd7 Binary files /dev/null and b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-builder.png differ diff --git a/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-flow.png b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-flow.png new file mode 100644 index 000000000..9415f752d Binary files /dev/null and b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-flow.png differ diff --git a/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png new file mode 100644 index 000000000..15ec3f9b2 Binary files /dev/null and b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-intro/s2i-runtime-build.png differ diff --git a/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/access-nginx.png b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/access-nginx.png new file mode 100644 index 000000000..ec900371e Binary files /dev/null and b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/access-nginx.png differ diff --git a/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/template-available.png b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/template-available.png new file mode 100644 index 000000000..2edbc54d8 Binary files /dev/null and b/static/images/docs/zh-cn/project-user-guide/image-builder/s2i-templates/template-available.png differ