RHDEVDOCS-3000 Document: Build Resource Volume Mounts

cicd/builds/build-strategies.adoc

@@ -8,6 +8,8 @@ toc::[]
 The following sections define the primary supported build strategies, and how to
 use them.
 
+// Docker build strategy
+
 include::modules/builds-strategy-docker-build.adoc[leveloffset=+1]
 
 include::modules/builds-strategy-docker-from-image.adoc[leveloffset=+2]
@@ -20,6 +22,13 @@ include::modules/builds-strategy-docker-build-arguments.adoc[leveloffset=+2]
 
 include::modules/builds-strategy-docker-squash-layers.adoc[leveloffset=+2]
 
+:context: build-strategies-docker
+
+include::modules/builds-using-build-volumes.adoc[leveloffset=+2]
+
+
+// S2I build strategy
+
 include::modules/builds-strategy-s2i-build.adoc[leveloffset=+1]
 
 include::modules/builds-strategy-s2i-incremental-builds.adoc[leveloffset=+2]
@@ -40,6 +49,12 @@ include::modules/images-create-s2i-build.adoc[leveloffset=+3]
 
 include::modules/images-create-s2i-scripts.adoc[leveloffset=+3]
 
+:context: build-strategies-s2i
+
+include::modules/builds-using-build-volumes.adoc[leveloffset=+2]
+
+// Custom build strategy
+
 include::modules/builds-strategy-custom-build.adoc[leveloffset=+1]
 
 include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2]
@@ -50,6 +65,8 @@ include::modules/builds-strategy-custom-environment-variables.adoc[leveloffset=+
 
 include::modules/images-custom.adoc[leveloffset=+2]
 
+// Pipeline build strategy
+
 include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1]
 
 include::modules/builds-understanding-openshift-pipeline.adoc[leveloffset=+2]

modules/builds-adding-input-secrets-configmaps.adoc

@@ -1,11 +1,17 @@
 // Module included in the following assemblies:
 //
-// * builds/creating-build-inputs.adoc
+// * cicd/builds/creating-build-inputs.adoc
+// * cicd/builds/builds-using-build-volumes.adoc
+
+:_module-type: PROCEDURE
 
 [id="builds-adding-input-secrets-configmaps_{context}"]
 = Adding input secrets and config maps
 
-In some scenarios, build operations require credentials or other configuration data to access dependent resources, but it is undesirable for that information to be placed in source control. You can define input secrets and input config maps for this purpose.
+[role="_abstract"]
+To provide credentials and other configuration data to a build without placing them in source control, you can define input secrets and input config maps.
+
+In some scenarios, build operations require credentials or other configuration data to access dependent resources. To make that information available without placing it in source control, you can define input secrets and input config maps.
 
 .Procedure
 
@@ -20,16 +26,51 @@ $ oc create configmap settings-mvn \
 ----
 +
 This creates a new config map named `settings-mvn`, which contains the plain text content of the `settings.xml` file.
++
+[TIP]
+====
+You can alternatively apply the following YAML to create the config map:
+[source,yaml]
+----
+apiVersion: core/v1
+kind: ConfigMap
+metadata:
+  name: settings-mvn
+data:
+  settings.xml: |
+    <settings>
+    … # Insert maven settings here
+    </settings>
+----
+====
+
 
 . Create the `Secret` object, if it does not exist:
 +
 [source,terminal]
 ----
 $ oc create secret generic secret-mvn \
     --from-file=id_rsa=<path/to/.ssh/id_rsa>
+    --type=kubernetes.io/ssh-auth
 ----
 +
 This creates a new secret named `secret-mvn`, which contains the base64 encoded content of the `id_rsa` private key.
++
+[TIP]
+====
+You can alternatively apply the following YAML to create the input secret:
+[source,yaml]
+----
+apiVersion: core/v1
+kind: Secret
+metadata:
+  name: secret-mvn
+type: kubernetes.io/ssh-auth
+data:
+  ssh-privatekey: |
+    # Insert ssh private key, base64 encoded
+----
+====
 
 . Add the config map and secret to the `source` section in the existing
 `BuildConfig` object:

modules/builds-create-imagestreamtag.adoc

@@ -17,12 +17,53 @@ The benefit of using image stream tags this way is that doing so grants access t
 +
 [source,terminal]
 ----
-$ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest -n openshift
+$ oc tag --source=docker registry.redhat.io/ubi8/ubi:latest ubi:latest -n openshift
 ----
