Skip to content

Commit d15854a

Browse files
authored
Merge pull request #14095 from bmcelvee/custom-builds-updates
Updates to build strategies and creating images
2 parents abee5ff + 265b4b0 commit d15854a

10 files changed

+109
-92
lines changed

builds/build-strategies.adoc

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
1-
// This assembly is included in the following assemblies:
2-
// * assembly/builds
3-
4-
//ifdef::context[:parent-context: {context}]
5-
61
[id="build-strategies"]
72
= Using build strategies
83
include::modules/common-attributes.adoc[]
@@ -12,34 +7,64 @@ toc::[]
127
The following sections define the primary supported build strategies, and how to
138
use them.
149

15-
// 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.
16-
17-
ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
1810
include::modules/builds-strategy-docker-build.adoc[leveloffset=+1]
11+
1912
include::modules/builds-strategy-docker-from-image.adoc[leveloffset=+2]
13+
2014
include::modules/builds-strategy-dockerfile-path.adoc[leveloffset=+2]
15+
2116
include::modules/builds-strategy-docker-environment-variables.adoc[leveloffset=+2]
17+
2218
include::modules/builds-strategy-docker-build-arguments.adoc[leveloffset=+2]
23-
endif::[]
19+
2420
include::modules/builds-strategy-s2i-build.adoc[leveloffset=+1]
21+
2522
include::modules/builds-strategy-s2i-incremental-builds.adoc[leveloffset=+2]
23+
2624
include::modules/builds-strategy-s2i-override-builder-image-scripts.adoc[leveloffset=+2]
25+
2726
include::modules/builds-strategy-s2i-environment-variables.adoc[leveloffset=+2]
27+
2828
include::modules/builds-strategy-s2i-environment-files.adoc[leveloffset=+3]
29+
2930
include::modules/builds-strategy-s2i-buildconfig-environment.adoc[leveloffset=+3]
31+
3032
include::modules/builds-strategy-s2i-ignore-source-files.adoc[leveloffset=+2]
33+
34+
include::modules/images-create-s2i.adoc[leveloffset=+2]
35+
36+
include::modules/images-create-s2i-build.adoc[leveloffset=+3]
37+
38+
include::modules/images-create-s2i-scripts.adoc[leveloffset=+3]
39+
3140
include::modules/builds-strategy-custom-build.adoc[leveloffset=+1]
41+
3242
include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2]
43+
3344
include::modules/builds-strategy-custom-secrets.adoc[leveloffset=+2]
45+
3446
include::modules/builds-strategy-custom-environment-variables.adoc[leveloffset=+2]
47+
48+
include::modules/images-custom.adoc[leveloffset=+2]
49+
3550
include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1]
51+
3652
include::modules/builds-understanding-openshift-pipeline.adoc[leveloffset=+2]
53+
3754
include::modules/builds-strategy-pipeline-providing-jenkinsfile.adoc[leveloffset=+2]
55+
3856
include::modules/builds-strategy-pipeline-environment-variables.adoc[leveloffset=+2]
57+
3958
include::modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc[leveloffset=+3]
59+
4060
include::modules/builds-tutorial-pipeline.adoc[leveloffset=+2]
41-
include::modules/builds-strategy-force-pull-procedure.adoc[leveloffset=+1]
42-
include::modules/builds-strategy-docker-force-pull-example.adoc[leveloffset=+2]
43-
include::modules/builds-strategy-s2i-force-pull-example.adoc[leveloffset=+2]
61+
62+
//include::modules/builds-strategy-force-pull-procedure.adoc[leveloffset=+1]
63+
64+
//include::modules/builds-strategy-docker-force-pull-example.adoc[leveloffset=+2]
65+
66+
//include::modules/builds-strategy-s2i-force-pull-example.adoc[leveloffset=+2]
67+
4468
include::modules/builds-strategy-secrets-web-console.adoc[leveloffset=+1]
69+
4570
include::modules/builds-strategy-enable-pulling-pushing.adoc[leveloffset=+1]
Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// Module included in the following assemblies:
22
//
3-
// <List assemblies here, each on a new line>
3+
// * assembly/builds/build-strategies.adoc
44

