Merge pull request #13000 from bmcelvee/osdocs-82-build-strategies

osdocs-82 Add build strategy modules

Author: bmcelvee

_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.