Merge pull request #85 from arewm/migrate-advanced-how-tos

Migrate and update basic release documentation

docs/modules/ROOT/pages/advanced-how-tos/_nav.adoc

@@ -6,5 +6,6 @@
 ** xref:advanced-how-tos/releasing/index.adoc[Releasing an application]
 *** xref:advanced-how-tos/releasing/create-release-plan.adoc[Creating a release plan]
 *** xref:advanced-how-tos/releasing/create-release-plan-admission.adoc[Creating a release plan admission]
+*** xref:advanced-how-tos/releasing/create-release.adoc[Creating a release]
 ** xref:advanced-how-tos/managing-multiple-versions.adoc[Managing multiple software versions]
 ** xref:advanced-how-tos/managing-security-fix.adoc[Managing a security fix]

docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan-admission.adoc

@@ -1 +1,68 @@
-= Creating a release plan admission
+= Creating a release plan admission
+
+A ReleasePlanAdmission (RPA) CR exists within a managed workspace. It defines the specific pipeline to run and a given xref:/advanced-how-tos/managing-compliance-with-ec.adoc[Enterprise Contract] Policy which needs to pass for the Snapshot before that pipeline can proceed.
+
+When an application is ready for release, the Development team contacts the owners of the managed workspace (for example, their organization's SRE team) and  requested access to the managed workspace. A RPA object is then created in the managed workspace to specify the configuration.
+
+== Creating a `ReleasePlanAdmission` object
+
+.*Prerequisites*
+
+* An existing Development and Managed workspace.
+
+* An existing `ReleasePlan` object in the Development workspace.
+
+.*Procedures*
+
+. Create a `ReleasePlanAdmission.yaml` object locally.
+
++
+*Example `ReleasePlanAdmission.yaml` object*
+
++
+[source,yaml]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: ReleasePlanAdmission
+metadata:
+ name: sre-production <.>
+ namespace: managed-workspace <.>
+spec:
+ applications:
+  - demo-app <.>
+ data: <key> <.>
+ environment: <sre-production> <.>
+ origin: <dev-workspace> <.>
+ pipelineRef: <pipeline_ref> <.>
+ policy: <policy> <.>
+ serviceAccount: <service-account> <.>
+
+----
+
++
+<.> The name of the release plan admission.
+<.> The Managed environment team's workspace.
+<.> A list of applications that you want to enable to be deployed in the managed workspace.
+<.> Optional: An unstructured key used for providing data for the managed Pipeline.
+<.> Optional: The environment from which the application updates are allowed to be received in the Managed workspace. This environment is created by the Development team.
+<.> The development team workspace where the application is defined.
+<.> Reference to the Pipeline to be executed by the release service.
+<.> The enterprise contract policy against which the system validates an application before releasing it to production.
+<.> Optional: The name of the service account to use in the Pipeline to gain elevated privileges. It's used only if you have defined the `pipelineRef` value.
+
++
+NOTE: The  ReleasePlanAdmission.yaml represents the reciprocal link to the ReleasePlan.yaml objects created by the development team.
+
+. In the Managed workspace, apply the `ReleasePlanAdmission.yaml` file and add the resource to your cluster by running the following command:
+
++
+[source,shell]
+----
+oc apply -f ReleasePlanAdmission.yaml -n managed
+----
+
+.*Verification*
+
+. In the {ProductName} UI, select the *Release services* > *Release plan admission* tab.
+. Review the RPA object that you just added. Using the Release plan admission tab, you can update or delete the selected Release plan object.
+. When a ReleasePlanAdmission is correctly configured to be paired with a ReleasePlan, its *Status* will display as being `Matched`.

docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan.adoc

@@ -1 +1,63 @@
-= Creating a release plan
+= Creating a release plan
+
+A ReleasePlan (RP) CR is created for a specific Application. It defines the the process to release a specific Application Snapshot in a target workspace, whether automatic releases are enabled, as well as additional data to pass to a corresponding RPA.
+
+== Creating a `ReleasePlan` object
+
+The development team creates a `ReleasePlan` object in the developer workspace. The `ReleasePlan` object includes a reference to the application that the development team wants to release, along with workspace where the application is supposed to be released.
+
+.*Prerequisites*
+
+* You have an existing Development workspace.
+* Ensure you have installed `oc`.
+* You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
+
+.*Procedures*
+
+. Create a `ReleasePlan.yaml` object locally.
+
++
+*Example `ReleasePlan.yaml` object*
+
++
+[source,yaml]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: ReleasePlan
+metadata:
+ labels:
+   release.appstudio.openshift.io/auto-release: 'true'
+   release.appstudio.openshift.io/standing-attribution: 'true'
+   release.appstudio.openshift.io/releasePlanAdmission: 'rpa-name' <.>
+ name: sre-production <.>
+ namespace: dev-workspace <.>
+spec:
+ application: <application-name> <.>
+ data: <key> <.>
+ pipelineRef: <pipeline-ref> <.>
+ serviceAccont: <service-account> <.>
+ target: managed-workspace <.>
+----
+
++
+<.> The name of the release plan.
+<.> The development team's workspace.
+<.> The name of the application that you want to deploy to the managed workspace.
+<.> Optional: The name of the RPA to use if more than one RPA references the specified application.
+<.> Optional: An unstructured key used for providing data for the managed Pipeline.
+<.> Optional: Reference to the Pipeline to be executed by the release service.
+<.> Optional: The name of the service account to use in the Pipeline to gain elevated privileges. It's used only if you have defined the `pipelineRef` value.
+<.> The workspace to which the system deploys the application. This workspace is created by the Managed environment team (for example, your organization's SRE team)
+
+. In the development workspace, apply the `ReleasePlan.yaml` file and add the resource to your cluster by running the following command:
+
++
+[source,shell]
+----
+$ oc apply -f ReleasePlan.yaml -n dev
+----
+
+.*Verification*
+
+. In the {ProductName} UI, select the *Release services* > *Release plan* tab.
+. Review the Release plan object that you just added. Using the Release plan tab, you can update or delete the selected Release plan object.

docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release.adoc

@@ -0,0 +1,59 @@
+= Creating a release
+
+A Release CR is created to submit a specific Application Snapshot to be processed according to teh referenced ReleasePlan.
+
+== Creating a `Release` object
+
+The development team creates a `Release` object in the developer workspace. The `Release` object includes a reference to the application snapshot that the development team wants to release, along with release plan that will be used to release the application.
+
+.*Prerequisites*
+
+* You have an existing Development workspace.
+* Ensure you have installed `oc`.
+* You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
+* You have completed the steps for creating a ReleasePlanAdmission and a matching ReleasePlan.
+
+.*Procedures*
+
+. Create a `Release.yaml` object locally.
+
++
+*Example `Release.yaml` object*
+
++
+[source,yaml]
+----
+apiVersion: appstudio.redhat.com/v1alpha1
+kind: Release
+metadata:
+ name: <name-of-this-release> <.>
+ namespace: dev-workspace <.>
+spec:
+ releasePlan: <release-plan-name> <.>
+ snapshot: <application-snapshot-name> <.>
+ data: <key> <.>
+----
+
+
++
+<.> The name of the release.
+<.> The development team's workspace.
+<.> The name of the release plan specifying the pipeline to run.
+<.> The name of the application snapshot that you want to release.
+<.> Optional: An unstructured key used for providing data for the managed Pipeline.
+
+. In the development workspace, apply the `Release.yaml` file and add the resource to your cluster by running the following command:
+
++
+[source,shell]
+----
+$ oc apply -f Release.yaml -n dev
+----
+
+.*Verification*
+
+. In the {ProductName} UI, select the *Applications* tab
+. Click on the application that is being released
+. Click on the *Releases* tab
+. See the recent releases that have been created for the application.
+. You can find a link to the release pipeline run by clicking on the name of the release that you created.

docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc

@@ -3,24 +3,26 @@
 :numbered:
 :source-highlighter: highlightjs
 
-Two teams work together to release an application:
+The process of developing software rarely happens entirely within a single team. Especially within large organizations, different teams may be building and deploying applications. In these situations, the team managing the deployments (for example, Site Reliability Engineers) will want to automate the process of accepting content for release, validating that certain conditions are met, and then performing the release action—all while maintaining control of their pipelines and secrets. In {ProductName}, we call this process releasing an application.
 
-* *Development team* - The team that develops and supports the application in a pre-production environment.
+Two teams work together to release an application:
 
-* *Managed environment team* - The team that supports the production instance of that application.
+* *Development team* - The team that develops and supports the application. This may include testing or deploying it in a pre-production environment.
 
-image::managed_environment.png[alt=Managed Environment]
+* *Managed environment team* - The team that maintains control of the process and secrets for performing a specific action (for example, deploying an application to a production environment).
 
-[1] When an application is ready for release, the Development team contacts the Managed Environment team; for example, their organization's SRE team, requesting access to the Managed environment for the first production release.
+.Procedure
 
-[2] The Managed environment team creates the managed environment and responds to the development team with the managed environment's configuration details. The Managed environment inherits some details of the development team’s workspace. However, the development team has limited access to the production environment, which is a part of the managed environment.
+. When an application is ready for release, the Development team contacts the Managed Environment team (for example, their organization's SRE team) requesting access to the managed environment for the first production release. 
 
-[3] The development team creates a matching configuration in their environment that is same as that of the Managed environment and attempts to release the application to production.
+. The development and managed environment teams will work together to create a ReleasePlanAdmission (RPA) in the managed environment to specify the release pipeline to run containing the appropriate tasks to release the application.
 
-[4] The Managed environment team validates the initial release and configures a traffic gateway, which allows external traffic to the application.
+. The development team creates a matching ReleasePlan (RP) configuration in their environment, which is same as that of the Managed environment, and attempts to release the application to production.
 
 .Next steps
 
 * *Create a `releasePlan` object:* The development team creates a ReleasePlan object in the developer workspace. The ReleasePlan object includes a reference to the application that the development team wants to release, along with workspace where the application is supposed to be released.
 
-* *Create a `releasePlanAdmission` object:* The Managed Environment team creates or updates the ReleasePlanAdmission object in response to the ReleasePlan object created by the development team. It indicates that the Managed Environment team has approved the application specified in the ReleasePlan object.
+* *Create a `releasePlanAdmission` object:* The Managed Environment team creates or updates the ReleasePlanAdmission object in response to the ReleasePlan object created by the development team. It indicates that the Managed Environment team has approved the application specified in the ReleasePlan object.
+
+* *Create a `release` object:* The development team creates a Release object to references a specific Snapshot and ReleasePlan. It indicates the users' intent to operate on the Snapshot with the matched ReleasePlanAdmission.