Merge pull request #13876 from bmcelvee/osdocs-623-dockerless-nodes

osdocs-123-devexp-138 Document dockerless nodes

Author: bmcelvee

_topic_map.yml

@@ -160,12 +160,16 @@ Topics:
   File: managing-build-output
 - Name: Using build strategies
   File: build-strategies
+- Name: Adding a Docker socket to custom builds with Buildah
+  File: custom-builds-buildah
 - Name: Performing basic builds
   File: basic-build-operations
 - Name: Triggering and modifying builds
   File: triggering-builds-build-hooks
 - Name: Performing advanced builds
   File: advanced-build-operations
+- Name: Securing builds by strategy
+  File: securing-builds-by-strategy
 - Name: Troubleshooting builds
   File: troubleshooting-builds
 ---

builds/custom-builds-buildah.adoc

@@ -0,0 +1,34 @@
+[id='custom-builds-buildah']
+= Adding a Docker socket to custom builds with Buildah
+include::modules/common-attributes.adoc[]
+:context: custom-builds-buildah
+toc::[]
+
+
+With {product-title} 4.0, a Docker socket will not be present on the host
+nodes. This means the _mount docker socket_ option of a custom build is not
+guaranteed to provide an accessible Docker socket for use within a custom build
+image.
+
+If you need this capability in order to build and push images, add the Buildah
+tool your custom build image and use it to build and push the image within your
+custom build logic. The following is an example of how to run custom builds with
+Buildah.
+
+[NOTE]
+====
+Using the custom build strategy requires permissions that normal users do
+not have by default because it allows the user to execute arbitrary code inside
+a privileged container running on the cluster. This level of access can be used
+to compromise the cluster and therefore should be granted only to users who are
+trusted with administrative privileges on the cluster.
+====
+
+.Prerequisites
+
+* Review how to xref:../builds/securing-builds-by-strategy.adoc#securing-builds-by-strategy[grant custom build permissions].
+
+
+include::modules/builds-create-custom-build-artifacts.adoc[leveloffset=+1]
+include::modules/builds-build-custom-builder-image.adoc[leveloffset=+1]
+include::modules/builds-use-custom-builder-image.adoc[leveloffset=+1]

builds/securing-builds-by-strategy.adoc

@@ -0,0 +1,54 @@
+[id='securing-builds-by-strategy']
+= Securing builds by strategy
+include::modules/common-attributes.adoc[]
+:context: securing-builds-by-strategy
+toc::[]
+
+Builds in {product-title} are run in privileged containers. Depending on the
+build strategy used, this allows a user who can run builds to escalate their
+permissions on the cluster and host nodes. As a security measure, limit who can
+run builds and the strategy that is used for those builds. Custom builds are
+inherently less safe than Source builds, because they can execute any code
+within a privileged container, and are disabled by default. Grant Docker build
+permissions with caution, because a vulnerability in the Dockerfile processing
+logic could result in a privileges being granted on the host node.
+
+By default, all users that can create builds are granted permission to use the
+Docker and Source-to-Image (S2I) build strategies. Users with *cluster-admin*
+privileges can enable the Custom build strategy, as referenced in the
+restricting build strategies to a user globally section.
+
+You can control who can build and which build strategies they can use by using
+an authorization policy. Each build strategy has a corresponding build
+subresource. A user must have permission to create a build _and_ permission to
+create on the build strategy subresource in order to create builds using that
+strategy. Default roles are provided which grant the *create* permission on the
+build strategy subresource.
+
+.Build Strategy Subresources and Roles
+[options="header"]
+|===
+
+|Strategy |Subresource |Role
+
+|Docker
+|builds/docker
+|system:build-strategy-docker
+
+|Source-to-Image
+|builds/source
+|system:build-strategy-source
+
+|Custom
+|builds/custom
+|system:build-strategy-custom
+
+|JenkinsPipeline
+|builds/jenkinspipeline
+|system:build-strategy-jenkinspipeline
+
+|===
+
+include::modules/builds-disabling-build-strategy-globally.adoc[leveloffset=+1]
+include::modules/builds-restricting-build-strategy-globally.adoc[leveloffset=+1]
+include::modules/builds-restricting-build-strategy-to-user.adoc[leveloffset=+1]

modules/builds-build-custom-builder-image.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+// * builds/custom-builds-buildah.adoc
+
+
+[id='builds-build-custom-builder-image-{context}']
+= Build custom builder image
+
+You can use {product-title} to build and push custom builder images to use in
+a custom strategy.
+
+.Prerequisites
+
+* Define all the inputs that will go into creating your new custom builder image.
+
+.Procedure
+
+. Define a BuildConfig that will build your custom builder image:
++
+----
+$ oc new-build --binary --strategy=docker --name custom-builder-image
+----
+
+. From the directory in which you created your custom build image, run the build:
++
+----
+$ oc start-build custom-builder-image --from-dir . -F
+----
++
+After the build completes, your new custom builder image will be
+available in your project in an image stream tag named
+`custom-builder-image:latest`.

