osdocs-82 Add build strategy modules

_topic_map.yml

@@ -37,6 +37,8 @@ Topics:
   File: understanding-builds
 - Name: Creating build inputs
   File: creating-build-inputs
+- Name: Build strategies
+  File: build-strategies
 - Name: Performing basic builds
   File: basic-build-operations
 ---

builds/build-strategies.adoc

@@ -0,0 +1,45 @@
+// This assembly is included in the following assemblies:
+// * assembly/builds
+
+//ifdef::context[:parent-context: {context}]
+
+[id='build-strategies']
+= Build strategies
+include::modules/common-attributes.adoc[]
+:context: build-strategies
+toc::[]
+
+The following sections define the primary supported build strategies, and how to
+use them.
+
+// The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+
+ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
+include::modules/builds-strategy-docker-build.adoc[leveloffset=+1]
+include::modules/builds-strategy-docker-from-image.adoc[leveloffset=+2]
+include::modules/builds-strategy-dockerfile-path.adoc[leveloffset=+2]
+include::modules/builds-strategy-docker-no-cache.adoc[leveloffset=+2]
+include::modules/builds-strategy-docker-environment-variables.adoc[leveloffset=+2]
+include::modules/builds-strategy-docker-build-arguments.adoc[leveloffset=+2]
+endif::[]
+include::modules/builds-strategy-s2i-build.adoc[leveloffset=+1]
+include::modules/builds-strategy-s2i-incremental-builds.adoc[leveloffset=+2]
+include::modules/builds-strategy-s2i-override-builder-image-scripts.adoc[leveloffset=+2]
+include::modules/builds-strategy-s2i-environment-variables.adoc[leveloffset=+2]
+include::modules/builds-strategy-s2i-environment-files.adoc[leveloffset=+3]
+include::modules/builds-strategy-s2i-buildconfig-environment.adoc[leveloffset=+3]
+include::modules/builds-strategy-s2i-ignore-source-files.adoc[leveloffset=+2]
+include::modules/builds-strategy-custom-build.adoc[leveloffset=+1]
+include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2]
+include::modules/builds-strategy-custom-expose-docker-socket.adoc[leveloffset=+2]
+include::modules/builds-strategy-custom-secrets.adoc[leveloffset=+2]
+include::modules/builds-strategy-custom-environment-variables.adoc[leveloffset=+2]
+include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1]
+include::modules/builds-strategy-pipeline-providing-jenkinsfile.adoc[leveloffset=+2]
+include::modules/builds-strategy-pipeline-environment-variables.adoc[leveloffset=+2]
+include::modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc[leveloffset=+3]
+include::modules/builds-strategy-force-pull-procedure.adoc[leveloffset=+1]
+include::modules/builds-strategy-docker-force-pull-example.adoc[leveloffset=+2]
+include::modules/builds-strategy-s2i-force-pull-example.adoc[leveloffset=+2]
+include::modules/builds-strategy-secrets-web-console.adoc[leveloffset=+1]
+include::modules/builds-strategy-enable-pulling-pushing.adoc[leveloffset=+1]

modules/builds-custom-strategy.adoc

@@ -21,7 +21,7 @@ defined as described in Custom Strategy Options.
 
 //[NOTE]
 //====
-//Add module above? 
+//Add module above?
 //====
 
 There is no technical difference between existing strategy secrets and the input
@@ -31,3 +31,9 @@ differently, based on your build use case.
 The input secrets are always mounted into the
 *_/var/run/secrets/openshift.io/build_* directory or your builder can parse the
 `$BUILD` environment variable, which includes the full build object.
+
+
+//[NOTE]
+//====
+//{product-title} does not guarantee your node has a docker socket to mount.
+//====

modules/builds-strategy-custom-build.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+[id='build-strategy-custom-build-{context}']
+= Custom build
+
+The Custom build strategy allows developers to define a specific builder image
+responsible for the entire build process. Using your own builder image allows
+you to customize your build process.
+
+A Custom builder image is a plain Docker-formatted container image embedded with
+build process logic, for example for building RPMs or base images. The
+`openshift/origin-custom-docker-builder` image is available on the
+https://registry.hub.docker.com/u/openshift/origin-custom-docker-builder[Docker
+Hub] registry as an example implementation of a Custom builder image.