55
[id="build-strategy-custom-build-{context}"]
66
= Custom build
@@ -15,9 +15,3 @@ build process logic, for example for building RPMs or base images.
1515
Custom builds run with a very high level of privilege and are not available to
1616
users by default. Only users who can be trusted with cluster administration
1717
permissions should be granted access to run custom builds.
18-
19-
.Additional resources
20-
21-
* See xref:../builds/securing-builds-by-strategy.adoc#securing-builds-by-strategy[Securing
22-
builds by strategy] for instructions on how to grant access to the this build
23-
type to a user.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Module included in the following assemblies:
22
//* assembly/builds
3+
//* assembly/builds/build-strategies.adoc
34

45
[id="builds-strategy-custom-environment-variables-{context}"]
56
= Using environment variables for custom builds

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Module included in the following assemblies:
2-
//* assembly/builds
2+
//* assembly/Builds
3+
//* assembly/builds/build-strategies.adoc
34

45
[id="builds-strategy-custom-from-image-{context}"]
56
= Using FROM image for custom builds

modules/builds-strategy-custom-secrets.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Module included in the following assemblies:
22
//* assembly/builds
3+
//* assembly/builds/build-strategies.adoc
34

45
[id="builds-strategy-custom-secrets-{context}"]
56
= Using secrets in custom builds

modules/images-create-s2i-build.adoc

Lines changed: 18 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,39 @@
11
// Module included in the following assemblies:
22
//* assembly/openshift_images
3-
4-
// This module can be included from assemblies using the following include statement:
5-
// include::<path>/images-create-guide-openshift.adoc[leveloffset=+1]
3+
//* assembly/builds/build-strategies.adoc
64

75
[id="images-create-s2i-build-{context}"]
8-
96
= Understanding the s2i build process
7+
108
The build process consists of the following three fundamental elements, which
119
are combined into a final container image:
1210

13-
- sources
14-
- S2I scripts
15-
- builder image
11+
* sources
12+
* S2I scripts
13+
* builder image
1614

1715
During the build process, S2I must place sources and scripts inside the builder
18-
image. To do so, S2I creates a *_tar_* file that contains the sources and
16+
image. To do so, S2I creates a `tar` file that contains the sources and
1917
scripts, then streams that file into the builder image. Before executing the
20-
*_assemble_* script, S2I untars that file and places its contents into the
21-
location specified by the `*io.openshift.s2i.destination*`
18+
`assemble` script, S2I un-tars that file and places its contents into the
19+
location specified by the `io.openshift.s2i.destination`
2220
label from the builder image, with the default location being the
23-
*_/tmp_* directory.
21+
`/tmp` directory.
2422

25-
For this process to happen, your image must supply the *tar* archiving
26-
utility (the `tar` command available in `*$PATH*`) and the command line
27-
interpreter (the `/bin/sh` command); this allows your image to use the fastest
28-
possible build path. If the `tar` or `/bin/sh` command is not available, the
29-
`s2i build` process is forced to automatically perform an additional container build
30-
to put both the sources and the scripts inside the image, and only then run the
31-
usual build.
23+
For this process to happen, your image must supply the `tar` archiving utility
24+
(the `tar` command available in `$PATH`) and the command line interpreter (the
25+
`/bin/sh` command); this allows your image to use the fastest possible build
26+
path. If the `tar` or `/bin/sh` command is not available, the `s2i build`
27+
process is forced to automatically perform an additional container build to put
28+
both the sources and the scripts inside the image, and only then run the usual
29+
build.
3230

3331
See the following diagram for the basic S2I build workflow:
3432

3533
.Build Workflow
3634
image::s2i-flow.png[S2I workflow]
3735

38-
Run build's responsibility is to untar the sources, scripts and artifacts
39-
(if such exist) and invoke the `assemble` script. If this is the second run
36+
Run build's responsibility is to un-tar the sources, scripts and artifacts
37+
(if such exist) and invoke the `assemble` script. If this is the second run
4038
(after catching `tar` or `/bin/sh` not found error) it is responsible only
4139
for invoking `assemble` script, since both scripts and sources are already there.

modules/images-create-s2i-scripts.adoc

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// Module included in the following assemblies:
22
//* assembly/openshift_images
3-
// This module can be included from assemblies using the following include statement:
43
// include::<path>/images-create-s2i-scripts.adoc[leveloffset=+1]
4+
//* assembly/builds/build-strategies.adoc
55