modules/builds-create-custom-build-artifacts.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+// * builds/custom-builds-buildah.adoc
+
+
+[id='builds-create-custom-build-artifacts-{context}']
+= Creating custom build artifacts
+
+You need to create the image you want to use as your custom build image.
+
+.Procedure
+
+. Starting with an empty directory, create a file named `Dockerfile` with the
+following content:
++
+----
+FROM docker.io/centos:7
+RUN yum install -y buildah
+# For simplicity, /tmp/build contains the inputs we’ll be building when we
+# run this custom builder image. Normally the custom builder image would
+# fetch this content from some location at build time. (e.g. via git clone).
+ADD Dockerfile.sample /tmp/input/Dockerfile
+ADD build.sh /usr/bin
+RUN chmod a+x /usr/bin/build.sh
+# /usr/bin/build.sh contains the actual custom build logic that will be executed when
+# this custom builder image is executed.
+ENTRYPOINT ["/usr/bin/build.sh"]
+----
+
+. In the same directory, create a file named `Dockerfile.sample`. This file will be
+included in the custom build image and defines the image that will be produced
+by the custom build:
++
+----
+FROM docker.io/centos:7
+RUN touch /tmp/built
+----
+
+. In the same directory, create a file named `build.sh`. This file contains the
+logic that will be executed when the custom build runs:
++
+----
+#!/bin/sh
+# Note that in this case the build inputs are part of the custom builder image, but normally this
+# would be retrieved from an external source.
+cd /tmp/input
+# OUTPUT_REGISTRY and OUTPUT_IMAGE are env variables provided by the custom
+# build framework
+TAG="${OUTPUT_REGISTRY}/${OUTPUT_IMAGE}"
+
+
+# performs the build of the new image defined by Dockerfile.sample
+buildah --storage-driver vfs bud --isolation chroot -t ${TAG} .
+
+
+# buildah requires a slight modification to the push secret provided by the service
+# account in order to use it for pushing the image
+cp /var/run/secrets/openshift.io/push/.dockercfg /tmp
+(echo "{ \"auths\": " ; cat /var/run/secrets/openshift.io/push/.dockercfg ; echo "}") > /tmp/.dockercfg
+
+
+# push the new image to the target for the build
+buildah --storage-driver vfs push --tls-verify=false --authfile /tmp/.dockercfg ${TAG}
+----

modules/builds-disabling-build-strategy-globally.adoc

@@ -0,0 +1,77 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+// * builds/securing-builds-by-strategy.adoc
+
+
+[id='builds-disabling-build-strategy-globally-{context}']
+= Disabling access to a build strategy globally
+
+To prevent access to a particular build strategy globally, log in as a user with
+*cluster-admin* privileges, remove the corresponding role from the
+*system:authenticated* group, and apply the annotation
+`rbac.authorization.kubernetes.io/autoupdate: "false"` to protect them from changes between
+the API restarts. The following example shows disabling the docker build
+strategy.
+
+.Procedure
+
+. Apply the `rbac.authorization.kubernetes.io/autoupdate` annotation:
++
+----
+$ oc edit clusterrolebinding system:build-strategy-docker-binding
+
+apiVersion: v1
+groupNames:
+- system:authenticated
+kind: ClusterRoleBinding
+metadata:
+  annotations:
+    rbac.authorization.kubernetes.io/autoupdate: "false" <1>
+  creationTimestamp: 2018-08-10T01:24:14Z
+  name: system:build-strategy-docker-binding
+  resourceVersion: "225"
+  selfLink: /oapi/v1/clusterrolebindings/system%3Abuild-strategy-docker-binding
+  uid: 17b1f3d4-9c3c-11e8-be62-0800277d20bf
+roleRef:
+  name: system:build-strategy-docker
+subjects:
+- kind: SystemGroup
+  name: system:authenticated
+userNames:
+- system:serviceaccount:management-infra:management-admin
+----
+<1> Change the `rbac.authorization.kubernetes.io/autoupdate` annotation's value to `"false"`. 
+. Remove the role:
++
+----
+$ oc adm policy remove-cluster-role-from-group system:build-strategy-docker system:authenticated
+----
+
+. Ensure the build strategy subresources are also removed from these roles:
++
+----
+$ oc edit clusterrole admin
+$ oc edit clusterrole edit
+----
+
+. For each role, remove the line that corresponds to the resource of the strategy
+to disable.
+.. Disable the Docker Build Strategy for *admin*:
++
+[source, yaml]
+----
+kind: ClusterRole
+metadata:
+  name: admin
+...
+rules:
+- resources:
+  - builds/custom
+  - builds/docker <1>
+  - builds/source
+  ...
+...
+----
+<1> Delete this line to disable Docker builds globally for users with the *admin*
+role.

modules/builds-restricting-build-strategy-globally.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+// * builds/securing-builds-by-strategy.adoc
+
+
+[id='builds-restricting-build-strategy-globally-{context}']
+= Restricting build strategies to users globally
+
+You can allow a set of specific users to create builds with a particular
+strategy.
+
+.Prerequisites
+
+* Disable global access to the build strategy.
+
+.Procedure
+
+* Assign the role that corresponds to the build strategy to a specific user. For
+example, to add the *system:build-strategy-docker* cluster role to the user
+*devuser*:
++
+----
+$ oc adm policy add-cluster-role-to-user system:build-strategy-docker devuser
+----
++
+[WARNING]
+====
+Granting a user access at the cluster level to the *builds/docker* subresource
+means that the user can create builds with the Docker strategy in
+any project in which they can create builds.
+====

modules/builds-restricting-build-strategy-to-user.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * assembly/builds
+// * builds/securing-builds-by-strategy.adoc
+
+
+[id='builds-restricting-build-strategy-to-user-{context}']
+= Restricting build strategies to a user within a project
+
+Similar to granting the build strategy role to a user globally, you can allow
+only a set of specific users within a project to create builds with a particular
+strategy.
+
+.Prerequisites
+
+* Disable global access to the build strategy.
+
+.Procedure
+
+* Assign the role that corresponds to the build strategy to a specific user within a
+project. For example, to add the *system:build-strategy-docker* role within the
+project *devproject* to the user *devuser*:
++
+----
+$ oc adm policy add-role-to-user system:build-strategy-docker devuser -n devproject
+----