Updates to build strategies and creating images

builds/build-strategies.adoc

@@ -1,8 +1,3 @@
-// This assembly is included in the following assemblies:
-// * assembly/builds
-
-//ifdef::context[:parent-context: {context}]
-
 [id="build-strategies"]
 = Using build strategies
 include::modules/common-attributes.adoc[]
@@ -12,34 +7,64 @@ 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-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/images-create-s2i.adoc[leveloffset=+2]
+
+include::modules/images-create-s2i-build.adoc[leveloffset=+3]
+
+include::modules/images-create-s2i-scripts.adoc[leveloffset=+3]
+
 include::modules/builds-strategy-custom-build.adoc[leveloffset=+1]
+
 include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2]
+
 include::modules/builds-strategy-custom-secrets.adoc[leveloffset=+2]
+
 include::modules/builds-strategy-custom-environment-variables.adoc[leveloffset=+2]
+
+include::modules/images-custom.adoc[leveloffset=+2]
+
 include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1]
+
 include::modules/builds-understanding-openshift-pipeline.adoc[leveloffset=+2]
+
 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-tutorial-pipeline.adoc[leveloffset=+2]
-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-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-strategy-custom-build.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// <List assemblies here, each on a new line>
+// * assembly/builds/build-strategies.adoc
 
 [id="build-strategy-custom-build-{context}"]
 = Custom build
@@ -15,9 +15,3 @@ build process logic, for example for building RPMs or base images.
 Custom builds run with a very high level of privilege and are not available to
 users by default. Only users who can be trusted with cluster administration
 permissions should be granted access to run custom builds.
-
-.Additional resources
-
-* See xref:../builds/securing-builds-by-strategy.adoc#securing-builds-by-strategy[Securing
-builds by strategy] for instructions on how to grant access to the this build
-type to a user.

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

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //* assembly/builds
+//* assembly/builds/build-strategies.adoc
 
 [id="builds-strategy-custom-environment-variables-{context}"]
 = Using environment variables for custom builds

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

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
-//* assembly/builds
+//* assembly/Builds
+//* assembly/builds/build-strategies.adoc
 
 [id="builds-strategy-custom-from-image-{context}"]
 = Using FROM image for custom builds

modules/builds-strategy-custom-secrets.adoc

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //* assembly/builds
+//* assembly/builds/build-strategies.adoc
 
 [id="builds-strategy-custom-secrets-{context}"]
 = Using secrets in custom builds

modules/images-create-s2i-build.adoc

@@ -1,41 +1,39 @@
 // Module included in the following assemblies:
 //* assembly/openshift_images
-
-// This module can be included from assemblies using the following include statement:
-// include::<path>/images-create-guide-openshift.adoc[leveloffset=+1]
+//* assembly/builds/build-strategies.adoc
 
 [id="images-create-s2i-build-{context}"]
-
 = Understanding the s2i build process
+
 The build process consists of the following three fundamental elements, which
 are combined into a final container image:
 
-- sources
-- S2I scripts
-- builder image
+* sources
+* S2I scripts
+* builder image
 
 During the build process, S2I must place sources and scripts inside the builder
-image. To do so, S2I creates a *_tar_* file that contains the sources and
+image. To do so, S2I creates a `tar` file that contains the sources and
 scripts, then streams that file into the builder image. Before executing the
-*_assemble_* script, S2I untars that file and places its contents into the
-location specified by the `*io.openshift.s2i.destination*`
+`assemble` script, S2I un-tars that file and places its contents into the
+location specified by the `io.openshift.s2i.destination`
 label from the builder image, with the default location being the
-*_/tmp_* directory.
+`/tmp` directory.
 
-For this process to happen, your image must supply the *tar* archiving
-utility (the `tar` command available in `*$PATH*`) and the command line
-interpreter (the `/bin/sh` command); this allows your image to use the fastest
-possible build path. If the `tar` or `/bin/sh` command is not available, the
-`s2i build` process is forced to automatically perform an additional container build
-to put both the sources and the scripts inside the image, and only then run the
-usual build.
+For this process to happen, your image must supply the `tar` archiving utility
+(the `tar` command available in `$PATH`) and the command line interpreter (the
+`/bin/sh` command); this allows your image to use the fastest possible build
+path. If the `tar` or `/bin/sh` command is not available, the `s2i build`
+process is forced to automatically perform an additional container build to put
+both the sources and the scripts inside the image, and only then run the usual
+build.
 
 See the following diagram for the basic S2I build workflow:
 
 .Build Workflow
 image::s2i-flow.png[S2I workflow]
 
