Skip to content

Commit 744441b

Browse files
uvindrauvindra
authored
Merge pull request #1839 from abeykoon/add-automation-pipeline-docs
Add automation pipeline documentation
2 parents 7f38f97 + 60e3e17 commit 744441b

File tree

6 files changed

+262
-85
lines changed

6 files changed

+262
-85
lines changed

‎en/pe-docs/docs/devops/automation-pipelines/inbuilt-templates.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Inbuilt Pipeline Templates
2+
3+
When configuring a pipeline, you can use built-in pipeline templates provided by Choreo. These templates include pre-defined functionality that can simplify and accelerate pipeline creation.
4+
5+
[Choreo’s pipeline specification](https://github.com/wso2/choreo-pipeline-specification/tree/main/docs/specification) supports referencing these templates using the following syntax:
6+
7+
```yaml
8+
steps:
9+
- name: <step name>
10+
template: choreo/<template name>
11+
```
12+
Check [complete list of Choreo built-in templates](https://github.com/wso2/choreo-pipeline-specification/blob/main/docs/specification/built-in-templates.md)
13+
14+
15+
## Publish to Choreo Marketplace
16+
17+
At the end of all the resource provisioning steps in the automation pipeline, to publish metadata and credentials of provisioned resources to the Choreo marketplace, use inbuilt pipeline template `choreo/marketplace-publish@v1`. This template accepts an input argument called `resource` which needs to have a specific structure. Following is an example used to publish details of a provisioned MSSQL database.
18+
19+
{% raw %}
20+
```yaml
21+
steps:
22+
- name: publish-marketplace
23+
template: choreo/marketplace-publish@v1
24+
arguments:
25+
parameters:
26+
- name: resource
27+
yamlObject:
28+
name: "dev-mssql-db"
29+
version: 1.0.0
30+
category: Database
31+
description: MSSQL Database
32+
tags:
33+
- dev
34+
properties:
35+
databaseName: "{{steps.run-terraform.outputs.parameters.sql_database_name}}"
36+
sqlServerFQDN: "{{steps.run-terraform.outputs.parameters.sql_server_fqdn}}"
37+
connectionCredentials:
38+
- environments:
39+
- Development
40+
parameters:
41+
- key: ConnectionString
42+
value: "{{steps.run-terraform.outputs.parameters.connection_string}}"
43+
isSecret: false
44+
- key: DBUsername
45+
value: "{{steps.run-terraform.outputs.parameters.db_user_username}}"
46+
isSecret: true
47+
- key: DBUserPassword
48+
value: "{{steps.run-terraform.outputs.parameters.db_user_password}}"
49+
isSecret: true
50+
```
51+
{% endraw %}

‎en/pe-docs/docs/devops/automation-pipelines/introduction.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# What are Automation Pipelines
2+
3+
!!! info "Note"
4+
Automation pipeline capabilities are only available for private data plane organizations.
5+
6+
Choreo provides the capability to define and run any automated workflow with multiple steps within your IDP infrastructure. You can write your automation pipeline using the [Choreo pipeline syntax](https://github.com/wso2/choreo-pipeline-specification/tree/main/docs/specification) which is a simplified version of [Argo workflows syntax](https://argoproj.github.io/workflows/) syntax.

‎en/pe-docs/docs/devops/automation-pipelines/manage-automation-pipeline.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Create Automation Pipelines
2+
3+
Choreo allows to define automation pipelines at organization level. Follow these steps to create an automation pipeline.
4+
5+
1. Sign in to the [Choreo Console](https://console.choreo.dev/).
6+
2. Open **Platform Operations** perspective.
7+
3. In the left navigation menu, click **DevOps** and then click **Automation Pipelines**.
8+
4. Click **+ Create**.
9+
5. You can define an inline yaml or import from GitHub
10+
11+
## Define Pipeline within Choreo
12+
13+
This option is useful when you are testing a pipeline or if you like to let Choreo to keep your pipeline definitions.
14+
15+
1. Under `Define your Pipeline YAML`, click **Use YAML Editor**
16+
2. Provide a name by which you can identify the pipeline.
17+
3. Optionally provide a description
18+
4. Click **Create**
19+
20+
This pipeline definition is managed within Choreo. You can update it after defining as well.
21+
22+
## Import Pipeline from Git
23+
24+
If your organization manages pipelines in Git (GitHub, Bitbucket or GitLab), you can authorize and let Choreo to refer it. It could be a monolithic repository having multiple pipelines.
25+
26+
1. Under `Import Pipeline from Git` Click on the Git provider to authorize, and proceed with steps to grant access.
27+
2. You can select **Repository**, **Branch** and Specific **Pipeline YAML** file within a directory in the repository.
28+
3. Provide a name by which you can identify the pipeline.
29+
4. Optionally provide a description
30+
5. Click **Create**
31+
32+
Created pipelines will be listed in a tabular view.
33+
34+
35+
# Edit Automation Pipelines
36+
37+
Editing is only possible for pipelines defined within Choreo. Click **Edit Pipeline YAML** and in the right side panel that opens up you can edit the pipeline definition. You can view the pipeline definition in full-screen view as well by maximizing the panel.
38+
39+
!!! info "Note"
40+
Once a pipeline is edited, you cannot roll back to a previous version.
41+
42+
When a pipeline is defined in Git, it always uses the latest version from the repository at runtime.
43+
To update the pipeline, modify it in Git and trigger a new run.
44+
45+
# Delete Automation Pipelines
46+
47+
In the pipeline listing, under the **Actions** column, click the **Delete** icon. A confirmation pop-up will appear. Upon confirmation, the pipeline and all its associated runs will be permanently removed from Choreo.

‎en/pe-docs/docs/devops/automation-pipelines/run-automation-pipeline.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
After a pipeline is defined, you can execute it. The pipeline may need some inputs for it to run. Ensure you configure them correctly before triggering the run.
2+
3+
# Add Pipeline Variables and Secrets
4+
5+
The pipelines are defined at the organization level. Thus the variables defined for them are injected at the same level. Learn more on how to define a input variable in your pipeline at [Variables and Secrets - Choreo Pipelines Specification](https://github.com/wso2/choreo-pipeline-specification/blob/36f292dcb34bdcf2292f5c8537efc57ef5f5e5a4/docs/specification/environment-variables.md). Follow these steps to define inputs and their values for a given pipeline.
6+
7+
1. Click on **Pipeline Variables & Secrets** at upper right corner of the pipeline page.
8+
2. A panel will appear on the right side. To add a variable, under **Variables** section, add a new one by providing the Name and Value. The variable name must exactly match the name expected by the pipeline.
9+
3. If you have a secret to be added as a pipeline input, under **Secrets** section, add a new one by providing the Name and Value. The secret name must exactly match the name expected by the pipeline.
10+
11+
!!! info "Note"
12+
Once a secret is added, it is securely uploaded to the environment’s configured vault and injected into the pods running the workflow. You will not be able to view the secret value again after it is added.
13+
14+
## Manage Existing Pipeline Variables and Secrets
15+
16+
To update or remove a secret, click the three vertical dots in the upper-right corner of the variable box in the Choreo UI. From the menu, choose the appropriate action.
17+
18+
## Pipeline Parameters
19+
20+
Parameters are another type of variables referred by automation pipelines. Speciality of these variables is, before running the pipeline, user needs to choose a value for the parameters out of specified.
21+
22+
In pipeline definition, specify parameters like below.
23+
24+
```yaml
25+
parameters:
26+
- name: environment
27+
default: "Development"
28+
enum: ["Development", "Production"]
29+
displayName: "Environment"
30+
```
31+
32+
# Run Pipeline
33+
34+
Once the pipeline inputs are configured, click **Start New Run** to trigger a workflow run. The run will use the latest version of the pipeline definition along with the configured inputs.
35+
36+
Under the Runs table, a new row will appear displaying a unique **Run ID** for the triggered run. The following details are shown for each pipeline run:
37+
38+
1. **Version** – The version of the pipeline definition. This version is automatically incremented each time the pipeline definition is updated. It helps determine whether the run was triggered after a definition update.
39+
2. **Status** – The current status of the run:
40+
- **Successful**: All steps in the pipeline completed successfully.
41+
- **Failed**: One or more steps in the pipeline failed.
42+
- **Stopped**: The pipeline was manually stopped.
43+
3. **Start Time** – The timestamp when the pipeline run was triggered.
44+
4. **Duration** – The total time taken to execute the pipeline. If the pipeline runs for more than a predefined threshold (default 60 minutes), it will be automatically force-stopped by Choreo.
45+
46+
47+
## View Pipeline Logs
48+
49+
Click **View Logs** for a selected pipeline run in the Runs table. This opens a panel on the right, displaying logs for each step of the pipeline. You can close or maximize the log panel using the icons in the upper-right corner of the panel.
50+
51+
!!! info "Note"
52+
Choreo keeps pipeline logs maximum for 30 days.
53+
54+
## Stop a Pipeline Run
55+
56+
Once a pipeline run is triggered, click on **View Logs** and then in the log panel that opens to the right, click on **Stop Run**.

‎en/pe-docs/mkdocs.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,12 @@ nav:
106106
- Groups & Roles:
107107
- Configure Access Control: user-management/groups-and-roles/configure-access-control.md
108108
- DevOps:
109+
- Automation Pipelines:
110+
- What are Automation Pipelines: devops/automation-pipelines/introduction.md
111+
- Choreo Pipelines Specification: devops/automation-pipelines/specification.md
112+
- Manage Automation Pipelines: devops/automation-pipelines/manage-automation-pipeline.md
113+
- Run Automation Pipelines: devops/automation-pipelines/run-automation-pipeline.md
114+
- Inbuilt Pipeline Templates: devops/automation-pipelines/inbuilt-templates.md
109115
- CI Pipelines:
110116
- Configure CI Pipeline: devops/ci-pipelines/configure-ci-pipeline.md
111117
- Integrate Unit Tests into the CI Pipeline: devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md
@@ -263,4 +269,3 @@ extra:
263269
pe_docs_path: /choreo/docs/platform-engineer/
264270
#site_version: 1.0.0
265271
#base_path: http://localhost:8000
266-

0 commit comments

Comments
 (0)