Skip to content

Getting Started

Installation

You must deploy Piper to a cluster with a pre-existing Argo Workflows deployment. Piper will create a CRD that Argo Workflows will pick up, so install or configure Piper to create those CRDs in the right namespace.

Please check out values.yaml file of the helm chart configurations.

To add piper helm repo run:

helm repo add piper https://piper.quickube.com

After configuring Piper values.yaml, run the following command for installation:

helm upgrade --install piper piper/piper \
-f YOUR_VALUES_FILE.yaml

Required Configuration

Ingress

Piper works best when it is able to listen to webhooks from your git provider. Expose Piper using an ingress or service, then provide the address to piper.webhook.url as follows: https://PIPER_EXPOSED_URL/webhook

Refer to values.yaml for more information.

Git

Piper will use git to fetch the .workflows folder and receive events using webhooks.

To pick which git provider you are using provide gitProvider.name configuration in helm chart (Currently we only support GitHub and Bitbucket).

Also configure your organization (GitHub), workspace (Bitbucket) or group (GitLab) name using gitProvider.organization.name in helm chart.

Git Token Permissions

The token should have access to create webhooks and read repository content. For GitHub, configure admin:org and write:org permissions in Classic Token. For Bitbucket, configure Repositories:read, Webhooks:read and write and Pull requests:read permissions (for multiple repos use workspace token). For Gitlab, configure read_api, write_repository and api (for multiple repos use group token with owner role).

Token

The git token should be passed as secret in the helm chart at gitProvider.token. The token can be passed as parameter via helm install command using --set piper.gitProvider.token=YOUR_GIT_TOKEN

Alternatively, you can use an already existing secret by configuring piper.gipProvider.existingSecret. The key should be named token token. You can create a Secret using this command:

kubectl create secret generic piper-git-token --from-literal=token=YOUR_GIT_OKEN

Webhook creation

Piper will create a webhook configuration for you, either for the whole organization or for each repo you configure.

Configure piper.webhook.url with the address of Piper that you exposed using an Ingress or Service with /webhook postfix.

For organization level configuration: gitProvider.webhook.orgLevel to true.

For granular repo webhook provide list of repos at: gitProvider.webhook.repoList.

Piper implements a graceful shutdown; it will delete all the webhooks when terminated.

Status check

Piper will handle status checks for you. It will notify the GitProvider of the status of the Workflow for the specific commit that triggered Piper. For linking provide valid URL of your Argo Workflows server address at: argoWorkflows.server.address

Argo Workflow Server (On development)

Piper will use the REST API to communicate with the Argo Workflows server for linting or creating workflows.

To lint the workflow before submitting it, please configure the internal address of Argo Workflows server (for example, argo-server.workflows.svc.cluster.local) in the field: argoWorkflows.server.address. Argo will need a token to authenticate. Please provide the secret in argoWorkflows.server.token. It is better to pass it as a reference to a secret in the field argoWorkflows.server.token.

Skip CRD Creation (On development)

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.