feat(STONEINTG-892): add proc to create override snapshot

* add procedure to create override snapshot

Signed-off-by: Hongwei Liu <[email protected]>

docs/modules/ROOT/nav-how-to-guides.adoc

@@ -17,6 +17,7 @@
 *** xref:how-to-guides/testing_applications/proc_adding_an_integration_test.adoc[Adding an integration test]
 *** xref:how-to-guides/testing_applications/proc_creating_custom_test.adoc[Creating a custom integration test]
 *** xref:how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc[Retriggering integration tests]
+*** xref:how-to-guides/testing_applications/proc_creating_override_snapshot.adoc[Creating an override snapshot]
 ** Managing environments
 *** xref:how-to-guides/managing-environments/con_overview_of_environments.adoc[Overview of {ProductName} environments]
 *** xref:how-to-guides/managing-environments/proc_creating_your_own_environment.adoc[Creating your own environment]

docs/modules/ROOT/pages/how-to-guides/testing_applications/con_test-overview.adoc

@@ -35,4 +35,6 @@ Custom tests in {ProductName} are tests that users and administrators create. To
 
 Integration tests ensure that all build components are able to work together at the same time. You can xref:how-to-guides/testing_applications/proc_adding_an_integration_test.adoc[add an integration test], simply by giving {ProductName} the address to a GitHub repo, and the path within that repo to the `.yaml` file that defines the test.
 
-{ProductName} runs integration tests after it successfully builds the components of an application. As part of the build process, {ProductName} creates an image for each component and stores them in a Quay.io repository. Images of all the components are then compiled into a snapshot of the application. {ProductName} tests the snapshot against user-defined IntegrationTestScenarios, which, again, refer to a GitHub repository. 
+{ProductName} runs integration tests after it successfully builds the components of an application. As part of the build process, {ProductName} creates an image for each component and stores them in a Quay.io repository. Images of all the components are then compiled into a snapshot of the application. {ProductName} tests the snapshot against user-defined IntegrationTestScenarios, which, again, refer to a GitHub repository. 
+
+Integration service provides the users with the ability to reset their component's Global Candidate List to a desired state with a manually created `override`, you can xref:how-to-guides/testing_applications/proc_creating_override_snapshot.adoc[create an override snapshot] and provide a valid container image for component to reset the component's Global Candidate List.

docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_creating_override_snapshot.adoc

@@ -0,0 +1,70 @@
+= Creating an override snapshot
+
+In {ProductName}, integration service provides the users with the ability to reset their component's Global Candidate List to a desired state with a manually created `override` snapshot which can then be a candidate for further promotion (release) if it passes all integration tests subsequently. 
+
+== Prerequisites
+- You have CLI access to the specific OpenShift cluster. For information on obtaining CLI access, refer to  xref:../../getting-started/getting_started_in_cli.adoc[Getting started in CLI]
+- You have an up-to-date kubectl binary. Alternatively, the `oc` binary is also compatible.
+- You have an existing managed workspace such as `ws-sample`, an application such as `application-sample` and a component such as `component-sample`.
+
+== Procedures
+To create an `override` snapshot, complete the following steps:
+
+. Identify the application and component that needs to be updated
+. In your preferred IDE, create an `override` snapshot in a `.yaml` file.
++
+Example snapshot.yaml file::
+
++
+[source]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: Snapshot
+metadata:
+  name: snapshot-sample
+  namespace: ws-sample-tenant
+  labels:
+    test.appstudio.openshift.io/type: override <1>
+spec:
+  application: application-sample
+  components:
+    - name: component-sample <2>
+      containerImage: quay.io/redhat-user-workloads/ws-sample-tenant/application-sample/component-sample@sha256:0db0a473a6abf5c15c424ab07cfbd5c40c06622fe648d4fe6a6b6abc224a0d0c <3>
+----
+<1> The label `test.appstudio.openshift.io/type: override` that indicates this is an `override` snapshot.
+<2> The component name you will reset its Global Candidate List.
+<3> The container image with valid digest you will reset the component <2> to.
+
+
+. Save the .yaml file and add the snapshot.yaml by running the following command:
++
+[source,terminal]
+----
+$ oc create -f snapshot.yaml -n ws-sample-tenant
+----
+This command adds the `override` snapshot to your workspace and Integration service will processe the `override` snapshot and update the component `component-sample`'s `.Spec.ContainerImage` to `quay.io/redhat-user-workloads/ws-sample-tenant/application-sample/component-sample@sha256:0db0a473a6abf5c15c424ab07cfbd5c40c06622fe648d4fe6a6b6abc224a0d0c`
+
+== Verification
+After integration service processes the created `override` snapshot, you may verify snapshot and component by the following steps:
+
+. Check snapshot `.Status.Conditions` by the following command:
++
+[source,terminal]
+----
+$ oc get snapshot snapshot-sample -n ws-sample-tenant -o yaml | yq  '.status.conditions.[] | select(.type =="AddedToGlobalCandidateList")'
+lastTransitionTime: "2024-06-05T18:20:37Z"
+message: The Snapshot's component was added to the global candidate list
+reason: Added
+status: "True"
+type: AddedToGlobalCandidateList
+----
+
+. Browse to the component you are updating and select the **Component details** tab. The updated container image is shown under **Image** column.
+
+. Check component `.Spec.ContainerImage` by the following command:
++
+[source,terminal]
+----
+$ oc get component component-sample -n ws-sample-tenant -o yaml | yq .spec.containerImage
+quay.io/redhat-user-workloads/ws-sample-tenant/application-sample/component-sample@sha256:0db0a473a6abf5c15c424ab07cfbd5c40c06622fe648d4fe6a6b6abc224a0d0c
+----