modules/builds-strategy-custom-environment-variables.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-custom-environment-variables-{context}']
+= Using environment variables for custom builds
+
+To make environment variables available to the Custom build
+process, you can add environment variables to the `customStrategy` definition
+of the `BuildConfig`.
+
+The environment variables defined there are passed to the pod that runs the
+custom build.
+
+.Procedure
+
+To define a custom HTTP proxy to be used during build:
+
+[source,yaml]
+----
+customStrategy:
+...
+  env:
+    - name: "HTTP_PROXY"
+      value: "http://myproxy.net:5187/"
+
+----
+
+ifdef::openshift-enterprise,openshift-origin[]
+Cluster administrators can also configure global build settings using Ansible.
+endif::[]
+
+You can also manage environment variables defined in the `BuildConfig` with the
+`oc set env` command.
+
+
+
+//[NOTE]
+//====
+// This module needs specific instructions and examples.
+// This is similar between Docker, S2I, and Custom.
+//====

modules/builds-strategy-custom-expose-docker-socket.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-custom-expose-docker-socket-{context}']
+= Exposing the Docker socket
+
+To allow the running of Docker commands and the building of container
+images from inside the container, the build container must be bound to an
+accessible socket.
+
+.Procedure
+
+Set the `exposeDockerSocket` option to *true*:
+
+[source,yaml]
+----
+strategy:
+  customStrategy:
+    exposeDockerSocket: true
+----

modules/builds-strategy-custom-from-image.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-custom-from-image-{context}']
+= Using FROM image for custom builds
+
+You can use the `customStrategy.from` section to indicate the image to use for the
+custom build
+
+.Procedure
+
+To set the `customStrategy.from` section:
+
+[source,yaml]
+----
+strategy:
+  customStrategy:
+    from:
+      kind: "DockerImage"
+      name: "openshift/sti-image-builder"
+----

modules/builds-strategy-custom-secrets.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-custom-secrets-{context}']
+= Using secrets in custom builds
+
+In addition to secrets for source and images that can be added to all build
+types, custom strategies allow adding an arbitrary list of secrets to the
+builder pod.
+
+.Procedure
+
+To mount each secret at a specific location:
+
+[source,yaml]
+----
+strategy:
+  customStrategy:
+    secrets:
+      - secretSource: <1>
+          name: "secret1"
+        mountPath: "/tmp/secret1" <2>
+      - secretSource:
+          name: "secret2"
+        mountPath: "/tmp/secret2"
+----
+<1> `secretSource` is a reference to a secret in the same namespace as the
+build.
+<2> `mountPath` is the path inside the custom builder where the secret should
+be mounted.

modules/builds-strategy-docker-build-arguments.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-docker-build-arguments-{context}']
+= Adding Docker build arguments
+
+You can set link:http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[Docker
+build arguments] using the `BuildArgs` array. The build
+arguments will be passed to Docker when a build is started.
+
+.Procedure
+
+To set Docker build arguments, add entries to the `BuildArgs` array, which is
+located in the `dockerStrategy` definition of the `BuildConfig`. For example:
+
+====
+[source,yaml]
+----
+dockerStrategy:
+...
+  buildArgs:
+    - name: "foo"
+      value: "bar"
+----
+====

modules/builds-strategy-docker-build.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+[id='builds-strategy-docker-build-{context}']
+= Docker build
+
+The Docker build strategy invokes the
+link:https://docs.docker.com/engine/reference/commandline/build/[docker build]
+command, and it therefore expects a repository with a *_Dockerfile_* and all
+required artifacts in it to produce a runnable image.

modules/builds-strategy-docker-environment-variables.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-docker-environment-variables-{context}']
+= Using Docker environment variables
+
+To make environment variables available to the Docker build
+process and resulting image, you can add environment variables to the
+`dockerStrategy` definition of the `BuildConfig`.
+
+The environment variables defined there are inserted as a single `ENV`
+Dockerfile instruction right after the `FROM` instruction, so that it can be
+referenced later on within the Dockerfile.
+
+.Procedure
+
+The variables are defined during build and stay in the output image, therefore
+they will be present in any container that runs that image as well.
+
+For example, defining a custom HTTP proxy to be used during build and runtime:
+
+[source,yaml]
+----
+dockerStrategy:
+...
+  env:
+    - name: "HTTP_PROXY"
+      value: "http://myproxy.net:5187/"
+----
+
+ifdef::openshift-enterprise,openshift-origin[]
+Cluster administrators can also configure global build settings using Ansible.
+endif::[]
+
+You can also manage environment variables defined in the `BuildConfig` with the
+`oc set env` command.

