Merge pull request #96 from arewm/main

add instructions for nudging against unreleased artifacts

Author: arewm

docs/modules/ROOT/pages/advanced-how-tos/building-olm.adoc

@@ -31,6 +31,8 @@ This procedure assumes that the source code for your Operator and bundle, includ
 
 == Automating updates for image references in the CSV
 
+In order to enable your operator to be installed in disconnected environments, it is important to include sha digest image references in the link:https://sdk.operatorframework.io/docs/olm-integration/generation/#csv-fields[CSV's `spec.relatedImages`].
+
 .Procedure
 
 . In the {ProductName} UI, in your OLM Operator's application, go to the *Components* tab and copy the URL for the Operator's container image. The URL should include `sha256:`.
@@ -41,6 +43,53 @@ This procedure assumes that the source code for your Operator and bundle, includ
 .. Wait for the first build of those components to finish.
 .. Copy the URL to the images and paste it as a reference in the bundle's CSV file.
 
+== Maintaining valid image references before a release
+
+When images are xref:/advanced-how-tos/releasing/index.adoc[released] they will be copied to another image repository so any pinned references will be invalid. To surmount this, {ProductName} enables your bundle to be pinned to image references which will be valid after release.
+
+.Procedure
+
+. Configure your xref:/advanced-how-tos/releasing/create-release-plan-admission.adoc[release plan admission] which will copy the images to a new repository.
+. In the `spec.data.mapping.components` create a list of component mappings to the target repository
+
++
+*Example partial `ReleasePlanAdmission.yaml` object*
+
++
+[source,yaml]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: ReleasePlanAdmission
+spec:
+ applications:
+  - demo-app <.>
+ data:
+   mapping:
+     components: <.>
+       - name: demo-component-1
+         repository: target-image-repository-1
+       - name: demo-component-2
+         repository: target-image-repository-2
+ origin: <dev-workspace> <.>
+
+----
+
++
+<.> A list of applications that will contain components to be released.
+<.> A list containing the target repository for each component
+<.> The development team workspace where the applications and components are defined.
+
+. Using your preferred text editor, in the git repo for your OLM Operator, open the CSV file for your bundle. In that file, update the image references to all images that will be released to the target repository from the RPA (the sha digests should remain unchanged). Commit this change.
+
++
+NOTE: Once this change is merged, the bundle will be invalid until all referenced images are released. In order to test the bundles in an environment, you will need to use a registry mirror like an link:https://docs.openshift.com/container-platform/4.16/rest_api/config_apis/imagedigestmirrorset-config-openshift-io-v1.html[ImageDigestMirrorSet].
+
+.*Verification*
+
+. Commit a change to an Operand or Operator triggering a push event.
+. After the build is completed, a pull request should be opened against your bundle's git repository.
+
+
 == Building the file-based catalog
 
 .Procedure