From f3def9ff6ec9b2f4ce7b858d96f1f70d724b6cd3 Mon Sep 17 00:00:00 2001 From: arewm Date: Thu, 11 Jul 2024 16:04:15 -0400 Subject: [PATCH 1/3] migrate and update basic release documentation Signed-off-by: arewm --- .../create-release-plan-admission.adoc | 69 ++++++++++++++++++- .../releasing/create-release-plan.adoc | 64 ++++++++++++++++- .../advanced-how-tos/releasing/index.adoc | 20 +++--- 3 files changed, 142 insertions(+), 11 deletions(-) diff --git a/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan-admission.adoc b/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan-admission.adoc index 21bbbcc8..3fbae391 100644 --- a/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan-admission.adoc +++ b/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan-admission.adoc @@ -1 +1,68 @@ -= Creating a release plan admission \ No newline at end of file += 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: <.> + environment: <.> + origin: <.> + pipelineRef: <.> + policy: <.> + serviceAccount: <.> + +---- + ++ +<.> 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`. diff --git a/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan.adoc b/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan.adoc index ef095ea1..7c094b0a 100644 --- a/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan.adoc +++ b/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release-plan.adoc @@ -1 +1,63 @@ -= Creating a release plan \ No newline at end of file += 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: <.> + data: <.> + pipelineRef: <.> + serviceAccont: <.> + 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. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc b/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc index d425886a..e7c914b4 100644 --- a/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc +++ b/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 all within a single team. Especially within large organizations, there may be different teams building applications and deploying them. In these situations, the team managing the deployments (for example Site Reliability Engineers) will want to be able to automate the process of accepting content for release, validating that certain conditions are met, and the performing the release action -- 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 that 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. \ No newline at end of file +* *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. \ No newline at end of file From a065f507e3c7ede673fd9b10b2f54e6b9ede6a8e Mon Sep 17 00:00:00 2001 From: arewm Date: Fri, 12 Jul 2024 10:23:44 -0400 Subject: [PATCH 2/3] add documentation for manually creating Release CR Signed-off-by: arewm --- .../ROOT/pages/advanced-how-tos/_nav.adoc | 1 + .../releasing/create-release.adoc | 59 +++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release.adoc diff --git a/docs/modules/ROOT/pages/advanced-how-tos/_nav.adoc b/docs/modules/ROOT/pages/advanced-how-tos/_nav.adoc index 2003563f..b99e2053 100644 --- a/docs/modules/ROOT/pages/advanced-how-tos/_nav.adoc +++ b/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] diff --git a/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release.adoc b/docs/modules/ROOT/pages/advanced-how-tos/releasing/create-release.adoc new file mode 100644 index 00000000..9cfe706e --- /dev/null +++ b/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: <.> + namespace: dev-workspace <.> +spec: + releasePlan: <.> + snapshot: <.> + data: <.> +---- + + ++ +<.> 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. \ No newline at end of file From 36648cbb106ac8ad05bc9ceb6c8f062977dedd8a Mon Sep 17 00:00:00 2001 From: Andrew McNamara Date: Mon, 15 Jul 2024 08:22:00 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> --- docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc b/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc index e7c914b4..17ae1115 100644 --- a/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc +++ b/docs/modules/ROOT/pages/advanced-how-tos/releasing/index.adoc @@ -3,7 +3,7 @@ :numbered: :source-highlighter: highlightjs -The process of developing software rarely happens all within a single team. Especially within large organizations, there may be different teams building applications and deploying them. In these situations, the team managing the deployments (for example Site Reliability Engineers) will want to be able to automate the process of accepting content for release, validating that certain conditions are met, and the performing the release action -- while maintaining control of their pipelines and secrets. In {ProductName}, we call this process releasing 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. Two teams work together to release an application: @@ -17,7 +17,7 @@ Two teams work together to release an application: . 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. -. The development team creates a matching ReleasePlan (RP) configuration in their environment that is same as that of the Managed environment and attempts to release the application to production. +. 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