modules/builds-strategy-docker-force-pull-example.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-docker-force-pull-example-{context}']
+= Docker force pull flag example
+
+Set the following to use the `forcePull` flag with Docker:
+
+
+[source,yaml]
+----
+strategy:
+  dockerStrategy:
+    forcePull: true <1>
+----
+<1> This flag causes the local builder image to be ignored, and a fresh version
+to be pulled from the registry to which the image stream points. Setting
+`forcePull` to *false* results in the default behavior of honoring the image
+stored locally.

modules/builds-strategy-docker-from-image.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-docker-from-image-{context}']
+= Replacing Dockerfile FROM image
+
+You can replace the `FROM` instruction of the *_Dockerfile_* with the `from` of
+the `BuildConfig`.
+
+.Procedure
+
+To replace the `FROM` instruction of the *_Dockerfile_* with the `from` of
+the `BuildConfig`.
+
+[source,yaml]
+----
+strategy:
+  dockerStrategy:
+    from:
+      kind: "ImageStreamTag"
+      name: "debian:latest"
+----

modules/builds-strategy-docker-no-cache.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-docker-no-cache-{context}']
+= Using no cache with docker builds
+
+Docker builds normally reuse cached layers found on the host performing the
+build. Setting the `noCache` option to *true* forces the build to ignore
+cached layers and rerun all steps of the *_Dockerfile_*.
+
+.Procedure
+
+To set the `noCache` option to *true*: 
+
+[source,yaml]
+----
+strategy:
+  dockerStrategy:
+    noCache: true
+----

modules/builds-strategy-dockerfile-path.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-dockerfile-path-{context}']
+= Using Dockerfile path
+
+By default, Docker builds use a Dockerfile (named *_Dockerfile_*) located at the
+root of the context specified in the `BuildConfig.spec.source.contextDir`
+field.
+
+The `dockerfilePath` field allows the build to use a different path to
+locate your Dockerfile, relative to the `BuildConfig.spec.source.contextDir`
+field. It can be a different file name than the default
+*_Dockerfile_* (for example, *_MyDockerfile_*), or a path to a Dockerfile in a
+subdirectory (for example, *_dockerfiles/app1/Dockerfile_*).
+
+.Procedure
+
+To use the `dockerfilePath` field for the build to use a different path to
+locate your Dockerfile, set:
+
+[source,yaml]
+----
+strategy:
+  dockerStrategy:
+    dockerfilePath: dockerfiles/app1/Dockerfile
+----

modules/builds-strategy-enable-pulling-pushing.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-enable-pulling-pushing-{context}']
+= Enabling pulling and pushing
+
+You can enable pulling to a private registry by setting the `Pull Secret` and
+pushing by setting the `Push Secret` in the build configuration.
+
+.Procedure
+
+To enable pulling to a private registry:
+
+* Set the `Pull Secret` in the build configuration.
+
+To enable pushing:
+
+ * Set the `Push Secret` in the build configuration.
+
+
+//[NOTE]
+//====
+// This module needs specific instructions and examples. And needs to be used for Docker and S2I.
+//====

modules/builds-strategy-force-pull-procedure.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-force-pull-procedure-{context}']
+= Using the force pull flag
+
+By default, if the builder image specified in the build configuration is
+available locally on the node, that image will be used. However, you can use
+the `forcepull` flag to override the local image and refresh it from the registry.
+
+.Procedure
+
+To override the local image and refresh it from the registry to which the image
+stream points, create a `BuildConfig` with the `forcePull` flag set to *true*.

modules/builds-strategy-pipeline-build.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-pipeline-build-{context}']
+= Pipeline build
+
+The Pipeline build strategy allows developers to define a _Jenkins pipeline_
+for execution by the Jenkins pipeline plugin.
+The build can be started, monitored, and managed by
+{product-title} in the same way as any other build type.
+
+Pipeline workflows are defined in a Jenkinsfile,
+either embedded directly in the build configuration,
+or supplied in a Git repository and referenced by the build configuration.
+
+The first time a project defines a build configuration using a Pipeline
+strategy, {product-title} instantiates a Jenkins server to execute the
+pipeline.  Subsequent Pipeline build configurations in the project share this
+Jenkins server.
+
+.Additional resources
+
+* For more information about Jenkins Pipelines, see the
+link:https://jenkins.io/doc/pipeline/[Jenkins documentation].
+* Pipeline build configurations require a Jenkins server to manage the
+pipeline execution. For more information on the Jenkins image provided with
+{product-title}, see OpenShift Pipeline, the Jenkins Image documentation, and
+the Pipeline build tutorial.

