diff --git a/docs/modules/ROOT/nav-how-to-guides.adoc b/docs/modules/ROOT/nav-how-to-guides.adoc index 540aca85..1de1ab8a 100644 --- a/docs/modules/ROOT/nav-how-to-guides.adoc +++ b/docs/modules/ROOT/nav-how-to-guides.adoc @@ -24,6 +24,9 @@ *** xref:how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc[Downloading your SLSA provenance] *** xref:how-to-guides/Secure-your-supply-chain/proc_java_dependencies.adoc[Configuring dependencies rebuild for Java apps in the CLI] ** xref:how-to-guides/proc_managing-compliance-with-the-enterprise-contract.adoc[Managing compliance with the Enterprise Contract] +** xref:how-to-guides/con_release_application.adoc[Releasing an application] +*** xref:how-to-guides/proc_release_plan.adoc[Creating a `releasePlan` object] +** xref:how-to-guides/proc_managed_services_onboarding.adoc[Managed services team onboarding] ** xref:how-to-guides/proc_delete_application.adoc[Deleting an application] @@ -35,6 +38,4 @@ Commenting these out per HACDOCS-425 and -414 //// Commenting out this xref for now because Burr said this page is currently unsupported. --Christian (csears@redhat.com), 2/16/2023 -** xref:cli/proc_release_application.adoc[Releasing an application] -** xref:how-to-guides/proc_managed_services_onboarding.adoc[CLI: Managed services team onboarding] //// diff --git a/docs/modules/ROOT/pages/how-to-guides/con_release_application.adoc b/docs/modules/ROOT/pages/how-to-guides/con_release_application.adoc new file mode 100644 index 00000000..e1810e9a --- /dev/null +++ b/docs/modules/ROOT/pages/how-to-guides/con_release_application.adoc @@ -0,0 +1,23 @@ += Releasing an application +:icons: font +:numbered: +:source-highlighter: highlightjs + +Two teams work together to release an application: + +* *Development team* - The team that develops and supports the application in a pre-production environment. + +* *Managed environment team* - The team that supports the production instance of that application. + +image::managed_environment.png[alt=Managed 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. + +[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. + +[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. + +[4] The Managed environment team validates the initial release and configures a traffic gateway, which allows external traffic to the application. + +.Next steps +link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/proc_release_plan/[Creating a `releasePlan` object] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-to-guides/proc_managed_services_onboarding.adoc b/docs/modules/ROOT/pages/how-to-guides/proc_managed_services_onboarding.adoc index cc31752d..2345d3a7 100644 --- a/docs/modules/ROOT/pages/how-to-guides/proc_managed_services_onboarding.adoc +++ b/docs/modules/ROOT/pages/how-to-guides/proc_managed_services_onboarding.adoc @@ -3,101 +3,72 @@ When an application is ready for release, the Development team contacts the Mana The Managed Environment team creates the following objects on the Managed workspace: -* *ReleaseStrategy* - The `ReleaseStrategy` object, created by the Managed Environment team, specifies the release pipeline that the system uses to release an application in their environment, as well as which enterprise contract the system must first validate. - -* *ReleasePlanAdmission* - The Managed Environment team creates the ReleasePlanAdmission object in response to the `ReleasePlan` object created by the development team. It indicates that the Managed Environment team has approved the xref:how-to-guides/proc_release_application.adoc#_creating_a_releaseplan_object[`ReleasePlan`] object for an application. It also specifies a `ReleaseStrategy` to be used for that particular Application and, optionally, an Environment to which the application will be deployed. +* *ReleasePlanAdmission* - 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 link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/proc_release_plan/[ReleasePlan] object. * *`copy-application.sh`* - The Managed Environment team runs the `copy-application.sh` script by defining the application name before releasing an application to production. The script copies the application and all of its components from the Development to the Managed workspace. As a result, when releasing an application to production, the Managed Environment team uses the application on its workspace rather than the one on the Developer workspace. Additionally, if the Development team adds a new component to the application on their workspace, they must notify the Managed Environment team. So they can run the `copy-application.sh` script again to ensure that the managed workspace has the most recent version of the application. -== The `ReleaseStrategy` object +== Creating a `ReleasePlanAdmission` object .*Prerequisites* * An existing Development and Managed workspace. -* An existing `ReleasePlan` object. +* An existing `ReleasePlan` object in the Development workspace. .*Procedures* -* Create a release_strategy.yaml object by running: +. Create a `ReleasePlanAdmission.yaml` object locally. + -[source,] ----- -oc apply -f releasestrategy.yaml -n managed ----- - -+ -*Example release_strategy.yaml object* +*Example `ReleasePlanAdmission.yaml` object* + [source,yaml] ---- apiVersion: appstudio.redhat.com/v1alpha1 -kind: ReleaseStrategy <.> +kind: ReleasePlanAdmission metadata: - name: strategy <.> - namespace: managed-environment <.> + name: sre-production <.> + namespace: managed-workspace <.> spec: - pipeline: release <.> - bundle: quay.io/{ProductName}-release/release-pipeline:main <.> - policy: policy <.> ----- -<.> The name of the resource that the Managed Environment team creates. -<.> The name of the release strategy. -<.> The name of the managed environment to which the system deploys an application. -<.> The name of the pipeline that the system uses when releasing an application to a managed environment. -<.> The URL to the release pipeline bundle. -<.> The URL to the enterprise contract policy config file which stores the policies and collections. The system validates the enterprise contract policies before releasing an application to production. - -== The ReleasePlanAdmission object - -.*Prerequisites* -* An existing Development and Managed workspace. - -* An existing `ReleasePlan` object in the Development workspace. - -* An existing `ReleaseStrategy` object. - -.*Procedures* - - -* Create a `release_plan_admission.yaml` object by running: + applications: + - demo-app <.> + data: <.> + environment: <.> + origin: <.> + pipelineRef: <.> + policy: <.> + serviceAccount: <.> -+ -[source,] ----- -oc apply -f releaseplanadmission.yaml -n managed ---- + -NOTE: The `release_plan_admission.yaml` represents the reciprocal link to the release_plan.yaml objects created by the development team. +<.> 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. + -*Example `release_plan_admission.yaml` object* +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,yaml] +[source,shell] ---- -apiVersion: appstudio.redhat.com/v1alpha1 -kind: ReleasePlanAdmission <.> -metadata: - name: sre-production <.> - namespace: managed <.> -spec: - application: demo-app <.> - environment: sre-production <.> - origin: <.> -releaseStrategy: <.> +oc apply -f ReleasePlanAdmission.yaml -n managed ---- -<.> The name of the resource that the Managed Environment team creates. -<.> The name of the release plan. -<.> The Managed Environment team’s workspace. -<.> The name of the application that you want to deploy to the managed workspace. -<.> The workspace from which the application updates are allowed to be received in the Managed workspace. -<.> The workspace on which the application updates are received. This workspace is created by the Development team. -<.> The release strategy that you defined in the `ReleaseStrategy` object. + +.*Verification* + +. On the Trusted Application Pipeline console, select the *Release services* > *Release plan admission* tab. +. Review the Release plan admission object that you just added. Using the Release plan admission tab, you can update or delete the selected Release plan object. == The `copy-application.sh` script @@ -106,18 +77,17 @@ releaseStrategy: <.> * An existing Development and Managed workspace. +* Download link:https://github.com/redhat-appstudio/release-service-utils/blob/main/copy-application.sh[./copy-application.sh] script. + .*Procedures* * Run the following command to copy the application from the development workspace to the managed workspace: + -[source,] +[source,shell] ---- ./copy-application.sh -a / ---- + -======= -NOTE: Run `./{ProductName}copy.sh --help` to review all the help options of the script. -======= - +To show the command usage information, run the `./copy-application.sh --help` command. diff --git a/docs/modules/ROOT/pages/how-to-guides/proc_release_application.adoc b/docs/modules/ROOT/pages/how-to-guides/proc_release_application.adoc deleted file mode 100644 index 0d602431..00000000 --- a/docs/modules/ROOT/pages/how-to-guides/proc_release_application.adoc +++ /dev/null @@ -1,186 +0,0 @@ -= Releasing an application -:icons: font -:numbered: -:source-highlighter: highlightjs - -Two teams work together to release an application: - -* *Development team* - The team that develops and supports the application in a pre-production environment. - -* *Managed environment team* - The team that supports the production instance of that application. - -image::managed_environment.png[alt=Managed 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. - -[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. - -[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. - -[4] The Managed environment team validates the initial release and configures a traffic gateway, which allows external traffic to the application. - -== Tasks that the Development and Managed environment teams complete - -To release an application to a managed environment: - -. The development team creates a xref:how-to-guides/proc_release_application.adoc#_creating_a_releaseplan_object[`ReleasePlan`] object in the developer workspace. The `ReleasePlan` object includes a reference to the application that the development team wants to release, along with the namespace and workspace where the application is suppose to release. - -. The Managed environment team creates a xref:how-to-guides/proc_release_application.adoc#_creating_a_releasestrategy_object[`ReleaseStrategy`] object to ensure that the release of an application meets link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/proc_managing-compliance-with-the-enterprise-contract[enterprise contract]. - -. The Managed environment team creates a xref:how-to-guides/proc_release_application.adoc#_creating_a_releaseplanadmission_object[`ReleasePlanAdmission`] object in the managed workspace. - -+ -The `ReleasePlanAdmission` indicates that the Managed environment team has approved the `ReleasePlan` for an application. The `ReleasePlanAdmission` also refers to the `ReleaseStrategy`, which ensures that the application's release meets security standards. - -+ -NOTE: The `ReleasePlan` and `ReleasePlanAdmission` is an agreement between the development and the Managed environment teams. This agreement indicates that the Managed environment team accepts the release of an application into the managed workspace and intends to support it. - -== Creating a `ReleasePlan` object - -.*Prerequisites* -* You have an existing Development and Managed workspace. -* Ensure you have installed oc. - -.*Procedures* - -. In the development workspace, create a release_plan.yaml object by running: - -+ -[source,kubernetes] ----- -oc apply -f releaseplan.yaml -n dev ----- - -+ -*Example `release_plan.yaml` object* - -+ -[source,yaml] ----- -apiVersion: appstudio.redhat.com/v1alpha1 -kind: ReleasePlan <1> -metadata: - labels: - release.appstudio.openshift.io/auto-release: 'true' - name: sre-production <2> - namespace: dev-workspace <3> -spec: - application: demo-app <4> - displayName: SRE Production <5> - target: - namespace: managed-workspace <6> ----- - -+ -<1> The name of the resource that you are creating. -<2> The name of the release plan. -<3> The development team's workspace. -<4> The name of the application that you want to deploy to the managed workspace. -<5> The -<6> 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) - -.*Verification* - -. Browse the application you are creating. -. Select the *Overview* tab to visualize the Application workflow. If you have successfully added a Managed environment, the system displays it at the end of the Application workflow. - -== Creating a `ReleaseStrategy` object - -.*Prerequisites* - -* You have an existing Development and Managed workspace. -* Ensure you have installed oc. -* Ensure you have downloaded your docker config json file from Quay and placed it in the /docker.config directory. -* An existing `ReleasePlan` object. - -.*Procedures* - -. Create a release_strategy.yaml object by running: - -+ -[source,kubernetes] ----- -oc apply -f releasestrategy.yaml -n managed ----- - -+ -*Example `release_strategy.yaml` object* - -+ -[source,yaml] ----- -apiVersion: appstudio.redhat.com/v1alpha1 -kind: ReleaseStrategy <.> -metadata: - name: strategy <.> - namespace: managed-environment <.> -spec: - pipeline: release <.> - bundle: quay.io/{ProductName}-release/release-pipeline:main <.> - policy: policy <.> - serviceAccount: service-account <.> ----- - -+ -<.> The name of the resource the Environment team creates. -<.> The name of the release strategy. -<.> The name of the managed environment to which the system deploys an application. -<.> The name of the pipeline that the system uses when releasing an application to a managed environment. -<.> The link to the release pipeline bundle. -<.> The enterprise contract policy against which the system validates an application before releasing it to production. -<.> The name of the link:https://github.com/scoheb/{ProductName}-demos/blob/main/m7/release/managed-workspace/service_account.yaml[`serviceAccount`] resource in the Managed workspace. This `serviceAccount` resource has link:https://kubernetes.io/docs/concepts/configuration/secret/#secret-types[secrets] that link:https://tekton.dev/vault/pipelines-v0.15.2/auth/[Tekton] uses to provide authentication to different tasks in the pipeline. - -== Creating a `ReleasePlanAdmission` object - -.*Prerequisites* - -* You have an existing Development and Managed workspace. -* An existing `ReleasePlan` object. -* An existing `ReleaseStrategy` object. - - -.*Procedures* - -. Create a release_plan_admission.yaml object by running: - -+ -[source,kubernetes] ----- -oc apply -f releaseplanadmission.yaml -n managed ----- - -+ -NOTE: The release_plan_admission.yaml represents the reciprocal link to the release_plan.yaml objects created by the development team. - -+ -*Example `release_plan_admission.yaml` object* - -+ -[source,yaml] ----- -apiVersion: appstudio.redhat.com/v1alpha1 -kind: ReleasePlanAdmission <1> -metadata: - name: sre-production <2> - namespace: managed <3> -spec: - application: demo-app <4> - environment: sre-production <5> - origin: - workspace: <6> - namespace: <7> - releaseStrategy: <8> ----- - -+ -<1> The name of the resource created by the Environment team. -<2> The name of the release plan. -<3> The Managed environment team's workspace. -<4> The name of the application that you want to deploy to the managed workspace. -<5> The -<6> The workspace from which the application updates are allowed to be received in the Managed workspace. -<7> The workspace on which the application updates are received. This workspace is created by the Development team. -<8> The release strategy. - -// How integration controller uses the release plan and will creates a release object ... ships of the content -// Alternatively you can add optional instructions to create a release manually. diff --git a/docs/modules/ROOT/pages/how-to-guides/proc_release_plan.adoc b/docs/modules/ROOT/pages/how-to-guides/proc_release_plan.adoc new file mode 100644 index 00000000..ed84f187 --- /dev/null +++ b/docs/modules/ROOT/pages/how-to-guides/proc_release_plan.adoc @@ -0,0 +1,59 @@ += 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 link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/getting_started_in_cli/[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' + name: sre-production <.> + namespace: dev-workspace <.> +spec: + application: demo-app <.> + data: <.> + pipelineRef: <.> + serviceAccount: <.> + 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: 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* + +. On the Trusted Application Pipeline console, 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. + +.Next steps +link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/proc_managed_services_onboarding.adoc/[Managed services team onboarding] \ No newline at end of file