You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+9-11
Original file line number
Diff line number
Diff line change
@@ -5,16 +5,18 @@ Welcome to Piper! Piper is open source project that aimed at providing multibran
5
5
6
6
## Table of Contents
7
7
8
-
-[Getting Started](#getting-started)
9
-
-[Reporting Issues](#reporting-issues)
10
-
-[How to Contribute](docs/CONTRIBUTING.md#how-to-contribute)
11
-
-[License](#license)
8
+
-[Piper](#piper)
9
+
-[Table of Contents](#table-of-contents)
10
+
-[Getting Started](#getting-started)
11
+
-[Reporting Issues](#reporting-issues)
12
+
-[How to Contribute](#how-to-contribute)
13
+
-[License](#license)
12
14
13
15
## Getting Started
14
16
15
-
Piper configures a webhook in git provider and listens to the webhooks sends. It will create a Workflow CRD out of branches that contains `.workflows` folder.
16
-
This folder should contain declarations of the templates and main DAG that will be running.
17
-
Finally, it will submit the Workflow as a K8s resource in the cluster.
17
+
Piper configures a webhook in git provider and listens to the webhooks sends. It will create a Workflow CRD out of branches that contains `.workflows` folder.
18
+
This folder should contain declarations of the templates and main DAG that will be running.
19
+
Finally, it will submit the Workflow as a K8s resource in the cluster.
18
20
To access more detailed explanations, please navigate to the [Documentation site](https://piper.quickube.com).
The environment variables used by Piper to configure its functionality.
4
-
The helm chart populate them using [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file
3
+
Piper uses the following environment variables to configure its functionality.
4
+
The helm chart populates them using [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file
5
5
6
6
### Git
7
7
8
8
* GIT_PROVIDER
9
-
The git provider that Piper will use, possible variables: GitHub (will support bitbucket and gitlab)
9
+
The git provider that Piper will use, possible variables: GitHub . We plan to support Bitbucket and GitLab, as well.
10
10
11
11
* GIT_TOKEN
12
-
The git token that will be used.
12
+
The git token that will be used to connect to the git provider.
13
13
14
14
* GIT_ORG_NAME
15
15
The organization name.
16
16
17
17
* GIT_ORG_LEVEL_WEBHOOK
18
-
Boolean variable, whether to config webhook in organization level. default `false`
18
+
Boolean variable, whether to config webhook at the organization level. Defaults to `false`.
19
19
20
20
* GIT_WEBHOOK_REPO_LIST
21
21
List of repositories to configure webhooks to.
22
22
23
23
* GIT_WEBHOOK_URL
24
-
URL of piper ingress, to configure webhooks.
24
+
URL of Piper ingress, to configure webhooks.
25
25
26
26
* GIT_WEBHOOK_AUTO_CLEANUP
27
-
Will cleanup all webhook that were created with piper.
28
-
Notice that there will be a race conditions between pod that being terminated and the new one.
27
+
Boolean variable that, if true, will cause Piper to automatically cleanup all webhooks that it creates when they are no longer necessary.
28
+
Notice that there is a race condition between a pod that is being terminated and the new one being scheduled.
29
29
30
30
* GIT_ENFORCE_ORG_BELONGING
31
-
Boolean variable, whether to enforce organizational belonging of git event creator. default `false`
31
+
Boolean variable that, if true, will cause Piper to enforce organizational belonging of git event creator. Defaults to `false`.
32
32
33
33
* GIT_FULL_HEALTH_CHECK
34
-
Enables full health check of webhook. Full health check contains expecting and validating ping event from a webhook.
35
-
Doesn't work for bitbucket, because the API call doesn't exists.
36
-
34
+
Boolean variable that, if true, enables full health checks on webhooks. A full health check contains expecting and validating ping event from a webhook.
35
+
Doesn't work for Bitbucket, because the API call doesn't exist on that platform.
37
36
38
37
### Argo Workflows Server
38
+
39
39
* ARGO_WORKFLOWS_TOKEN
40
-
The token of Argo Workflows server.
40
+
This token is used to authenticate with the Argo Workflows server.
41
41
42
42
* ARGO_WORKFLOWS_ADDRESS
43
43
The address of Argo Workflows Server.
44
-
44
+
45
45
* ARGO_WORKFLOWS_CREATE_CRD
46
-
Whether to directly send Workflows instruction or create a CRD in the Cluster.
46
+
Boolean variable that deterines whether to directly send Workflows instructions or create a CRD in the Cluster.
47
47
48
48
* ARGO_WORKFLOWS_NAMESPACE
49
49
The namespace of Workflows creation for Argo Workflows.
@@ -52,9 +52,10 @@ The helm chart populate them using [values.yaml](https://github.com/quickube/pip
52
52
Used to configure Argo Workflows client with local kube configurations.
53
53
54
54
### Rookout
55
+
55
56
* ROOKOUT_TOKEN
56
57
The token used to configure Rookout agent. If not provided, will not start the agent.
57
-
* ROOKOUT_LABELS
58
-
The labels to label instances at Rookout, default to "service:piper"
58
+
* ROOKOUT_LABELS
59
+
The labels to label instances at Rookout, defaults to "service:piper"
59
60
* ROOKOUT_REMOTE_ORIGIN
60
-
The repo URL for source code fetching, default:"https://github.com/quickube/piper.git".
61
+
The repo URL for source code fetching, default:"https://github.com/quickube/piper.git".
Copy file name to clipboardExpand all lines: docs/configuration/health_check.md
+5-5
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,7 @@
1
1
## Health Check
2
2
3
-
Health check executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by `/healthz` endpoint:
3
+
The following examples shows a health check being executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by `/healthz` endpoint:
4
+
4
5
```yaml
5
6
livenessProbe:
6
7
httpGet:
@@ -18,14 +19,13 @@ The mechanism for checking the health of Piper is:
18
19
19
20
1. Piper set health status of all webhooks to not-healthy.
20
21
21
-
2. Piper requests ping from all the webhooks configured.
22
+
2. Piper requests ping from all the webhooks configured.
22
23
23
24
3. Git Provider send ping to `/webhook` endpoint, this will set the health status to `healthy` with timeout of 5 seconds.
24
25
25
26
4. Piper check the status of all webhooks configured.
Piper should be deployed in the cluster with Argo Workflows.
4
-
Piper will create a CRD that Argo Workflows will pick, so install or configure Piper to create those CRDs in the right namespace.
3
+
You must deploy Piper to a cluster with a pre-existing Argo Workflows deployment.
4
+
Piper will create a CRD that Argo Workflows will pick, so install or configure Piper to create those CRDs in the right namespace.
5
5
6
6
Please check out [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file of the helm chart configurations.
7
7
8
8
To add piper helm repo run:
9
+
9
10
```bash
10
11
helm repo add piper https://piper.quickube.com
11
12
```
12
13
13
14
After configuring Piper [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml), run the following command for installation:
Piper will create a webhook configuration for you, for the whole organization or for each repo you configure.
59
62
60
-
Configure `piper.webhook.url` the address of piper that exposed with ingress with `/webhook` postfix.
63
+
Configure `piper.webhook.url`with the address of Piper that you exposed using an Ingress or Service with `/webhook` postfix.
61
64
62
-
For organization level configure: `gitProvider.webhook.orgLevel` to `true`.
65
+
For organization level configuration: `gitProvider.webhook.orgLevel` to `true`.
63
66
64
-
For granular repo webhook provide list of repos at: `gitProvider.webhook.repoList`.
67
+
For granular repo webhook provide list of repos at: `gitProvider.webhook.repoList`.
65
68
66
-
Piper implements graceful shutdown, it will delete all the webhooks when terminated.
69
+
Piper implements graceful shutdown, it will delete all the webhooks when terminated.
67
70
68
71
#### Status check
69
72
70
-
Piper will handle status checks for you.
73
+
Piper will handle status checks for you.
71
74
It will notify the GitProvider for the status of Workflow for specific commit that triggered Piper.
72
75
For linking provide valid URL of your Argo Workflows server address at: `argoWorkflows.server.address`
73
76
@@ -81,4 +84,4 @@ To lint the workflow before submitting it, please configure the internal address
81
84
82
85
#### Skip CRD Creation (On development)
83
86
84
-
Piper can communicate directly to Argo Workflow using ARGO_WORKFLOWS_CREATE_CRD environment variable, if you want to skip the creation of CRD change `argoWorkflows.crdCreation` to `false`.
87
+
Piper can communicate directly to Argo Workflow using ARGO_WORKFLOWS_CREATE_CRD environment variable, if you want to skip the creation of CRD change `argoWorkflows.crdCreation` to `false`.
Piper is an open source project that aimed at providing multibranch pipeline functionality to Argo Workflows, allows users to create distinct Workflows based on Git branches. Supports GitHub and Bitbucket.
7
+
Welcome to Piper!
10
8
11
-
## General explanation
9
+
Piper is an open source project that aimed at providing multibranch pipeline functionality to Argo Workflows. This allows users to create distinct Workflows based on Git branches. We supports GitHub and Bitbucket.
To achieve multibranch pipeline functionality Piper will do the hard works for us.
18
-
At initialization, it will load all configuration and create a webhook in repository or organization scope.
19
-
Then each branch that have `.workflows` folder will create a Workflow CRD out of the files in this folder.
17
+
Piper handles the hard work of configuring multibranch pipelines for us! At initialization, it will load all configuration and create a webhook in repository or organization scope. Then, for each branch that has a `.workflows` folder, Piper will create a Workflow CRD out of the files in this folder. Finally, when Piper detects changes in the repository via the webhook, it triggers the workflows that match the branch and event.
Copy file name to clipboardExpand all lines: docs/usage/workflows_folder.md
+20-12
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,9 @@ We will explain each of the files that should be included in the `.workflows` fo
5
5
6
6
### triggers.yaml (convention name)
7
7
8
-
This file holds a list of triggers that will be executed `onStart` by `events` from specific `branches`.
8
+
This file holds a list of triggers that will be executed `onStart` by `events` from specific `branches`.
9
9
Piper will execute each of matching triggers, so configure it wisely.
10
+
10
11
```yaml
11
12
- events:
12
13
- push
@@ -17,50 +18,57 @@ Piper will execute each of matching triggers, so configure it wisely.
17
18
templates: ["templates.yaml"]
18
19
config: "default"
19
20
```
20
-
Can be found [here](https://github.com/quickube/piper/tree/main/examples/.workflows/triggers.yaml).
21
+
22
+
This example can be found [here](https://github.com/quickube/piper/tree/main/examples/.workflows/triggers.yaml).
21
23
22
24
In this example `main.yaml` will be executed as DAG when `push` or `pull_request.synchronize` events will be applied in `main` branch.
23
25
`onExit`will be executed `exit.yaml` when finished the workflow as exit handler.
24
26
25
-
26
27
`onExit`can overwrite the default `onExit` configuration from by reference existing DAG tasks as in the [example](https://github.com/quickube/piper/tree/main/examples/.workflows/exit.yaml).
27
28
28
29
`config`field used for workflow configuration selection. the default value is `default` configuration.
29
30
30
31
#### events
31
-
Events field used to terminate when the trigger will be executed. name of the event depends on the git provider.
32
+
33
+
Events field used to terminate when the trigger will be executed. name of the event depends on the git provider.
32
34
33
35
For instance, GitHub pull_request event have few action, one of them is synchronize.
34
36
35
37
#### branches
38
+
36
39
For which branch that trigger will be executed.
37
40
38
-
#### onStart
41
+
#### onStart
42
+
39
43
This [file](https://github.com/quickube/piper/tree/main/examples/.workflows/main.yaml) can be named as you wish and will be referenced in `triggers.yaml` file. It will define an entrypoint DAG that the Workflow will execute.
40
44
41
45
As a best practice, this file should contain the dependencies logic and parametrization of each of referenced templates. It should not implement new templates, for this, use template.yaml file.
42
46
43
-
#### onExit
47
+
#### onExit
48
+
44
49
This field used to pass verbose exitHandler to the triggered workflow.
45
50
It will override the default onExit from the provided `config` or the default `config`.
46
51
47
52
In the provided `exit.yaml` describes a DAG that will overwrite the default `onExit` configuration.
0 commit comments