Merge pull request #73661 from bhardesty/osdocs-8076-cicd-port

OSDOCS-9984: Port BuildConfig and Jenkins books to OSD and ROSA

Author: jeana-redhat

_topic_maps/_topic_map_osd.yml

@@ -456,13 +456,71 @@ Name: CI/CD
 Dir: cicd
 Distros: openshift-dedicated
 Topics:
-- Name: Builds
+- Name: CI/CD overview
+  File: index
+# This can be included when Shipwright is ported.
+# - Name: Builds using Shipwright
+#   Dir: builds_using_shipwright
+#   Topics:
+#   - Name: Overview of Builds
+#     File: overview-openshift-builds
+- Name: Builds using BuildConfig
   Dir: builds
-  Distros: openshift-dedicated
   Topics:
-  - Name: Setting up additional trusted certificate authorities for builds
-    File: setting-up-trusted-ca
-    Distros: openshift-dedicated
+  - Name: Understanding image builds
+    File: understanding-image-builds
+  - Name: Understanding build configurations
+    File: understanding-buildconfigs
+  - Name: Creating build inputs
+    File: creating-build-inputs
+  - Name: Managing build output
+    File: managing-build-output
+  - Name: Using build strategies
+    File: build-strategies
+#  - Name: Custom image builds with Buildah
+#    File: custom-builds-buildah
+  - Name: Performing and configuring 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: Using Red Hat subscriptions in builds
+    File: running-entitled-builds
+  # Dedicated-admin cannot secure builds by strategy
+  # - Name: Securing builds by strategy
+  #   File: securing-builds-by-strategy
+  # Dedicated-admin cannot edit build configuration resources
+  # - Name: Build configuration resources
+  #   File: build-configuration
+  - Name: Troubleshooting builds
+    File: troubleshooting-builds
+#  - Name: Setting up additional trusted certificate authorities for builds
+#    File: setting-up-trusted-ca
+# This can be included when Pipelines is ported.
+# - Name: Pipelines
+#   Dir: pipelines
+#   Topics:
+#   - Name: About OpenShift Pipelines
+#     File: about-pipelines
+# This can be included when GitOps is ported.
+# - Name: GitOps
+#   Dir: gitops
+#   Topics:
+#   - Name: About OpenShift GitOps
+#     File: about-redhat-openshift-gitops
+- Name: Jenkins
+  Dir: jenkins
+  Topics:
+  - Name: Configuring Jenkins images
+    File: images-other-jenkins
+  - Name: Jenkins agent
+    File: images-other-jenkins-agent
+# Include this once Pipelines is ported:
+#   - Name: Migrating from Jenkins to OpenShift Pipelines
+#     File: migrating-from-jenkins-to-openshift-pipelines
+  - Name: Important changes to OpenShift Jenkins images
+    File: important-changes-to-openshift-jenkins-images
 ---
 Name: Images
 Dir: openshift_images

_topic_maps/_topic_map_rosa.yml

@@ -689,13 +689,71 @@ Name: CI/CD
 Dir: cicd
 Distros: openshift-rosa
 Topics:
-- Name: Builds
+- Name: CI/CD overview
+  File: index
+# This can be included when Shipwright is ported.
+# - Name: Builds using Shipwright
+#   Dir: builds_using_shipwright
+#   Topics:
+#   - Name: Overview of Builds
+#     File: overview-openshift-builds
+- Name: Builds using BuildConfig
   Dir: builds
-  Distros: openshift-rosa
   Topics:
-  - Name: Setting up additional trusted certificate authorities for builds
-    File: setting-up-trusted-ca
-    Distros: openshift-rosa
+  - Name: Understanding image builds
+    File: understanding-image-builds
+  - Name: Understanding build configurations
+    File: understanding-buildconfigs
+  - Name: Creating build inputs
+    File: creating-build-inputs
+  - Name: Managing build output
+    File: managing-build-output
+  - Name: Using build strategies
+    File: build-strategies
+#  - Name: Custom image builds with Buildah
+#    File: custom-builds-buildah
+  - Name: Performing and configuring 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: Using Red Hat subscriptions in builds
+    File: running-entitled-builds
+  # Dedicated-admin cannot secure builds by strategy
+  # - Name: Securing builds by strategy
+  #   File: securing-builds-by-strategy
+  # Dedicated-admin cannot edit build configuration resources
+  # - Name: Build configuration resources
+  #   File: build-configuration
+  - Name: Troubleshooting builds
+    File: troubleshooting-builds
+#  - Name: Setting up additional trusted certificate authorities for builds
+#    File: setting-up-trusted-ca
+# This can be included when Pipelines is ported.
+# - Name: Pipelines
+#   Dir: pipelines
+#   Topics:
+#   - Name: About OpenShift Pipelines
+#     File: about-pipelines
+# This can be included when GitOps is ported.
+# - Name: GitOps
+#   Dir: gitops
+#   Topics:
+#   - Name: About OpenShift GitOps
+#     File: about-redhat-openshift-gitops
+- Name: Jenkins
+  Dir: jenkins
+  Topics:
+  - Name: Configuring Jenkins images
+    File: images-other-jenkins
+  - Name: Jenkins agent
+    File: images-other-jenkins-agent
+# Include this when Pipelines is ported:
+#  - Name: Migrating from Jenkins to OpenShift Pipelines
+#    File: migrating-from-jenkins-to-openshift-pipelines
+  - Name: Important changes to OpenShift Jenkins images
+    File: important-changes-to-openshift-jenkins-images
 ---
 Name: Images
 Dir: openshift_images

cicd/builds/advanced-build-operations.adoc

@@ -6,9 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-The following sections provide instructions for advanced build operations including
-setting build resources and maximum duration, assigning builds to nodes, chaining
-builds, build pruning, and build run policies.
+You can set build resources and maximum duration, assign builds to nodes, chain builds, prune builds, and configure build run policies.
 
 include::modules/builds-setting-build-resources.adoc[leveloffset=+1]
 

cicd/builds/build-strategies.adoc

@@ -27,6 +27,12 @@ include::modules/builds-strategy-docker-squash-layers.adoc[leveloffset=+2]
 
 include::modules/builds-using-build-volumes.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../cicd/builds/creating-build-inputs.adoc#builds-define-build-inputs_creating-build-inputs[Build inputs]
+* xref:../../cicd/builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input secrets and config maps]
+
 
 // S2I build strategy
 
@@ -54,8 +60,16 @@ include::modules/images-create-s2i-scripts.adoc[leveloffset=+3]
 
 include::modules/builds-using-build-volumes.adoc[leveloffset=+2]
 
-// Custom build strategy
+[role="_additional-resources"]
+.Additional resources
 
+* xref:../../cicd/builds/creating-build-inputs.adoc#builds-define-build-inputs_creating-build-inputs[Build inputs]
+* xref:../../cicd/builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input secrets and config maps]
+
+// Custom build strategy
+// Custom builds require cluster-admin permissions, and are 
+// generally discouraged for customers.
+ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/builds-strategy-custom-build.adoc[leveloffset=+1]
 
 include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2]
@@ -65,9 +79,14 @@ 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]
+endif::openshift-dedicated,openshift-rosa[]
 
 // Pipeline build strategy
+// Pipeline builds are deprecated, but OpenShift Pipelines have 
+// not been added to the OSD/ROSA docs yet. Once added, these 
+// sections can be added back to the OSD/ROSA docs.
 
+ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1]
 
 include::modules/builds-understanding-openshift-pipeline.adoc[leveloffset=+2]