modules/builds-strategy-pipeline-environment-variables.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-pipeline-environment-variables-{context}']
+= Using environment variables for pipeline builds
+
+To make environment variables available to the Pipeline build process, you can
+add environment variables to the `jenkinsPipelineStrategy` definition of the
+`BuildConfig`.
+
+Once defined, the environment variables will be set as parameters for any
+Jenkins job associated with the `BuildConfig`
+
+.Procedure
+
+To define environment variables to be used during build:
+
+[source,yaml]
+----
+jenkinsPipelineStrategy:
+...
+  env:
+    - name: "FOO"
+      value: "BAR"
+
+----
+
+You can also manage environment variables defined in the `BuildConfig` with the
+`oc set env` command.
+
+
+
+//[NOTE]
+//====
+// This module needs specific instructions and examples.
+// This is similar between Docker, S2I, and Custom.
+//====

modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-pipeline-mapping-buildconfig-jenkins-{context}']
+= Mapping Between BuildConfig Environment Variables and Jenkins Job Parameters
+
+When a Jenkins job is created or updated based on changes to a Pipeline
+strategy `BuildConfig`, any environment variables in the `BuildConfig` are
+mapped to Jenkins job parameters definitions, where the default values for the
+Jenkins job parameters definitions are the current values of the associated
+environment variables.
+
+After the Jenkins job's initial creation, you can still add additional
+parameters to the job from the Jenkins console. The parameter names differ from
+the names of the environment variables in the `BuildConfig`. The parameters are
+honored when builds are started for those Jenkins jobs.
+
+How you start builds for the Jenkins job dictates how the parameters are set.
+
+* If you start with `oc start-build`, the values of the environment variables in the
+`BuildConfig` are the parameters set for the corresponding job instance. Any
+changes you make to the parameters' default values from the Jenkins console are
+ignored. The `BuildConfig` values take precedence.
+
+* If you start with `oc start-build -e`, the values for the environment variables
+specified in the `-e` option take precedence.
+** If you specify an environment variable not listed in the `BuildConfig`, they
+will be added as a Jenkins job parameter definitions.
+** Any changes you make from the Jenkins console to the parameters corresponding
+to the environment variables are ignored. The `BuildConfig` and what you specify
+with `oc start-build -e` takes precedence.
+
+* If you start the Jenkins job with the Jenkins console, then you can control the
+setting of the parameters with the Jenkins console as part of starting a build
+for the job.

modules/builds-strategy-pipeline-providing-jenkinsfile.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-pipeline-providing-jenkinsfile-{context}']
+= Providing the Jenkinsfile for pipeline builds
+
+You can provide the Jenkinsfile for pipeline builds.
+
+.Procedure
+
+To provide the Jenkinsfile, you can either:
+
+1. Embed the Jenkinsfile in the build configuration.
+2. Include in the build configuration a reference to the
+   Git repository that contains the Jenkinsfile.
+
+.Embedded Definition
+[source,yaml]
+----
+kind: "BuildConfig"
+apiVersion: "v1"
+metadata:
+  name: "sample-pipeline"
+spec:
+  strategy:
+    jenkinsPipelineStrategy:
+      jenkinsfile: |-
+        node('agent') {
+          stage 'build'
+          openshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true')
+          stage 'deploy'
+          openshiftDeploy(deploymentConfig: 'frontend')
+        }
+----
+
+.Reference to Git Repository
+[source,yaml]
+----
+kind: "BuildConfig"
+apiVersion: "v1"
+metadata:
+  name: "sample-pipeline"
+spec:
+  source:
+    git:
+      uri: "https://github.com/openshift/ruby-hello-world"
+  strategy:
+    jenkinsPipelineStrategy:
+      jenkinsfilePath: some/repo/dir/filename <1>
+----
+<1> The optional `jenkinsfilePath` field specifies the name of the
+    file to use, relative to the source `contextDir`.
+    If `contextDir` is omitted, it defaults to the root of the repository.
+    If `jenkinsfilePath` is omitted, it defaults to *_Jenkinsfile_*.