-Run build's responsibility is to untar the sources, scripts and artifacts
-(if such exist) and invoke the `assemble` script.  If this is the second run
+Run build's responsibility is to un-tar the sources, scripts and artifacts
+(if such exist) and invoke the `assemble` script. If this is the second run
 (after catching `tar` or `/bin/sh` not found error) it is responsible only
 for invoking `assemble` script, since both scripts and sources are already there.

modules/images-create-s2i-scripts.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //* assembly/openshift_images
-// This module can be included from assemblies using the following include statement:
 // include::<path>/images-create-s2i-scripts.adoc[leveloffset=+1]
+//* assembly/builds/build-strategies.adoc
 
 [id="images-create-s2i-scripts-{context}"]
 = Writing s2i scripts
@@ -18,9 +18,9 @@ each build in the following order:
 Both the `io.openshift.s2i.scripts-url` label specified in the image and the
 script specified in a BuildConfig can take one of the following forms:
 
-- `image:///path_to_scripts_dir` - absolute path inside the image to a directory where the S2I scripts are located
-- `$$file:///path_to_scripts_dir$$` - relative or absolute path to a directory on the host where the S2I scripts are located
-- `http(s)://path_to_scripts_dir` - URL to a directory where the S2I scripts are located
+* `image:///path_to_scripts_dir` - absolute path inside the image to a directory where the S2I scripts are located
+* `$$file:///path_to_scripts_dir$$` - relative or absolute path to a directory on the host where the S2I scripts are located
+* `http(s)://path_to_scripts_dir` - URL to a directory where the S2I scripts are located
 
 .S2I Scripts
 [cols="3a,8a",options="header"]
@@ -80,9 +80,9 @@ for more information.
 
 The following example S2I scripts are written in Bash. Each
 example assumes its tar
-contents are unpacked into the *_/tmp/s2i_* directory.
+contents are unpacked into the `/tmp/s2i` directory.
 
-.*_assemble_* script:
+.`assemble` script:
 ====
 
 ----
@@ -106,7 +106,7 @@ popd
 ----
 ====
 
-.*_run_* script:
+.`run` script:
 ====
 
 ----
@@ -133,7 +133,7 @@ popd
 ----
 ====
 
-.*_usage_* script:
+.`usage` script:
 ====
 
 ----
@@ -147,15 +147,14 @@ EOF
 ----
 ====
 
-[id="using-images-with-onbuild-instructions-{context}"]
-
+////
 == Using Images with ONBUILD Instructions
 The `ONBUILD` instructions can be found in many official container images. For
 example:
 
-- Ruby
-- Node.js
-- Python
+* Ruby
+* Node.js
+*  Python
 
 See the link:https://docs.docker.com/engine/reference/builder/#onbuild[Docker
 documentation] for more information on `ONBUILD`.
@@ -175,4 +174,4 @@ prerequisites.
 .Additional resources
 
 * link:https://blog.openshift.com/create-s2i-builder-image/[S2I Image Creation Tutorial]
-* link:https://github.com/openshift/source-to-image[S2I Project Repository]
+////

modules/images-create-s2i.adoc

@@ -1,18 +1,15 @@
 // Module included in the following assemblies:
 //* assembly/openshift_images
-
-// This module can be included from assemblies using the following include statement:
-// include::<path>/images-create-s2i.adoc[leveloffset=+1]
+//* assembly/builds/build-strategies.adoc
 
 [id="images-create-s2i-{context}"]
-
 = Creating images from source code with s2i
-Source-to-Image
-(S2I) is a framework that makes it easy to write images that take application
-source code as an input and produce a new image that runs the assembled
-application as output.
 
-The main advantage of using S2I for building reproducible container images is the
-ease of use for developers. As a builder image author, you must understand two
-basic concepts in order for your images to provide the best possible S2I performance:
-the build process and S2I scripts.
+Source-to-Image (S2I) is a framework that makes it easy to write images that
+take application source code as an input and produce a new image that runs the
+assembled application as output.
+
+The main advantage of using S2I for building reproducible container images is
+the ease of use for developers. As a builder image author, you must understand
+two basic concepts in order for your images to provide the best possible S2I
+performance: the build process and S2I scripts.

modules/images-custom.adoc

@@ -1,17 +1,17 @@
 // Module included in the following assemblies:
 //* assembly/openshift_images
