Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

TEP-0048 Pipeline as code #341

Closed
wants to merge 1 commit into from
Closed

TEP-0048 Pipeline as code #341

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 215 additions & 0 deletions teps/0048-pipeline-as-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
---
status: proposed
title: Pipelines as Code
creation-date: '2020-01-20'
last-updated: '2020-01-20'
authors: [chmouel, afrittoli]
---

# TEP-0048: Pipeline as Code

- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Use Cases (optional)](#use-cases-optional)
- [Requirements](#requirements)
- [Proposal](#proposal)
- [Notes/Caveats (optional)](#notescaveats-optional)
- [Risks and Mitigations](#risks-and-mitigations)
- [User Experience (optional)](#user-experience-optional)
- [Performance (optional)](#performance-optional)
- [Design Details](#design-details)
- [Test Plan](#test-plan)
- [Design Evaluation](#design-evaluation)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
- [Upgrade & Migration Strategy (optional)](#upgrade--migration-strategy-optional)
- [References (optional)](#references-optional)

## Summary

The pipelines as code technique emphasizes that the configuration of delivering
pipelines that build, test and deploy our applications or infrastructure should
be treated as code; they should be placed under source control and modularized
in reusable components with automated testing and deployment.


## Motivation

The Tekton pipeline definitions are currently dissociated from a source code repository.
They may be located in the same repository as they code they should build, test and deploy,
but Tekton controller is not aware of them. Tekton expects the pipeline
definition to be deployed to a kubernetes cluster. Even when the Tekton
resources are deployed to the cluster from the Repository, it's not easy to test
changes to them, as their definition won't be updated until they are redeployed
to the cluster.

The reason for the current behaviour is that Tekton is non-prescriptive about how to set up
CI and CD pipelines. It aims to provide the building blocks for creating such pipelines and it leaves
it up to the user to decide how to integrate the pipeline in the overall workflow.

The use case of a single repo, running CI/CD jobs in isolation, is very common and
we wish to provide dedicated support for it, by providing an easy way for users to
chmouel marked this conversation as resolved.
Show resolved Hide resolved
run pipelines and tasks stored in a specific folder of the repo. The same tool can be used by
pipeline and task authors for quick testing and experimentation of their code.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

something else that might be interesting to mention as motivation is that this is a feature supported by so so many other CI/CD systems

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chmouel @FogDong I spent a bit of time looking at some other systems and whether or not most of them allow you to express both pipelines + triggering information as "code" (i.e. use version control as the source of truth) and it seems like most of them do

In this doc I took a really quick (and maybe inaccurate, plz add any corrections) look at:

  • Github actions
  • aws codepipeline
  • azure pipeline
  • jenkins (im the least sure i found the right info for this one)
  • circleci
  • travis
  • harness
  • bamboo
  • gitlab

I wanted to look at more, including Openshift pipelines ( + @vdemeester @imjasonh ?) but didnt get a chance!

plz feel free to add to this / expand on it / correct it / use anything useful in this TEP

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this @bobcatfish

Yeah a lot of this has been focused on Pull request CI (pre-merge) and not much on CD and post-merge CI.

I definitively think it's in scope, there is Jenkins-X who supports this too with lighthouse which I find interesting.

We will definitively needs to do a bit of thinking on how to integrate this with triggers.

(and fyi openshift BuildConfig, openshift pipelines doesn't support triggering as code)

### Goals

A way for users to add a tekton pipeline in a repository and getting it
automatically picked up for CI or CD.

> The solution should be as much as possible git hosting system agnostic.

### Non-Goals

- GitOps: Pipelines as Code does not take care of the [GitOps primitives](https://www.weave.works/technologies/gitops/), it
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it possible to be specific about which primitives it doesn't take care of?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, all of them, aka the TEP solely focuses on Pipeline def in the code being picked up. If it helps implementing GitOps operation/primites good but ain't a goal so far.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, there is quite a lot of definitions and interpretation of GitOPS, maybe PAC (pipelines as code) can help for only a subset of it but that's not the goal

simply applies tekton pipelines that may take care of some GitOps operation.

### Use Cases

- A User have a source code repository based on some Golang backend.
- User add a webhook (or other means) from its repository to pipelines as a code.
- The user add a directory called in `.tekton` with some pipeline definition for
testing its repository.
- User sending a PR with its change.
- The source code is automatically tested with the pipeline definition in `.tekton`.

Subsequently if the user needs to add another component to its source code (i.e:
a javascript based frontend) and need to make a changes to the pipeline
definition to do the testing of that new component, the change to the pipeline
would only apply for that Pull Request until it will be merged.
chmouel marked this conversation as resolved.
Show resolved Hide resolved

## Requirements

* We need to be able to test changes inside the `.tekton` folder as part of the PR sent.
* We should provide an easy way (single curl command and/or operator flag) to deploy Tekton with "tekton-as-code" support.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i dont exactly disagree with this requirement, but it seems to be specific to a particular solution (e.g. if we solved this by building support into triggers or pipelines, this might not be relevant?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true but work on "pipeline as code" can start / take place in parallel of getting this in triggers (or pipeline 😓 ). I think it's a requirement to "bootstrap" the work on the topic (giving time to implement this correctly if need be in tekton components).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @vdemeester

I don't think we need to make "triggering as code" a requirement for pipeline as code.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need to make "triggering as code" a requirement for pipeline as code.

can we expand on this a bit? i DO think that we should aim for this - @chmouel you pointed out some other solutions that do not allow triggering as code, but i strongly feel that this is where we want to get to (solutions that don't currently provide it i'm guessing would if they could - and probably will eventually)

maybe one way to avoid expanding the scope of what you are planning too far is if we could include a requirement that for whatever solutions we look at, we at least consider how they could be expanded to support triggering as code? <-- this depends on whether we want what we explore here to be the tekton recommended way of doing pipelines as code, or whether we want this to be one of many options that tekton provides. if this is "the one tekton way" then i think we need to be a lot more thorough

* We need assume single tenancy on the pipelines-as-code cluster.
* We assume single tenancy on the tekton-as-code cluster.
* We assume the user does not need access to the cluster.

## Proposal

Create an initial set of triggers templates for the users to install on its cluster.
Create an initial pipeline to test the change of a PR according to the templates in the `.tekton` project directory.

Provide an one-command way to install a version for code with "Tekton as code"
enabled that outputs a webhook URL and a secret that can be used by users to
enable Tekton as code for their repo, and a readonly tekton dashboard that can
be used to observe their pipeline runs.

### Notes/Caveats

With this initial proposal we have left out the notification part of Pipeline as
a code. To make it a 'complete package' we would want Pipeline as Code being
able to notify on PR the status of the `PipelineRun` execution, have the ability
to see the live execution of the Pipeline or when the pipeline finished to know
if it was succesfull or failed.

With this initial proposal we have focused on a PR based workflow and not on the
post-merge workflows. But there is nothing in this design that can't
address post-merge workflows.

We are not addressing here on how to check out private repositories and how to
get token from the Web VCS provider (ie: via Github or Gitlab [personal
token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
or via an [Oauth
application](https://docs.github.com/en/free-pro-team@latest/developers/apps))

### Risks and Mitigations


#### Logs retention

There is currently no way with Tekton to have the logs in different locations
which means we assume the logs will be kept as long as the `Pipelinerun` is
still in the cluster.

### User Experience

* A user deploy with a single command the pipelines as code template and retrieve
the ingress url of the eventlistenner webhook url.
* The user configure the webhook URL in GitHub or other web vcs provider.
* A user add a tekton template in the `.tekton` directory of its repository.
* User sends a PR.
* Pipeline as code start applying the template located in the `.tekton`
directory
* User is able to watch the pipeline execution status via `tkn` or `dashboard`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious how the authors visualize this happening on the dashboard. Right now there's not a lot of filters other than namespaces and labels. Are these filters going to be used to find different variants of same pipeline in the same UI or would this involve some restructuring of the UI as well?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We chatted among RHT colleagues on how we wanted to present this if we wanted to expose pipeline as a code on the openshift console, which probably would be a bit the same for dashboard.

I would imagine, there would be a repository first view, where each repository can have a pipeline as a code status, with the different runs and link to logs.

Not so different from what we have on github actions and other CI i guess.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it would be a bit of a leap for the tekton dashboard to become aware of repositories - but it would be nice! reminds me of tektoncd/dashboard#1612 which is suggesting a grouping mechanism that could group triggering info + pipelines - i think @dibyom might be planning to look into proposing a grouping mechanism like this

* Pipeline as code, succeed or fail accordingly.

### Performance (optional)

<!--
Consideration about performance.
What impact does this change have on the start-up time and execution time
of task and pipeline runs? What impact does it have on the resource footprint
of Tekton controllers as well as task and pipeline runs?

Consider which use cases are impacted by this change and what are their
performance requirements.
-->

## Design Details


## Test Plan

<!--
**Note:** *Not required until targeted at a release.*

Consider the following in developing a test plan for this enhancement:
- Will there be e2e and integration tests, in addition to unit tests?
- How will it be tested in isolation vs with other components?

No need to outline all of the test cases, just the general strategy. Anything
that would count as tricky in the implementation and anything particularly
challenging to test should be called out.

All code is expected to have adequate tests (eventually with coverage
expectations).
-->

## Design Evaluation
<!--
How does this proposal affect the reusability, simplicity, flexibility
and conformance of Tekton, as described in [design principles](https://github.com/tektoncd/community/blob/master/design-principles.md)
-->

## Drawbacks

<!--
Why should this TEP _not_ be implemented?
-->

## Alternatives

Instead of having a Tekton as a code task with a binary doing the 'work' we may
want to do this directly in triggers.

This is something that is possible to do currently but from my experience working
on POC and the future
Comment on lines +185 to +191
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will need more detailled alternative approach here at some point

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What kind of details would you like to see ? Alternative implementation or alternative design achieving tekton as code ?

The alternative design is I guess an ad-hoc approach, like the way we do right know which is not really tekton as code i guess.


## Infrastructure Needed (optional)

<!--
Use this section if you need things from the project/SIG. Examples include a
new subproject, repos requested, github details. Listing these here allows a
SIG to get the process for these resources started right away.
-->

## Upgrade & Migration Strategy (optional)

<!--
Use this section to detail wether this feature needs an upgrade or
migration strategy. This is especially useful when we modify a
behavior or add a feature that may replace and deprecate a current one.
-->

## References (optional)

* A POC for pipelines as code :

https://github.com/chmouel/tekton-asa-code

An experiementation in python for the different techniques to achieve pipelines as a code.