Skip to content

Commit e0317c4

Browse files
arewmarewm
authored
Merge pull request #85 from arewm/migrate-advanced-how-tos
Migrate and update basic release documentation
2 parents 929c3d0 + 36648cb commit e0317c4

File tree

5 files changed

+202
-11
lines changed

5 files changed

+202
-11
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@
66
** xref:advanced-how-tos/releasing/index.adoc[Releasing an application]
77
*** xref:advanced-how-tos/releasing/create-release-plan.adoc[Creating a release plan]
88
*** xref:advanced-how-tos/releasing/create-release-plan-admission.adoc[Creating a release plan admission]
9+
*** xref:advanced-how-tos/releasing/create-release.adoc[Creating a release]
910
** xref:advanced-how-tos/managing-multiple-versions.adoc[Managing multiple software versions]
1011
** 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

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,68 @@
1-
= Creating a release plan admission
1+
= Creating a release plan admission
2+
3+
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.
4+
5+
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.
6+
7+
== Creating a `ReleasePlanAdmission` object
8+
9+
.*Prerequisites*
10+
11+
* An existing Development and Managed workspace.
12+
13+
* An existing `ReleasePlan` object in the Development workspace.
14+
15+
.*Procedures*
16+
17+
. Create a `ReleasePlanAdmission.yaml` object locally.
18+
19+
+
20+
*Example `ReleasePlanAdmission.yaml` object*
21+
22+
+
23+
[source,yaml]
24+
----
25+
apiVersion: appstudio.redhat.com/v1alpha1
26+
kind: ReleasePlanAdmission
27+
metadata:
28+
name: sre-production <.>
29+
namespace: managed-workspace <.>
30+
spec:
31+
applications:
32+
- demo-app <.>
33+
data: <key> <.>
34+
environment: <sre-production> <.>
35+
origin: <dev-workspace> <.>
36+
pipelineRef: <pipeline_ref> <.>
37+
policy: <policy> <.>
38+
serviceAccount: <service-account> <.>
39+
40+
----
41+
42+
+
43+
<.> The name of the release plan admission.
44+
<.> The Managed environment team's workspace.
45+
<.> A list of applications that you want to enable to be deployed in the managed workspace.
46+
<.> Optional: An unstructured key used for providing data for the managed Pipeline.
47+
<.> 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.
48+
<.> The development team workspace where the application is defined.
49+
<.> Reference to the Pipeline to be executed by the release service.
50+
<.> The enterprise contract policy against which the system validates an application before releasing it to production.
51+
<.> 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.
52+
53+
+
54+
NOTE: The ReleasePlanAdmission.yaml represents the reciprocal link to the ReleasePlan.yaml objects created by the development team.
55+
56+
. In the Managed workspace, apply the `ReleasePlanAdmission.yaml` file and add the resource to your cluster by running the following command:
57+
58+
+
59+
[source,shell]
60+
----
61+
oc apply -f ReleasePlanAdmission.yaml -n managed
62+
----
63+
64+
.*Verification*
65+
66+
. In the {ProductName} UI, select the *Release services* > *Release plan admission* tab.
67+
. Review the RPA object that you just added. Using the Release plan admission tab, you can update or delete the selected Release plan object.
68+
. 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

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,63 @@
1-
= Creating a release plan
1+
= Creating a release plan
2+
3+
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.
4+
5+
== Creating a `ReleasePlan` object
6+
7+
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.
8+
9+
.*Prerequisites*
10+
11+
* You have an existing Development workspace.
12+
* Ensure you have installed `oc`.
13+
* You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
14+
15+
.*Procedures*
16+
17+
. Create a `ReleasePlan.yaml` object locally.
18+
19+
+
20+
*Example `ReleasePlan.yaml` object*
21+
22+
+
23+
[source,yaml]
24+
----
25+
apiVersion: appstudio.redhat.com/v1alpha1
26+
kind: ReleasePlan
27+
metadata:
28+
labels:
29+
release.appstudio.openshift.io/auto-release: 'true'
30+
release.appstudio.openshift.io/standing-attribution: 'true'
31+
release.appstudio.openshift.io/releasePlanAdmission: 'rpa-name' <.>
32+
name: sre-production <.>
33+
namespace: dev-workspace <.>
34+
spec:
35+
application: <application-name> <.>
36+
data: <key> <.>
37+
pipelineRef: <pipeline-ref> <.>
38+
serviceAccont: <service-account> <.>
39+
target: managed-workspace <.>
40+
----
41+
42+
+
43+
<.> The name of the release plan.
44+
<.> The development team's workspace.
45+
<.> The name of the application that you want to deploy to the managed workspace.
46+
<.> Optional: The name of the RPA to use if more than one RPA references the specified application.
47+
<.> Optional: An unstructured key used for providing data for the managed Pipeline.
48+
<.> Optional: Reference to the Pipeline to be executed by the release service.
49+
<.> 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.
50+
<.> 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)
51+
52+
. In the development workspace, apply the `ReleasePlan.yaml` file and add the resource to your cluster by running the following command:
53+
54+
+
55+
[source,shell]
56+
----
57+
$ oc apply -f ReleasePlan.yaml -n dev
58+
----
59+
60+
.*Verification*
61+
62+
. In the {ProductName} UI, select the *Release services* > *Release plan* tab.
63+
. 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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
= Creating a release
2+
3+
A Release CR is created to submit a specific Application Snapshot to be processed according to teh referenced ReleasePlan.
4+
5+
== Creating a `Release` object
6+
7+
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.
8+
9+
.*Prerequisites*
10+
11+
* You have an existing Development workspace.
12+
* Ensure you have installed `oc`.
13+
* You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
14+
* You have completed the steps for creating a ReleasePlanAdmission and a matching ReleasePlan.
15+
16+
.*Procedures*
17+
18+
. Create a `Release.yaml` object locally.
19+
20+
+
21+
*Example `Release.yaml` object*
22+
23+
+
24+
[source,yaml]
25+
----
26+
apiVersion: appstudio.redhat.com/v1alpha1
27+
kind: Release
28+
metadata:
29+
name: <name-of-this-release> <.>
30+
namespace: dev-workspace <.>
31+
spec:
32+
releasePlan: <release-plan-name> <.>
33+
snapshot: <application-snapshot-name> <.>
34+
data: <key> <.>
35+
----
36+
37+
38+
+
39+
<.> The name of the release.
40+
<.> The development team's workspace.
41+
<.> The name of the release plan specifying the pipeline to run.
42+
<.> The name of the application snapshot that you want to release.
43+
<.> Optional: An unstructured key used for providing data for the managed Pipeline.
44+
45+
. In the development workspace, apply the `Release.yaml` file and add the resource to your cluster by running the following command:
46+
47+
+
48+
[source,shell]
49+
----
50+
$ oc apply -f Release.yaml -n dev
51+
----
52+
53+
.*Verification*
54+
55+
. In the {ProductName} UI, select the *Applications* tab
56+
. Click on the application that is being released
57+
. Click on the *Releases* tab
58+
. See the recent releases that have been created for the application.
59+
. 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

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,26 @@
33
:numbered:
44
:source-highlighter: highlightjs
55

6-
Two teams work together to release an application:
6+
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.
77

8-
* *Development team* - The team that develops and supports the application in a pre-production environment.
8+
Two teams work together to release an application:
99

10-
* *Managed environment team* - The team that supports the production instance of that application.
10+
* *Development team* - The team that develops and supports the application. This may include testing or deploying it in a pre-production environment.
1111
12-
image::managed_environment.png[alt=Managed Environment]
12+
* *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).
1313
14-
[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.
14+
.Procedure
1515

16-
[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.
16+
. 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.
1717

18-
[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.
18+
. 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.
1919

20-
[4] The Managed environment team validates the initial release and configures a traffic gateway, which allows external traffic to the application.
20+
. 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.
2121

2222
.Next steps
2323

2424
* *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.
2525
26-
* *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.
26+
* *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.
27+
28+
* *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.

0 commit comments

Comments
 (0)