modules/builds-strategy-s2i-build.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='build-strategy-s2i-{context}']
+= Source-to-Image (S2I) build
+
+Source-to-Image (S2I) is a tool for building reproducible, Docker-formatted
+container images. It produces ready-to-run images by injecting application
+source into a container image and assembling a new image. The new image
+incorporates the base image (the builder) and built source and is ready to use
+with the `docker run` command. S2I supports incremental builds, which re-use
+previously downloaded dependencies, previously built artifacts, etc.
+
+The advantages of S2I include the following:
+
+[horizontal]
+Image flexibility:: S2I scripts can be written to inject
+application code into almost any existing Docker-formatted container image,
+taking advantage of the existing ecosystem. Note that, currently, S2I relies on
+`tar` to inject application source, so the image needs to be able to process
+tarred content.
+
+Speed:: With S2I, the assemble process can perform a large number of complex
+operations without creating a new layer at each step, resulting in a fast
+process. In addition, S2I scripts can be written to re-use artifacts stored in a
+previous version of the application image, rather than having to download or
+build them each time the build is run.
+
+Patchability:: S2I allows you to rebuild the application consistently if an
+underlying image needs a patch due to a security issue.
+
+Operational efficiency:: By restricting build operations instead of allowing
+arbitrary actions, as a *_Dockerfile_* would allow, the PaaS operator can avoid
+accidental or intentional abuses of the build system.
+
+Operational security:: Building an arbitrary *_Dockerfile_* exposes the host
+system to root privilege escalation. This can be exploited by a malicious user
+because the entire Docker build process is run as a user with Docker privileges.
+S2I restricts the operations performed as a root user and can run the scripts
+as a non-root user.
+
+User efficiency:: S2I prevents developers from performing arbitrary `yum
+install` type operations, which could slow down development iteration, during
+their application build.
+
+Ecosystem:: S2I encourages a shared ecosystem of images where you can leverage
+best practices for your applications.
+
+Reproducibility:: Produced images can include all inputs including specific versions
+of build tools and dependencies. This ensures that the image can be reproduced
+precisely.

modules/builds-strategy-s2i-buildconfig-environment.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-buildconfig-environment-{context}']
+= Using Source-to-Image (S2I) BuildConfig environment
+
+You can add environment variables to the `sourceStrategy` definition of the
+`BuildConfig`. The environment variables defined there are 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.
+
+.Procedure
+
+* For example, to disable assets compilation for your Rails application:
+
+[source,yaml]
+----
+sourceStrategy:
+...
+  env:
+    - name: "DISABLE_ASSET_COMPILATION"
+      value: "true"
+----
+
+.Additional resources
+
+* The Build environment section provides more advanced instructions.
+* You can also manage environment variables defined in the `BuildConfig` with the
+`oc set env` command.

modules/builds-strategy-s2i-environment-files.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-environment-files-{context}']
+= Using Source-to-Image (S2I) environment files
+
+Source build enables you to set environment values (one per line) inside your
+application, by specifying them in a *_.s2i/environment_* file in the source
+repository. The environment variables specified in this file are present during
+the build process and in the output image.
+
+If you provide a *_.s2i/environment_* file in your source repository, S2I reads
+this file during the build. This allows customization of the build behavior as
+the *_assemble_* script may use these variables.
+
+.Procedure
+
+For example, to disable assets compilation for your Rails
+application during the build:
+
+* Add `DISABLE_ASSET_COMPILATION=true` in the *_.s2i/environment_* file.
+
+In addition to builds, the specified environment variables are also available in
+the running application itself. For example, to cause the Rails
+application to start in `development` mode instead of `production`:
+
+* Add `RAILS_ENV=development` to the *_.s2i/environment_* file.
+
+.Additional resources
+
+* The complete list of supported environment variables is available in the using
+images section for each image.

modules/builds-strategy-s2i-environment-variables.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-environment-variables-{context}']
+= Source-to-Image (S2I) environment variables
+
+There are two ways to make environment variables available to the source build
+process and resulting image. Environment files and *BuildConfig* environment
+values. Variables provided will be present during the build process and in the
+output image.

