Merge pull request #27860 from bmcelvee/term-updates-builds

Terminology updates for builds book

Author: bmcelvee

_topic_map.yml

@@ -614,6 +614,9 @@ Topics:
 - Name: Syncing LDAP groups
   File: ldap-syncing
   Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
+- Name: Creating and using config maps
+  File: configmaps
+  Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
 ---
 Name: Networking
 Dir: networking
@@ -1061,9 +1064,6 @@ Topics:
 - Name: Setting up additional trusted certificate authorities for builds
   File: setting-up-trusted-ca
   Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
-- Name: Creating and using ConfigMaps
-  File: builds-configmaps
-  Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
 ---
 Name: Pipelines
 Dir: pipelines

authentication/configmaps.adoc

@@ -0,0 +1,32 @@
+[id="configmaps"]
+= Creating and using config maps
+include::modules/common-attributes.adoc[]
+:context: configmaps
+
+toc::[]
+
+The following sections define config maps and how to create and use them.
+
+include::modules/authentication-configmap-overview.adoc[leveloffset=+1]
+
+include::modules/authentication-configmap-create-from-console.adoc[leveloffset=+1]
+
+include::modules/authentication-configmap-create.adoc[leveloffset=+1]
+
+include::modules/authentication-configmap-creating-from-directories.adoc[leveloffset=+2]
+
+include::modules/authentication-configmap-creating-from-files.adoc[leveloffset=+2]
+
+include::modules/authentication-configmap-creating-from-literal-values.adoc[leveloffset=+2]
+
+[id="authentication-configmaps-consuming-configmap-in-pods"]
+== Use Cases: Consuming ConfigMaps in pods
+
+The following sections describe some uses cases when consuming `ConfigMap`
+objects in pods.
+
+include::modules/authentication-configmaps-use-case-consuming-in-env-vars.adoc[leveloffset=+2]
+
+include::modules/authentication-configmaps-use-case-setting-command-line-arguments.adoc[leveloffset=+2]
+
+include::modules/authentication-configmaps-use-case-consuming-in-volumes.adoc[leveloffset=+2]

builds/advanced-build-operations.adoc

@@ -8,8 +8,6 @@ The following sections provide instructions for advanced build operations includ
 setting build resources and maximum duration, assigning builds to nodes, chaining
 builds, build pruning, and build run policies.
 
-// 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.
-
 include::modules/builds-setting-build-resources.adoc[leveloffset=+1]
 
 include::modules/builds-setting-maximum-duration.adoc[leveloffset=+1]

builds/basic-build-operations.adoc

@@ -4,11 +4,7 @@ include::modules/common-attributes.adoc[]
 :context: basic-build-operations
 toc::[]
 
-The following sections provide instructions for basic build operations including
-starting and canceling builds, deleting BuildConfigs, viewing build details, and
-accessing build logs.
-
-// 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.
+The following sections provide instructions for basic build operations including starting and canceling builds, deleting BuildConfigs, viewing build details, and accessing build logs.
 
 include::modules/builds-basic-start-build.adoc[leveloffset=+1]
 include::modules/builds-basic-start-re-run.adoc[leveloffset=+2]

builds/builds-configmaps.adoc

@@ -5,9 +5,9 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 
-With {product-title} {product-version}, a Docker socket will not be present on the host
+With {product-title} {product-version}, 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
+guaranteed to provide an accessible docker socket for use within a custom build
 image.
 
 If you require this capability in order to build and push images, add the Buildah

builds/custom-builds-buildah.adoc

@@ -13,8 +13,8 @@ include::modules/builds-source-secrets-entitlements.adoc[leveloffset=+1]
 There are two paths to pulling in the base RHEL image:
 
 * Add the pull secret to registry.redhat.io to your project.
-* Create an imagestream in the `openshift` namespace for the RHEL-based
-image. This makes the imagestream available across the cluster.
+* Create an image stream in the `openshift` namespace for the RHEL-based
+image. This makes the image stream available across the cluster.
 
 == Running builds with Subscription Manager
 