++
+[TIP]
+====
+You can alternatively apply the following YAML to create an `ImageStreamTag` in the `openshift` namespace:
+[source,yaml]
+----
+apiVersion: image.openshift.io/v1
+kind: ImageStream
+metadata:
+  name: ubi
+  namespace: openshift
+spec:
+  tags:
+  - from:
+      kind: DockerImage
+      name: registry.redhat.io/ubi8/ubi:latest
+    name: latest
+    referencePolicy:
+      type: Source
+----
+====
 
 * To create an `ImageStreamTag` in a single project, enter:
 +
 [source,terminal]
 ----
-$ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest
+$ oc tag --source=docker registry.redhat.io/ubi8/ubi:latest ubi:latest
+----
++
+[TIP]
+====
+You can alternatively apply the following YAML to create an `ImageStreamTag` in a single project:
+[source,yaml]
+----
+apiVersion: image.openshift.io/v1
+kind: ImageStream
+metadata:
+  name: ubi
+spec:
+  tags:
+  - from:
+      kind: DockerImage
+      name: registry.redhat.io/ubi8/ubi:latest
+    name: latest
+    referencePolicy:
+      type: Source
 ----
+====

modules/builds-docker-strategy.adoc

@@ -26,7 +26,9 @@ RUN chmod 755 /input_report.sh
 CMD ["/bin/sh", "-c", "/input_report.sh"]
 ----
 
-[NOTE]
+[IMPORTANT]
 ====
 Users normally remove their input secrets from the final application image so that the secrets are not present in the container running from that image. However, the secrets still exist in the image itself in the layer where they were added. This removal is part of the Dockerfile itself.
+
+To prevent the contents of input secrets and config maps from appearing in the build output container images and avoid this removal process altogether, xref:../../cicd/builds/build-strategies.html#builds-using-build-volumes_build-strategies-docker[use build volumes] in your Docker build strategy instead.
 ====

modules/builds-input-secrets-configmaps.adoc

@@ -5,6 +5,11 @@
 [id="builds-input-secrets-configmaps_{context}"]
 = Input secrets and config maps
 
+[IMPORTANT]
+====
+To prevent the contents of input secrets and config maps from appearing in build output container images, use build volumes in your xref:../../cicd/builds/build-strategies.html#builds-using-build-volumes_build-strategies-docker[Docker build] and xref:../../cicd/builds/build-strategies.html#builds-using-build-volumes_build-strategies-s2i[source-to-image build] strategies.
+====
+
 In some scenarios, build operations require credentials or other configuration data to access dependent resources, but it is undesirable for that information to be placed in source control. You can define input secrets and input config maps for this purpose.
 
 For example, when building a Java application with Maven, you can set up a private mirror of Maven Central or JCenter that is accessed by private keys. To download libraries from that private mirror, you have to supply the

modules/builds-source-input-satellite-config.adoc

@@ -33,15 +33,29 @@ Builds that use Red Hat Satellite to install content must provide appropriate co
 ----
 $ oc create configmap yum-repos-d --from-file /path/to/satellite.repo
 ----
-+
 
-. Add the Satellite repository configuration to the `BuildConfig`:
+. Add the Satellite repository configuration and entitlement key as a build volumes:
 +
 [source,yaml]
 ----
-source:
-    configMaps:
-    - configMap:
-        name: yum-repos-d
-      destinationDir: yum.repos.d
+strategy:
+  dockerStrategy:
+    from:
+      kind: ImageStreamTag
+      name: ubi:latest
+    volumes:
+    - name: yum-repos-d
+      mounts:
+      - destinationPath: /etc/yum.repos.d
+      source:
+        type: ConfigMap
+        configMap:
+          name: yum-repos-d
+    - name: etc-pki-entitlement
+      mounts:
+      - destinationPath: /etc/pki/entitlement
+      source:
+        type: Secret
+        secret:
+          secretName: etc-pki-entitlement
 ----

modules/builds-source-secrets-entitlements.adoc

@@ -21,13 +21,21 @@ $  oc create secret generic etc-pki-entitlement --from-file /path/to/entitlement
 > --from-file /path/to/entitlement/{ID}-key.pem ...
 ----
 
-. Add the secret as a build input in the build configuration:
+. Add the secret as a build volume in the build configuration’s Docker strategy:
 +
 [source,yaml]
 ----