66
[id="images-create-s2i-scripts-{context}"]
77
= Writing s2i scripts
@@ -18,9 +18,9 @@ each build in the following order:
1818
Both the `io.openshift.s2i.scripts-url` label specified in the image and the
1919
script specified in a BuildConfig can take one of the following forms:
2020

21-
- `image:///path_to_scripts_dir` - absolute path inside the image to a directory where the S2I scripts are located
22-
- `$$file:///path_to_scripts_dir$$` - relative or absolute path to a directory on the host where the S2I scripts are located
23-
- `http(s)://path_to_scripts_dir` - URL to a directory where the S2I scripts are located
21+
* `image:///path_to_scripts_dir` - absolute path inside the image to a directory where the S2I scripts are located
22+
* `$$file:///path_to_scripts_dir$$` - relative or absolute path to a directory on the host where the S2I scripts are located
23+
* `http(s)://path_to_scripts_dir` - URL to a directory where the S2I scripts are located
2424

2525
.S2I Scripts
2626
[cols="3a,8a",options="header"]
@@ -80,9 +80,9 @@ for more information.
8080

8181
The following example S2I scripts are written in Bash. Each
8282
example assumes its tar
83-
contents are unpacked into the *_/tmp/s2i_* directory.
83+
contents are unpacked into the `/tmp/s2i` directory.
8484

85-
.*_assemble_* script:
85+
.`assemble` script:
8686
====
8787
8888
----
@@ -106,7 +106,7 @@ popd
106106
----
107107
====
108108

109-
.*_run_* script:
109+
.`run` script:
110110
====
111111
112112
----
@@ -133,7 +133,7 @@ popd
133133
----
134134
====
135135

136-
.*_usage_* script:
136+
.`usage` script:
137137
====
138138
139139
----
@@ -147,15 +147,14 @@ EOF
147147
----
148148
====
149149

150-
[id="using-images-with-onbuild-instructions-{context}"]
151-
150+
////
152151
== Using Images with ONBUILD Instructions
153152
The `ONBUILD` instructions can be found in many official container images. For
154153
example:
155154
156-
- Ruby
157-
- Node.js
158-
- Python
155+
* Ruby
156+
* Node.js
157+
* Python
159158
160159
See the link:https://docs.docker.com/engine/reference/builder/#onbuild[Docker
161160
documentation] for more information on `ONBUILD`.
@@ -175,4 +174,4 @@ prerequisites.
175174
.Additional resources
176175
177176
* link:https://blog.openshift.com/create-s2i-builder-image/[S2I Image Creation Tutorial]
178-
* link:https://github.com/openshift/source-to-image[S2I Project Repository]
177+
////

modules/images-create-s2i.adoc

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,15 @@
11
// Module included in the following assemblies:
22
//* assembly/openshift_images
3-
4-
// This module can be included from assemblies using the following include statement:
5-
// include::<path>/images-create-s2i.adoc[leveloffset=+1]
3+
//* assembly/builds/build-strategies.adoc
64

75
[id="images-create-s2i-{context}"]
8-
96
= Creating images from source code with s2i
10-
Source-to-Image
11-
(S2I) is a framework that makes it easy to write images that take application
12-
source code as an input and produce a new image that runs the assembled
13-
application as output.
147

15-
The main advantage of using S2I for building reproducible container images is the
16-
ease of use for developers. As a builder image author, you must understand two
17-
basic concepts in order for your images to provide the best possible S2I performance:
18-
the build process and S2I scripts.
8+
Source-to-Image (S2I) is a framework that makes it easy to write images that
9+
take application source code as an input and produce a new image that runs the
10+
assembled application as output.
11+
12+
The main advantage of using S2I for building reproducible container images is
13+
the ease of use for developers. As a builder image author, you must understand
14+
two basic concepts in order for your images to provide the best possible S2I
15+
performance: the build process and S2I scripts.

modules/images-custom.adoc

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
// Module included in the following assemblies:
22
//* assembly/openshift_images
3+
//* assembly/builds/build-strategies.adoc
34

45
[id="images-custom-{context}"]
56
= Using custom builder images
67