@@ -33,5 +33,5 @@ include::modules/builds-strategy-docker-squash-layers.adoc[leveloffset=+1]
 
 == Additional resources
 
-* See xref:../openshift_images/image-streams-manage.adoc#image-streams-managing[Managing imagestreams]
+* See xref:../openshift_images/image-streams-manage.adoc#image-streams-managing[Managing image streams]
 for more information.

builds/running-entitled-builds.adoc

@@ -4,26 +4,11 @@ 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.
+Builds in {product-title} are run in privileged containers. Depending on the build strategy used, if you have privileges, you can run builds to escalate their permissions on the cluster and host nodes. And as a security measure, it limits 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 administrator 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 to create builds using that strategy. Default roles are provided that grant the create permission on the build strategy subresource.
 
 .Build Strategy Subresources and Roles
 [options="header"]

builds/securing-builds-by-strategy.adoc

@@ -5,46 +5,46 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images
-from an image registry.
+Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images from an image registry.
 
-The procedure requires a cluster administrator to create a ConfigMap and add additional CAs as keys in the ConfigMap.
+The procedure requires a cluster administrator to create a `ConfigMap` and add additional CAs as keys in the `ConfigMap`.
 
-* The ConfigMap must be created in the `openshift-config` namespace.
-* `domain` is the key in the ConfigMap; `value` is the PEM-encoded certificate.
+* The `ConfigMap` must be created in the `openshift-config` namespace.
+* `domain` is the key in the `ConfigMap` and `value` is the PEM-encoded certificate.
 ** Each CA must be associated with a domain. The domain format is `hostname[..port]`.
-* The ConfigMap name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field.
+* The `ConfigMap` name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field.
 //* No longer needs single PEM bundle
 
 include::modules/configmap-adding-ca.adoc[leveloffset=+1]
 
 == Additional resources
 
-* link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a ConfigMap]
-* link:https://kubectl.docs.kubernetes.io/pages/app_management/secrets_and_configmaps.html[Secrets and ConfigMaps]
+* link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a `ConfigMap`]
+* link:https://kubectl.docs.kubernetes.io/guides/config_management/secrets_configmaps/[Secrets and `ConfigMaps`]
 * xref:../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI]
 endif::[]
+
+
 ifdef::openshift-dedicated[]
-Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images
-from an image registry.
+Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images from an image registry.
 
-The procedure requires a Dedicated administrator to create a ConfigMap and add additional CAs as keys in the ConfigMap.
+The procedure requires a Dedicated administrator to create a `ConfigMap` and add additional CAs as keys in the `ConfigMap`.
 
-* The ConfigMap must be created in the `openshift-config` namespace.
-* `domain` is the key in the ConfigMap; `value` is the PEM-encoded certificate.
+* The `ConfigMap` must be created in the `openshift-config` namespace.
+* `domain` is the key in the `ConfigMap` and `value` is the PEM-encoded certificate.
 ** Each CA must be associated with a domain. The domain format is `hostname[..port]`.
-* The ConfigMap name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field.
+* The `ConfigMap` name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field.
 //* No longer needs single PEM bundle
 
 [NOTE]
 ====
-{product-title} administrators are required to use the `registry-cas` ConfigMap.
+{product-title} administrators are required to use the `registry-cas` `ConfigMap`.
 ====
 
 include::modules/configmap-adding-ca.adoc[leveloffset=+1]
 
 == Additional resources
 
 * link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a ConfigMap]
-* link:https://kubectl.docs.kubernetes.io/pages/app_management/secrets_and_configmaps.html[Secrets and ConfigMaps]
+* link:https://kubectl.docs.kubernetes.io/guides/config_management/secrets_configmaps/[Secrets and ConfigMaps]
 endif::[]

builds/setting-up-trusted-ca.adoc

@@ -4,10 +4,7 @@ include::modules/common-attributes.adoc[]
 :context: triggering-builds-build-hooks
 toc::[]
 
-The following sections outline how to trigger builds and modify builds using
-build hooks.
-
-// 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.
+The following sections outline how to trigger builds and modify builds using build hooks.
 
 include::modules/builds-triggers.adoc[leveloffset=+1]