@@ -79,6 +98,7 @@ include::modules/builds-strategy-pipeline-environment-variables.adoc[leveloffset
 include::modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc[leveloffset=+3]
 
 include::modules/builds-tutorial-pipeline.adoc[leveloffset=+2]
+endif::openshift-dedicated,openshift-rosa[]
 
 //include::modules/builds-strategy-force-pull-procedure.adoc[leveloffset=+1]
 

cicd/builds/running-entitled-builds.adoc

@@ -11,7 +11,9 @@ Use the following sections to install Red Hat subscription content within {produ
 
 include::modules/builds-create-imagestreamtag.adoc[leveloffset=+1]
 
+ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/builds-source-secrets-entitlements.adoc[leveloffset=+1]
+endif::openshift-dedicated,openshift-rosa[]
 
 == Running builds with Subscription Manager
 
@@ -28,16 +30,25 @@ include::modules/builds-strategy-docker-entitled-satellite.adoc[leveloffset=+2]
 
 * link:https://access.redhat.com/solutions/5847331[How to use builds with Red Hat Satellite subscriptions and which certificate to use]
 
+ifndef::openshift-dedicated,openshift-rosa[]
 // Beginning of "Running entitled builds with SharedSecret objects" section
 
+// Tech Preview features are not included in ROSA and OSD. When this feature
+// is GA, it should be evaluated for possible inclusion in the OSD and ROSA
+// docs.
+
 include::modules/builds-running-entitled-builds-with-sharedsecret-objects.adoc[leveloffset=+1]
 
 // End of "Running entitled builds with SharedSecret objects" section
+endif::openshift-dedicated,openshift-rosa[]
 
 [role="_additional-resources"]
 == Additional resources
 
+// The following two xrefs are not included in the OSD and ROSA docs.
+ifndef::openshift-dedicated,openshift-rosa[]
 * xref:../../support/remote_health_monitoring/insights-operator-simple-access.adoc#insights-operator-simple-access[Importing simple content access certificates with Insights Operator]
 * xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+endif::openshift-dedicated,openshift-rosa[]
 * xref:../../openshift_images/image-streams-manage.adoc#image-streams-managing[Managing image streams]
-* xref:../../cicd/builds/build-strategies.adoc#build-strategies[build strategy]
+* xref:../../cicd/builds/build-strategies.adoc#build-strategies[Build strategies]

cicd/builds/understanding-image-builds.adoc

@@ -12,6 +12,14 @@ include::modules/builds-strategy-docker-build.adoc[leveloffset=+2]
 
 include::modules/builds-strategy-s2i-build.adoc[leveloffset=+2]
 
+// Custom builds require cluster-admin
+ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/builds-strategy-custom-build.adoc[leveloffset=+2]
+endif::openshift-dedicated,openshift-rosa[]
 
+// Pipeline builds are deprecated, but the OpenShift Pipelines 
+// doc has not been added to the OSD/ROSA docs yet. Once it is
+// added, this section can be included in the OSD/ROSA docs.
+ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+2]
+endif::openshift-dedicated,openshift-rosa[]

cicd/index.adoc

@@ -6,15 +6,24 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+// The Shipwright, Pipelines, and GitOps content is not currently included
+// in the OSD and ROSA docs. As these layered products are added to the 
+// OSD and ROSA docs, the applicable content and xrefs below should be 
+// included.
 
 {product-title} is an enterprise-ready Kubernetes platform for developers, which enables organizations to automate the application delivery process through DevOps practices, such as continuous integration (CI) and continuous delivery (CD). To meet your organizational needs, the {product-title} provides the following CI/CD solutions:
 
 * OpenShift Builds
+ifndef::openshift-dedicated,openshift-rosa[]
 * {pipelines-shortname}
 * OpenShift GitOps
+endif::openshift-dedicated,openshift-rosa[]
+* Jenkins
 
 [id="openshift-builds"]
 == OpenShift Builds
+// This can be included in the OSD and ROSA docs when Shipwright is ported.
+ifndef::openshift-dedicated,openshift-rosa[]
 OpenShift Builds provides you the following options to configure and run a build:
 
 * Builds using Shipwright is an extensible build framework based on the Shipwright project. You can use it to build container images on an {product-title} cluster. You can build container images from source code and Dockerfile by using image build tools, such as Source-to-Image (S2I) and Buildah.
@@ -24,18 +33,32 @@ For more information, see link:https://docs.openshift.com/builds/latest/about/ov
 * Builds using `BuildConfig` objects is a declarative build process to create cloud-native apps. You can define the build process in a YAML file that you use to create a `BuildConfig` object. This definition includes attributes such as build triggers, input parameters, and source code. When deployed, the `BuildConfig` object builds a runnable image and pushes the image to a container image registry. With the `BuildConfig` object, you can create a Docker, Source-to-image (S2I), or custom build.
 +
 For more information, see xref:../cicd/builds/understanding-image-builds.adoc#understanding-image-builds[Understanding image builds].
+endif::openshift-dedicated,openshift-rosa[]
 
+// This is the same para as above, but without the unordered list.
+ifdef::openshift-dedicated,openshift-rosa[]
+Builds using `BuildConfig` objects is a declarative build process to create cloud-native apps. You can define the build process in a YAML file that you use to create a `BuildConfig` object. This definition includes attributes such as build triggers, input parameters, and source code. When deployed, the `BuildConfig` object builds a runnable image and pushes the image to a container image registry. With the `BuildConfig` object, you can create a Docker, Source-to-image (S2I), or custom build.
+
+For more information, see xref:../cicd/builds/understanding-image-builds.adoc#understanding-image-builds[Understanding image builds].
+endif::openshift-dedicated,openshift-rosa[]
+
+// This can be included in OSD and ROSA when the Pipelines doc is ported.
+ifndef::openshift-dedicated,openshift-rosa[]
 [id="openshift-pipelines"]
 == {pipelines-shortname}
 {pipelines-shortname} provides a Kubernetes-native CI/CD framework to design and run each step of the CI/CD pipeline in its own container. It can scale independently to meet the on-demand pipelines with predictable outcomes.
 
 For more information, see link:https://docs.openshift.com/pipelines/latest/about/understanding-openshift-pipelines.html[Understanding {pipelines-shortname}].
+endif::openshift-dedicated,openshift-rosa[]
 
+// This can be included in OSD and ROSA when the GitOps doc is ported.
+ifndef::openshift-dedicated,openshift-rosa[]
 [id="openshift-gitops"]
 == OpenShift GitOps
 OpenShift GitOps is an Operator that uses Argo CD as the declarative GitOps engine. It enables GitOps workflows across multicluster OpenShift and Kubernetes infrastructure. Using OpenShift GitOps, administrators can consistently configure and deploy Kubernetes-based infrastructure and applications across clusters and development lifecycles.
 
 For more information, see xref:../cicd/gitops/about-redhat-openshift-gitops.adoc#about-redhat-openshift-gitops[About {gitops-title}].
+endif::openshift-dedicated,openshift-rosa[]
 
 [id="jenkins-ci-cd"]
 == Jenkins

cicd/jenkins/images-other-jenkins-agent.adoc

@@ -23,6 +23,7 @@ Use a version of the agent image that is appropriate for your {product-title} re
 The {product-title} Jenkins image also defines the following sample `java-builder` pod template to illustrate how you can use the agent image with the Jenkins Kubernetes plugin.
 
 The `java-builder` pod template employs two containers:
+
 * A `jnlp` container that uses the {product-title} Base agent image and handles the JNLP contract for starting and stopping Jenkins agents.
 * A `java` container that uses the `java` {product-title} Sample ImageStream, which contains the various Java binaries, including the Maven binary `mvn`, for building code.
 

cicd/jenkins/images-other-jenkins.adoc

@@ -71,5 +71,9 @@ include::modules/images-other-jenkins-memory.adoc[leveloffset=+1]
 [role="_additional-resources"]
 == Additional resources
 
+// This xref points to a topic that is not currently included in the OSD and 
+// ROSA docs.
+ifndef::openshift-dedicated,openshift-rosa[]
 * See xref:../../architecture/understanding-development.adoc#base-image-options[Base image options] for more information about the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#using_red_hat_base_container_images_standard_and_minimal[Red Hat Universal Base Images] (UBI).
+endif::openshift-dedicated,openshift-rosa[]
 * xref:../../cicd/jenkins/important-changes-to-openshift-jenkins-images.adoc#important-changes-to-openshift-jenkins-images[Important changes to OpenShift Jenkins images]