+//* assembly/builds/build-strategies.adoc
 
 [id="images-custom-{context}"]
 = Using custom builder images
 
 By allowing you to define a specific builder image responsible for the entire
-build process, {product-title}'s
-Custom build strategy was
-designed to fill a gap created with the increased popularity of creating container
-images. When there is a requirement for a build to still produce individual
-artifacts (packages, JARs, WARs, installable ZIPs, and base images, for
-example), a _Custom builder image_ using the Custom build strategy is the
-perfect match to fill that gap.
+build process, {product-title}'s Custom build strategy was designed to fill a
+gap created with the increased popularity of creating container images. When
+there is a requirement for a build to still produce individual artifacts
+(packages, JARs, WARs, installable ZIPs, and base images, for example), a
+_Custom builder image_ using the Custom build strategy is the perfect match to
+fill that gap.
 
 A Custom builder image is a plain container image embedded with build process
 logic, for example for building RPMs or base container images.
@@ -23,7 +23,6 @@ To fully leverage the benefits of the Custom build strategy, you must understand
 how to create a Custom builder image that will be capable of building desired
 objects.
 
-[id="custom-builder-image-{context}"]
 == Custom builder image
 
 Upon invocation, a custom builder image will receive the following environment
@@ -35,46 +34,45 @@ variables with the information needed to proceed with the build:
 
 |Variable Name |Description
 
-|`*BUILD*`
-|The entire serialized JSON of the `*Build*` object definition. If you need to
+|`BUILD`
+|The entire serialized JSON of the `Build` object definition. If you need to
 use a specific API version for serialization, you can set the
-`*buildAPIVersion*` parameter in the custom strategy
+`buildAPIVersion` parameter in the custom strategy
 specification of the build configuration.
 
-|`*SOURCE_REPOSITORY*`
+|`SOURCE_REPOSITORY`
 |The URL of a Git repository with source to be built.
 
-|`*SOURCE_URI*`
-|Uses the same value as `*SOURCE_REPOSITORY*`. Either can be used.
+|`SOURCE_URI`
+|Uses the same value as `SOURCE_REPOSITORY`. Either can be used.
 
-|`*SOURCE_CONTEXT_DIR*`
+|`SOURCE_CONTEXT_DIR`
 |Specifies the subdirectory of the Git repository to be used when building. Only
 present if defined.
 
-|`*SOURCE_REF*`
+|`SOURCE_REF`
 |The Git reference to be built.
 
-|`*ORIGIN_VERSION*`
+|`ORIGIN_VERSION`
 |The version of the {product-title} master that created this build object.
 
-|`*OUTPUT_REGISTRY*`
+|`OUTPUT_REGISTRY`
 |The container image registry to push the image to.
 
-|`*OUTPUT_IMAGE*`
+|`OUTPUT_IMAGE`
 |The container image tag name for the image being built.
 
-|`*PUSH_DOCKERCFG_PATH*`
+|`PUSH_DOCKERCFG_PATH`
 |The path to the container registry credentials for running a `podman push` or `docker push` operation.
 
 |===
 
-[id="custom-builder-workflow-{context}"]
 == Custom builder workflow
 
 Although custom builder image authors have great flexibility in defining the
 build process, your builder image must still adhere to the following required
 steps necessary for seamlessly running a build inside of {product-title}:
 
-. The `*Build*` object definition contains all the necessary information about input parameters for the build.
+. The `Build` object definition contains all the necessary information about input parameters for the build.
 . Run the build process.
 . If your build produces an image, push it to the build's output location if it is defined. Other output locations can be passed with environment variables.

openshift_images/create-images.adoc

@@ -29,8 +29,11 @@ include::modules/images-create-guidelines.adoc[leveloffset=+1]
 include::modules/images-create-guide-general.adoc[leveloffset=+2]
 include::modules/images-create-guide-openshift.adoc[leveloffset=+2]
 include::modules/images-create-metadata.adoc[leveloffset=+1]
-include::modules/images-create-s2i.adoc[leveloffset=+1]
-include::modules/images-create-s2i-build.adoc[leveloffset=+2]
-include::modules/images-create-s2i-scripts.adoc[leveloffset=+2]
+
+
+
+//Testing may need to move
 include::modules/images-test-s2i.adoc[leveloffset=+1]
-include::modules/images-custom.adoc[leveloffset=+1]
+
+
+//Section - use openshift to build images - link to build strategies