-source:
-  secrets:
-  - secret:
-      name: etc-pki-entitlement
-    destinationDir: etc-pki-entitlement
+strategy:
+  dockerStrategy:
+    from:
+      kind: ImageStreamTag
+      name: ubi:latest
+    volumes:
+    - name: etc-pki-entitlement
+      mounts:
+      - destinationPath: /etc/pki/entitlement
+      source:
+        type: Secret
+        secret:
+          secretName: etc-pki-entitlement
 ----

modules/builds-strategy-docker-entitled-satellite.adoc

@@ -8,33 +8,15 @@ Docker strategy builds can use Red Hat Satellite repositories to install subscri
 
 .Prerequisites
 
-* The entitlement keys and Satellite repository configurations must be added as build inputs.
+* You have added the entitlement keys and Satellite repository configurations as build volumes.
 
 .Procedure
 
 Use the following as an example Dockerfile to install content with Satellite:
 
 [source,terminal]
 ----
-FROM registry.redhat.io/rhel7:latest
-USER root
-# Copy entitlements
-COPY ./etc-pki-entitlement /etc/pki/entitlement
-# Copy repository configuration
-COPY ./yum.repos.d /etc/yum.repos.d
-# Delete /etc/rhsm-host to use entitlements from the build container
-RUN sed -i".org" -e "s#^enabled=1#enabled=0#g" /etc/yum/pluginconf.d/subscription-manager.conf <1>
-#RUN cat /etc/yum/pluginconf.d/subscription-manager.conf
-RUN yum clean all
-#RUN yum-config-manager
-RUN rm /etc/rhsm-host && \
-    # yum repository info provided by Satellite
-    yum -y update && \
-    yum -y install <rpms> && \
-    # Remove entitlements
-    rm -rf /etc/pki/entitlement
-# OpenShift requires images to run as non-root by default
-USER 1001
-ENTRYPOINT ["/bin/bash"]
+FROM registry.redhat.io/ubi8/ubi:latest
+RUN dnf search kernel-devel --showduplicates && \
+        dnf install -y kernel-devel
 ----
-<1> If adding Satellite configurations to builds using `enabled=1` fails, add `RUN sed -i".org" -e "s#^enabled=1#enabled=0#g" /etc/yum/pluginconf.d/subscription-manager.conf` to the Dockerfile.

modules/builds-strategy-docker-entitled-subman.adoc

@@ -9,33 +9,15 @@ Docker strategy builds can use the Subscription Manager to install subscription
 
 .Prerequisites
 
-The entitlement keys, subscription manager configuration, and subscription manager certificate authority must be added as build inputs.
+The entitlement keys must be added as build strategy volumes.
 
 .Procedure
 
 Use the following as an example Dockerfile to install content with the Subscription Manager:
 
 [source,terminal]
 ----
-FROM registry.redhat.io/rhel7:latest
-USER root
-# Copy entitlements
-COPY ./etc-pki-entitlement /etc/pki/entitlement
-# Copy subscription manager configurations
-COPY ./rhsm-conf /etc/rhsm
-COPY ./rhsm-ca /etc/rhsm/ca
-# Delete /etc/rhsm-host to use entitlements from the build container
-RUN rm /etc/rhsm-host && \
-    # Initialize /etc/yum.repos.d/redhat.repo
-    # See https://access.redhat.com/solutions/1443553
-    yum repolist --disablerepo=* && \
-    subscription-manager repos --enable <enabled-repo> && \
-    yum -y update && \
-    yum -y install <rpms> && \
-    # Remove entitlements and Subscription Manager configs
-    rm -rf /etc/pki/entitlement && \
-    rm -rf /etc/rhsm
-# OpenShift requires images to run as non-root by default
-USER 1001
-ENTRYPOINT ["/bin/bash"]
+FROM registry.redhat.io/ubi8/ubi:latest
+RUN dnf search kernel-devel --showduplicates && \
+        dnf install -y kernel-devel
 ----

modules/builds-strategy-docker-squash-layers.adoc

@@ -2,7 +2,7 @@
 //* builds/running-entitled-builds.adoc
 
 [id="builds-strategy-docker-squash-layers_{context}"]
-= Squash layers with docker builds
+= Squashing layers with docker builds
 
 Docker builds normally create a layer representing each instruction in a Dockerfile. Setting the `imageOptimizationPolicy` to `SkipLayers` merges all instructions into a single layer on top of the base image.