modules/builds-strategy-s2i-force-pull-example.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-force-pull-example-{context}']
+= Source-to-Image (S2I) force pull flag example
+
+Set the following to use the `forcePull` flag with S2I:
+
+[source,yaml]
+----
+strategy:
+  sourceStrategy:
+    from:
+      kind: "ImageStreamTag"
+      name: "builder-image:latest" <1>
+    forcePull: true <2>
+----
+<1> The builder image being used, where the local version on the node may not be
+up to date with the version in the registry to which the image stream points.
+<2> This flag causes the local builder image to be ignored and a fresh version
+to be pulled from the registry to which the image stream points. Setting
+`forcePull` to *false* results in the default behavior of honoring the image
+stored locally.

modules/builds-strategy-s2i-ignore-source-files.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-ignore-source-files-{context}']
+= Ignoring Source-to-Image (S2I) source files
+
+Source to image supports a `.s2iignore` file, which contains a list of file
+patterns that should be ignored. Files in the build working directory, as
+provided by the various input sources, that match a pattern found in the
+`.s2iignore` file will not be made available to the `assemble` script.
+
+For more details on the format of the `.s2iignore` file, see the source-to-image
+documentation.
+
+
+//[NOTE]
+//====
+// This module needs specific instructions and examples.
+//====

modules/builds-strategy-s2i-incremental-builds.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//* assembly/build-strategies
+
+[id='builds-strategy-s2i-incremental-builds-{context}']
+= Performing Source-to-Image (S2I) incremental builds
+
+S2I can perform incremental builds, which means it reuses artifacts from
+previously-built images.
+
+.Procedure
+
+To create an incremental build, create a `BuildConfig` with the following
+modification to the strategy definition:
+
+[source,yaml]
+----
+strategy:
+  sourceStrategy:
+    from:
+      kind: "ImageStreamTag"
+      name: "incremental-image:latest" <1>
+    incremental: true <2>
+----
+<1> Specify an image that supports incremental builds. Consult the
+documentation of the builder image to determine if it supports this behavior.
+<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 stating the incremental build was not successful because
+of a missing *_save-artifacts_* script.
+
+.Additional resources
+
+* See S2I Requirements for information on how to create a builder image
+supporting incremental builds.

modules/builds-strategy-s2i-override-builder-image-scripts.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-s2i-override-builder-image-scripts-{context}']
+= Overriding Source-to-Image (S2I) builder image scripts
+
+You can override the *_assemble_*, *_run_*, and *_save-artifacts_*
+S2I scripts provided by the builder image.
+
+.Procedure
+
+To override the *_assemble_*, *_run_*, and *_save-artifacts_* S2I scripts
+provided by the builder image, either:
+
+1. Provide an *_assemble_*, *_run_*, or *_save-artifacts_* script in the
+*_.s2i/bin_* directory of your application source repository, or
+
+2. Provide a URL of a directory containing the scripts as part of the strategy
+definition. For example:
+
+[source,yaml]
+----
+strategy:
+  sourceStrategy:
+    from:
+      kind: "ImageStreamTag"
+      name: "builder-image:latest"
+    scripts: "http://somehost.com/scripts_directory" <1>
+----
+<1> This path will have *_run_*, *_assemble_*, and *_save-artifacts_* appended
+to it. If any or all scripts are found they will be used in place of the same
+named script(s) provided in the image.
+
+[NOTE]
+====
+Files located at the `scripts` URL take precedence over files located in
+*_.s2i/bin_* of the source repository.
+====

modules/builds-strategy-secrets-web-console.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//* assembly/builds
+
+[id='builds-strategy-secrets-web-console-{context}']
+= Adding secrets with web console
+
+You can add a secret to your build configuration so that it can access a private
+repository.
+
+.Procedure
+
+To add a secret to your build configuration so that it can access a private
+repository:
+
+. Create a new {product-title} project.
+
+. Create a secret that contains credentials for accessing a private source code
+repository.
+
+. Create a build configuration.
+
+. On the build configuration editor page or in the `create app from builder image`
+page of the web console, set the *Source Secret*.
+
+. Click the *Save* button.
+
+
+//[NOTE]
+//====
+// This module needs specific instructions and examples.
+// This is applicable for Docker, S2I, and Custom. 
+//====