openshift · stevsmit · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/_distro_map.yml b/_distro_map.yml
@@ -565,3 +565,16 @@ openshift-coo:
     standalone-coo-docs-1-latest:
       name: '1-latest'
       dir: coo/1-latest
+openshift-jtbd:
+  name: OpenShift Container Platform (JTBD)
+  author: OpenShift Documentation Project <openshift-docs@redhat.com>
+  site: commercial
+  site_name: Documentation
+  site_url: https://docs.openshift.com/
+  branches:
+    enterprise-4.22:
+      name: '4.22'
+      dir: container-platform-jtbd/4.22
+    testing-jtbd-openshift-images:
+      name: '4.22'
+      dir: container-platform-jtbd/4.22
diff --git a/_topic_maps/_topic_map_jtbd.yml b/_topic_maps/_topic_map_jtbd.yml
@@ -0,0 +1,59 @@
+# POC: JTBD-based Images book structure
+# Source: openshift_images consolidation report + Images JTBD statements.xlsx
+# Do not merge — structural POC only
+
+Name: Images
+Dir: openshift_images_jtbd
+Distros: openshift-jtbd
+Topics:
+- Name: Discover
+  Dir: discover
+  Topics:
+  - Name: Understand container images in OpenShift
+    File: understand-container-images-in-openshift
+
+- Name: Administer
+  Dir: administer
+  Topics:
+  - Name: Manage cluster sample image streams
+    File: manage-cluster-sample-image-streams
+  - Name: Configure cluster-wide image policy
+    File: configure-cluster-wide-image-policy
+
+- Name: Develop
+  Dir: develop
+  Topics:
+  - Name: Create container images for OpenShift
+    File: create-container-images-for-openshift
+  - Name: Build S2I builder images
+    File: build-s2i-builder-images
+  - Name: Deploy applications with Red Hat S2I images
+    File: deploy-applications-with-red-hat-s2i-images
+
+- Name: Configure
+  Dir: configure
+  Topics:
+  - Name: Mirror container images to a local registry
+    File: mirror-container-images-to-a-local-registry
+  - Name: Organize image versions with tags
+    File: organize-image-versions-with-tags
+  - Name: Control container image pull behavior
+    File: control-container-image-pull-behavior
+
+- Name: Secure
+  Dir: secure
+  Topics:
+  - Name: Authenticate workloads with private registries
+    File: authenticate-workloads-with-private-registries
+
+- Name: Integrate
+  Dir: integrate
+  Topics:
+  - Name: Automate CI/CD with image streams
+    File: automate-ci-cd-with-image-streams
+
+- Name: Optimize
+  Dir: optimize
+  Topics:
+  - Name: Manage image streams and imports
+    File: manage-image-streams-and-imports
diff --git a/openshift_images_jtbd/administer/_attributes b/openshift_images_jtbd/administer/_attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/openshift_images_jtbd/administer/configure-cluster-wide-image-policy.adoc b/openshift_images_jtbd/administer/configure-cluster-wide-image-policy.adoc
@@ -0,0 +1,52 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configure-cluster-wide-image-policy"]
+= Configure cluster-wide image policy
+include::_attributes/common-attributes.adoc[]
+:context: configure_cluster_wide_image_policy
+
+toc::[]
+
+[role="_abstract"]
+When I need to govern how my cluster handles container images cluster-wide, I want to configure the image.config.openshift.io/cluster resource, so I can control registry access, imports, mirroring, and trust policies consistently across all nodes.
+
+== Understand Image CR parameters [reference]
+
+include::modules/images-configuration-parameters.adoc[leveloffset=+1]
+
+== Configure registry allowlists and blocks [procedure]
+
+include::modules/images-configuration-file.adoc[leveloffset=+1]
+
+include::modules/images-configuration-allowed.adoc[leveloffset=+2]
+
+include::modules/images-configuration-blocked.adoc[leveloffset=+2]
+
+include::modules/images-configuration-blocked-payload.adoc[leveloffset=+2]
+
+include::modules/images-configuration-insecure.adoc[leveloffset=+2]
+
+== Configure short-name search registries [procedure]
+
+include::modules/images_configuration_shortname_con.adoc[leveloffset=+1]
+
+include::modules/images-configuration-shortname-when-not-to-use.adoc[leveloffset=+2]
+
+include::modules/images-configuration-shortname.adoc[leveloffset=+2]
+
+== Configure trust and mirroring [procedure]
+
+include::modules/images-configuration-cas.adoc[leveloffset=+2]
+
+include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1]
+
+include::modules/images-configuration-registry-mirror-configuring.adoc[leveloffset=+2]
+
+include::modules/images_configuring_registry_mirror_config_params.adoc[leveloffset=+2]
+
+include::modules/images-configuration-registry-mirror-convert.adoc[leveloffset=+2]
+
+include::modules/images-configuration-registry-mirror-project-secret.adoc[leveloffset=+2]
+
+== Understand MCO rollout behavior [concept]
+
+include::modules/images-configuration-mco-and-registry-changes.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/administer/images b/openshift_images_jtbd/administer/images
@@ -0,0 +1 @@
+../../images/
diff --git a/openshift_images_jtbd/administer/manage-cluster-sample-image-streams.adoc b/openshift_images_jtbd/administer/manage-cluster-sample-image-streams.adoc
@@ -0,0 +1,49 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="manage-cluster-sample-image-streams"]
+= Manage cluster sample image streams
+include::_attributes/common-attributes.adoc[]
+:context: manage_cluster_sample_image_streams
+
+toc::[]
+
+[role="_abstract"]
+When I need default sample image streams and templates in my cluster, I want to install, configure, and maintain Cluster Samples Operator content, so I can bootstrap development workflows in connected or disconnected environments.
+
+== Understand operator behavior
+
+include::snippets/cluster-sampler-operator-deprecation.adoc[leveloffset=+1]
+
+include::modules/samples-operator-overview.adoc[leveloffset=+1]
+
+include::modules/samples-operator-bootstrapped.adoc[leveloffset=+1]
+
+ifndef::openshift-rosa,openshift-dedicated[]
+include::modules/samples-operator-restricted-network-install.adoc[leveloffset=+2]
+
+include::modules/samples-operator-restricted-nw-install-with-access.adoc[leveloffset=+2]
+
+endif::openshift-rosa,openshift-dedicated[]
+
+== Configure management state and imports
+
+include::modules/samples-operator-retries.adoc[leveloffset=+1]
+
+include::modules/samples-operator-crd.adoc[leveloffset=+1]
+
+include::modules/images-samples-operator-deprecated-image-stream.adoc[leveloffset=+1]
+
+== Plan mirroring for sample content
+
+ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2]
+
+endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+
+ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+include::modules/samples-operator-configuration.adoc[leveloffset=+1]
+
+endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+
+== Configure alternate or mirrored registry
+
+include::modules/installation-restricted-network-samples.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/administer/modules b/openshift_images_jtbd/administer/modules
@@ -0,0 +1 @@
+../../modules
diff --git a/openshift_images_jtbd/administer/snippets b/openshift_images_jtbd/administer/snippets
@@ -0,0 +1 @@
+../../snippets
diff --git a/openshift_images_jtbd/configure/_attributes b/openshift_images_jtbd/configure/_attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/openshift_images_jtbd/configure/control-container-image-pull-behavior.adoc b/openshift_images_jtbd/configure/control-container-image-pull-behavior.adoc
@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="control-container-image-pull-behavior"]
+= Control container image pull behavior
+include::_attributes/common-attributes.adoc[]
+:context: control_container_image_pull_behavior
+
+toc::[]
+
+[role="_abstract"]
+When pods start containers, I want to configure imagePullPolicy, so I can control whether images are always pulled, pulled only if absent, or never pulled from the registry.
+
+== Configure explicit pull policy [reference]
+
+include::modules/images-image-pull-policy-overview.adoc[leveloffset=+1]
+
+== Rely on default pull policy [concept]
+
+include::modules/images-image-pull-policy-default-behavior.adoc[leveloffset=+2]
diff --git a/openshift_images_jtbd/configure/images b/openshift_images_jtbd/configure/images
@@ -0,0 +1 @@
+../../images/
diff --git a/openshift_images_jtbd/configure/mirror-container-images-to-a-local-registry.adoc b/openshift_images_jtbd/configure/mirror-container-images-to-a-local-registry.adoc
@@ -0,0 +1,28 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="mirror-container-images-to-a-local-registry"]
+= Mirror container images to a local registry
+include::_attributes/common-attributes.adoc[]
+:context: mirror_container_images_to_a_local_registry
+
+toc::[]
+
+[role="_abstract"]
+When I operate OpenShift in a restricted network, I want to mirror required container images to a local registry, so I can install, upgrade, and run workloads without internet access.
+
+== Plan mirror registry topology
+
+include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]
+
+include::modules/cli-installing-cli-linux.adoc[leveloffset=+2]
+
+include::modules/cli-installing-cli-windows.adoc[leveloffset=+2]
+
+include::modules/cli-installing-cli-macos.adoc[leveloffset=+2]
+
+== Configure mirroring credentials
+
+include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]
+
+== Mirror release images
+
+include::modules/installation-mirror-repository.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/configure/modules b/openshift_images_jtbd/configure/modules
@@ -0,0 +1 @@
+../../modules
diff --git a/openshift_images_jtbd/configure/organize-image-versions-with-tags.adoc b/openshift_images_jtbd/configure/organize-image-versions-with-tags.adoc
@@ -0,0 +1,28 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="organize-image-versions-with-tags"]
+= Organize image versions with tags
+include::_attributes/common-attributes.adoc[]
+:context: organize_image_versions_with_tags
+
+toc::[]
+
+[role="_abstract"]
+When I reference container images in builds and deployments, I want to use human-readable tags as mutable pointers to digests, so I can request specific versions and promote images between environments safely.
+
+== Apply tag naming conventions
+
+include::modules/images-tag.adoc[leveloffset=+1]
+
+include::modules/images-tagging-conventions.adoc[leveloffset=+1]
+
+== Add and remove tags
+
+include::modules/images-add-tags-to-imagestreams.adoc[leveloffset=+1]
+
+include::modules/images-remove-tag-imagestream.adoc[leveloffset=+1]
+
+== Choose reference syntax and types
+
+include::modules/images-referencing-images-imagestreams.adoc[leveloffset=+1]
+
+include::modules/images-imagestream-reference-types.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/configure/snippets b/openshift_images_jtbd/configure/snippets
@@ -0,0 +1 @@
+../../snippets
diff --git a/openshift_images_jtbd/develop/_attributes b/openshift_images_jtbd/develop/_attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/openshift_images_jtbd/develop/build-s2i-builder-images.adoc b/openshift_images_jtbd/develop/build-s2i-builder-images.adoc
@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="build-s2i-builder-images"]
+= Build S2I builder images
+include::_attributes/common-attributes.adoc[]
+:context: build_s2i_builder_images
+
+toc::[]
+
+[role="_abstract"]
+When developers build applications from source on OpenShift, I want to create S2I builder images, so I can transform application source into runnable container images with minimal developer effort.
+
+== Understand the S2I build process [concept]
+
+include::modules/images-create-s2i.adoc[leveloffset=+1]
+
+include::modules/images-create-s2i-build.adoc[leveloffset=+2]
+
+== Write assemble and run scripts [procedure]
+
+include::modules/images-create-s2i-scripts.adoc[leveloffset=+2]
+
+== Test builder images [procedure]
+
+include::modules/images-test-s2i.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/develop/create-container-images-for-openshift.adoc b/openshift_images_jtbd/develop/create-container-images-for-openshift.adoc
@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="create-container-images-for-openshift"]
+= Create container images for OpenShift
+include::_attributes/common-attributes.adoc[]
+:context: create_container_images_for_openshift
+
+toc::[]
+
+[role="_abstract"]
+When I build applications for OpenShift, I want to create container images following platform best practices, so I can deploy reproducible, secure, and consumable images on the cluster.
+
+== General container image guidelines [concept]
+
+include::modules/images-create-guidelines.adoc[leveloffset=+1]
+
+include::modules/images-create-guide-general.adoc[leveloffset=+2]
+
+== OpenShift-specific authoring guidelines [concept]
+
+include::modules/images-create-guide-openshift.adoc[leveloffset=+2]
+
+== Define image metadata labels [reference]
+
+include::modules/images-create-metadata.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/develop/deploy-applications-with-red-hat-s2i-images.adoc b/openshift_images_jtbd/develop/deploy-applications-with-red-hat-s2i-images.adoc
@@ -0,0 +1,41 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="deploy-applications-with-red-hat-s2i-images"]
+= Deploy applications with Red Hat S2I images
+include::_attributes/common-attributes.adoc[]
+:context: deploy_applications_with_red_hat_s2i_images
+
+toc::[]
+
+[role="_abstract"]
+When I build and deploy containerized applications on OpenShift, I want to locate and use supported Red Hat S2I and middleware images, so I can run applications with version-compatible base components.
+
+== Find supported Red Hat container images
+
+Red{nbsp}Hat official container images are provided in the Red{nbsp}Hat Registry at link:https://registry.redhat.io[registry.redhat.io]. {product-title}'s supported S2I, database, and Jenkins images are provided in the `openshift4` repository in the {quay} Registry. For example, `quay.io/openshift-release-dev/ocp-v4.0-<address>` is the name of the OpenShift Application Platform image.
+
+The xPaaS middleware images are provided in their respective product repositories on the Red Hat Registry but suffixed with a `-openshift`. For example, `registry.redhat.io/jboss-eap-6/eap64-openshift` is the name of the JBoss EAP image.
+
+All Red{nbsp}Hat supported images covered in this section are described in the link:https://catalog.redhat.com/software/containers/explore[Container images section of the Red Hat Ecosystem Catalog]. For every version of each image, you can find details on its contents and usage. Browse or search for the image that interests you.
+
+[IMPORTANT]
+====
+The newer versions of container images are not compatible with earlier versions of {product-title}. Verify and use the correct version of container images, based on your version of {product-title}.
+====
+
+== Use S2I builder images
+
+You can use the link:https://access.redhat.com/documentation/en-us/red_hat_software_collections/3/html-single/using_red_hat_software_collections_container_images/index[Red{nbsp}Hat Software Collections] images as a foundation for applications that rely on specific runtime environments such as Node.js, Perl, or Python. 
+
+You can use the link:https://docs.redhat.com/en/documentation/red_hat_build_of_openjdk/11/html/using_source-to-image_for_openshift_with_red_hat_build_of_openjdk_11/openjdk-overview-s2i-openshift[Introduction to source-to-image for OpenShift] documentation as a reference for runtime environments that use Java.
+
+S2I images are also available though the xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Cluster Samples Operator].
+
+include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
+
+== Select builders in Developer Console
+
+include::modules/accessing-s2i-builder-images-in-developer-console.adoc[leveloffset=+1]
+
+== Customize S2I builder behavior
+
+include::modules/images-using-customizing-s2i-images-scripts-embedded.adoc[leveloffset=+1]
diff --git a/openshift_images_jtbd/develop/images b/openshift_images_jtbd/develop/images
@@ -0,0 +1 @@
+../../images/
diff --git a/openshift_images_jtbd/develop/modules b/openshift_images_jtbd/develop/modules
@@ -0,0 +1 @@
+../../modules
diff --git a/openshift_images_jtbd/develop/snippets b/openshift_images_jtbd/develop/snippets
@@ -0,0 +1 @@
+../../snippets
diff --git a/openshift_images_jtbd/discover/_attributes b/openshift_images_jtbd/discover/_attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/openshift_images_jtbd/discover/images b/openshift_images_jtbd/discover/images
@@ -0,0 +1 @@
+../../images/
diff --git a/openshift_images_jtbd/discover/modules b/openshift_images_jtbd/discover/modules
@@ -0,0 +1 @@
+../../modules
diff --git a/openshift_images_jtbd/discover/snippets b/openshift_images_jtbd/discover/snippets
@@ -0,0 +1 @@
+../../snippets