diff --git a/docs/modules/ROOT/nav-how-to-guides.adoc b/docs/modules/ROOT/nav-how-to-guides.adoc index 639f7ed2..3b4c2cfd 100644 --- a/docs/modules/ROOT/nav-how-to-guides.adoc +++ b/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] diff --git a/docs/modules/ROOT/pages/how-to-guides/testing_applications/con_test-overview.adoc b/docs/modules/ROOT/pages/how-to-guides/testing_applications/con_test-overview.adoc index a7b0df79..a755da35 100644 --- a/docs/modules/ROOT/pages/how-to-guides/testing_applications/con_test-overview.adoc +++ b/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. \ No newline at end of file +{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. + +The integration service provides 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 a component to reset the component's Global Candidate List. diff --git a/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_creating_override_snapshot.adoc b/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_creating_override_snapshot.adoc new file mode 100644 index 00000000..54e43719 --- /dev/null +++ b/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_creating_override_snapshot.adoc @@ -0,0 +1,72 @@ += Creating an override snapshot + +In {ProductName}, the integration service provides 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. + +You can xref:how-to-guides/testing_applications/proc_creating_override_snapshot.adoc[create an override snapshot] and provide a valid container image for a component to reset the component's Global Candidate List. + +== 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's `.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 +----