diff --git a/dev_guide/builds.adoc b/dev_guide/builds.adoc index 45b43e99404f..424a880c16d0 100644 --- a/dev_guide/builds.adoc +++ b/dev_guide/builds.adoc @@ -84,6 +84,33 @@ The `*ImageChange*` trigger creates a new build each time the Docker image speci <4> The `*strategy*` section describes the build strategy used to execute the build. You can specify `*Source*`, `*Docker*` and `*Custom*` strategies here. This specification uses the `*ruby-20-centos7*` Docker image that Source-To-Image will use for the application build. <5> After the Docker image is successfully built, it will be pushed into the repository described in the `*output*` section. +== Defining an incremental buildConfig +Source-To-Image (S2I) builds provide an option to perform incremental build, which means they will +reuse artifacts from previously built image. To create an incremental build one +needs to create a BuildConfig as previously explained, but with a slight modification +in strategy definition as presented below: + +[incremental.json] +---- +{ + "strategy": { + "type": "Source", + "sourceStrategy": { + "from": { + "kind": "ImageStreamTag", + "name": "incremental-image:latest" <1> + }, + "incremental": true <2> + } + } +} +---- + +<1> You need to specify here an image that supports incremental builds. Note: the S2I images provided by OpenShift do not implement artifact reuse, so setting incremental to true will have no effect on BuildConfigs using those builder images. +<2> This flag controls whether an incremental build is attempted. If the builder image does not support incremental builds, the build will still succeed but you will get a log message that the incremental build was not successful because of a missing `save-artifacts` script. + +NOTE: For information on how to create a builder image which supports incremental build see link:../creating_images/sti.html[creating images guide]. + == Starting a Build You can manually invoke a build using the following command: @@ -127,17 +154,17 @@ environment variable as part of the `*sourceStrategy*` in BuildConfig: ==== ---- - { - "sourceStrategy": { - ... - "env": [ - { - "Name": "BUILD_LOGLEVEL", - "Value": "2" <1> - } - ] - } - } +{ + "sourceStrategy": { + ... + "env": [ + { + "Name": "BUILD_LOGLEVEL", + "Value": "2" <1> + } + ] + } +} ---- <1> Adjust this value to the desired log level. @@ -164,15 +191,15 @@ is later built. The source code location definition is part of the ==== ---- - { - "source" : { - "type" : "Git", <1> - "git" : { <2> - "uri": "git://github.com/openshift/ruby-hello-world.git" - }, - "contextDir": "app/dir", <3> - }, - } +{ + "source" : { + "type" : "Git", <1> + "git" : { <2> + "uri": "git://github.com/openshift/ruby-hello-world.git" + }, + "contextDir": "app/dir", <3> + }, +} ---- <1> The `*type*` field describes what SCM is used to fetch your source code. @@ -189,8 +216,8 @@ default location (the root folder) using this field. [[configuring-the-source-environment]] == Source Environment -There are two ways to make environment variables available to the link:../architecture/core_objects/builds.html#source-build[Source] -build process and resulting image, Environment files and BuildConfig environment values. +There are two ways to make environment variables available to the link:../architecture/core_objects/builds.html#source-build[Source] +build process and resulting image, Environment files and BuildConfig environment values. === Environment files Source enables you to set environment values @@ -214,7 +241,7 @@ the running application itself. For example, you can add application to be started in `development` mode instead of `production`. === BuildConfig Environment -You can add environment variables to the SourceStrategy definition of the BuildConfig. +You can add environment variables to the SourceStrategy definition of the BuildConfig. Environment variables defined here will be visible during the *_assemble_* script execution and will be defined in the output image, making them also available to the *_run_* script and application code. @@ -244,12 +271,12 @@ JSON within the `*BuildConfig*`: ==== ---- - { - "type": "github", - "github": { - "secret": "secret101" - } - } +{ + "type": "github", + "github": { + "secret": "secret101" + } +} ---- ==== @@ -270,12 +297,12 @@ following is an example trigger definition JSON within the `*BuildConfig*`: ==== ---- - { - "type": "generic", - "generic": { - "secret": "secret101" - } - } +{ + "type": "generic", + "generic": { + "secret": "secret101" + } +} ---- ==== @@ -292,21 +319,21 @@ The endpoint can accept an optional payload with the following format: ---- { - type: 'git', - git: { - uri: '', - ref: '', - commit: '', - author: { - name: '', - email: '', - }, - committer: { - name: '', - email: '', - }, - message: '' - } + type: 'git', + git: { + uri: '', + ref: '', + commit: '', + author: { + name: '', + email: '', + }, + committer: { + name: '', + email: '', + }, + message: '' + } } ---- ==== @@ -339,13 +366,13 @@ trigger on: ==== ---- - { - "metadata":{ - "name": "ruby-20-centos7", - }, - "kind": "ImageStream", - "apiVersion": "v1beta1", - } +{ + "metadata":{ + "name": "ruby-20-centos7", + }, + "kind": "ImageStream", + "apiVersion": "v1beta1", +} ---- ==== + @@ -360,15 +387,17 @@ example: ==== ---- - "strategy": { - "type": "Source", - "sourceStrategy": { - "from": { - "kind": "ImageStreamTag", - "name": "ruby-20-centos7:latest" - }, - } +{ + "strategy": { + "type": "Source", + "sourceStrategy": { + "from": { + "kind": "ImageStreamTag", + "name": "ruby-20-centos7:latest" + }, } + } +} ---- ==== + @@ -380,10 +409,10 @@ ImageStream named `ruby-20-centos7` located within this namespace. ==== ---- - { - "type": "imageChange", - "imageChange": {} - } +{ + "type": "imageChange", + "imageChange": {} +} ---- ==== + @@ -396,15 +425,17 @@ for the build. For example, the resulting build will be: ==== ---- - "strategy": { - "type": "Source", - "sourceStrategy": { - "from": { - "kind": "DockerImage", - "name": "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid" - } +{ + "strategy": { + "type": "Source", + "sourceStrategy": { + "from": { + "kind": "DockerImage", + "name": "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid" } } + } +} ---- ==== @@ -412,9 +443,9 @@ This ensures that the triggered build uses the new image that was just pushed to the repository, and the build can be re-run anytime with exactly the same inputs. -In addition to setting the image field for all `*Strategy*` types, for custom builds, -the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked. If it does -not exist, then it is created with the immutable image reference. If it does exist +In addition to setting the image field for all `*Strategy*` types, for custom builds, +the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked. If it does +not exist, then it is created with the immutable image reference. If it does exist then it is updated with the immutable image reference. If a build is triggered due to a webhook trigger or manual request, @@ -475,13 +506,15 @@ that you created, which in the above example is `*dockerhub*`: ==== ---- -"parameters": { - "output": { - "to": { - "name": "private-image" - }, - "pushSecret":{ - "name":"dockerhub" +{ + "parameters": { + "output": { + "to": { + "name": "private-image" + }, + "pushSecret":{ + "name":"dockerhub" + } } } }