78
By allowing you to define a specific builder image responsible for the entire
8-
build process, {product-title}'s
9-
Custom build strategy was
10-
designed to fill a gap created with the increased popularity of creating container
11-
images. When there is a requirement for a build to still produce individual
12-
artifacts (packages, JARs, WARs, installable ZIPs, and base images, for
13-
example), a _Custom builder image_ using the Custom build strategy is the
14-
perfect match to fill that gap.
9+
build process, {product-title}'s Custom build strategy was designed to fill a
10+
gap created with the increased popularity of creating container images. When
11+
there is a requirement for a build to still produce individual artifacts
12+
(packages, JARs, WARs, installable ZIPs, and base images, for example), a
13+
_Custom builder image_ using the Custom build strategy is the perfect match to
14+
fill that gap.
1515

1616
A Custom builder image is a plain container image embedded with build process
1717
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
2323
how to create a Custom builder image that will be capable of building desired
2424
objects.
2525

26-
[id="custom-builder-image-{context}"]
2726
== Custom builder image
2827

2928
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:
3534

3635
|Variable Name |Description
3736

38-
|`*BUILD*`
39-
|The entire serialized JSON of the `*Build*` object definition. If you need to
37+
|`BUILD`
38+
|The entire serialized JSON of the `Build` object definition. If you need to
4039
use a specific API version for serialization, you can set the
41-
`*buildAPIVersion*` parameter in the custom strategy
40+
`buildAPIVersion` parameter in the custom strategy
4241
specification of the build configuration.
4342

44-
|`*SOURCE_REPOSITORY*`
43+
|`SOURCE_REPOSITORY`
4544
|The URL of a Git repository with source to be built.
4645

47-
|`*SOURCE_URI*`
48-
|Uses the same value as `*SOURCE_REPOSITORY*`. Either can be used.
46+
|`SOURCE_URI`
47+
|Uses the same value as `SOURCE_REPOSITORY`. Either can be used.
4948

50-
|`*SOURCE_CONTEXT_DIR*`
49+
|`SOURCE_CONTEXT_DIR`
5150
|Specifies the subdirectory of the Git repository to be used when building. Only
5251
present if defined.
5352

54-
|`*SOURCE_REF*`
53+
|`SOURCE_REF`
5554
|The Git reference to be built.
5655

57-
|`*ORIGIN_VERSION*`
56+
|`ORIGIN_VERSION`
5857
|The version of the {product-title} master that created this build object.
5958

60-
|`*OUTPUT_REGISTRY*`
59+
|`OUTPUT_REGISTRY`
6160
|The container image registry to push the image to.
6261

63-
|`*OUTPUT_IMAGE*`
62+
|`OUTPUT_IMAGE`
6463
|The container image tag name for the image being built.
6564

66-
|`*PUSH_DOCKERCFG_PATH*`
65+
|`PUSH_DOCKERCFG_PATH`
6766
|The path to the container registry credentials for running a `podman push` or `docker push` operation.
6867

6968
|===
7069

71-
[id="custom-builder-workflow-{context}"]
7270
== Custom builder workflow
7371

7472
Although custom builder image authors have great flexibility in defining the
7573
build process, your builder image must still adhere to the following required
7674
steps necessary for seamlessly running a build inside of {product-title}:
7775

78-
. The `*Build*` object definition contains all the necessary information about input parameters for the build.
76+
. The `Build` object definition contains all the necessary information about input parameters for the build.
7977
. Run the build process.
8078
. 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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,11 @@ include::modules/images-create-guidelines.adoc[leveloffset=+1]
2929
include::modules/images-create-guide-general.adoc[leveloffset=+2]
3030
include::modules/images-create-guide-openshift.adoc[leveloffset=+2]
3131
include::modules/images-create-metadata.adoc[leveloffset=+1]
32-
include::modules/images-create-s2i.adoc[leveloffset=+1]
33-
include::modules/images-create-s2i-build.adoc[leveloffset=+2]
34-
include::modules/images-create-s2i-scripts.adoc[leveloffset=+2]
32+
33+
34+
35+
//Testing may need to move
3536
include::modules/images-test-s2i.adoc[leveloffset=+1]
36-
include::modules/images-custom.adoc[leveloffset=+1]
37+
38+
39+
//Section - use openshift to build images - link to build strategies

0 commit comments

Comments
 (0)