diff --git a/content/en/docs/decisions/0001-pipeline-tools.md b/content/en/docs/decisions/0001-pipeline-tools.md new file mode 100644 index 0000000..b7bec8c --- /dev/null +++ b/content/en/docs/decisions/0001-pipeline-tools.md @@ -0,0 +1,66 @@ +# CI/CD pipeline tools for composable pipeline + +## Context and Problem Statement + +In order to build a composable pipeline that provides a golden path and reusable components, we need to define the tools that will be used to execute the pipeline. + +ArgoCD is considered set in stone as the tool to manage the deployment of applications. However, the tools to compose and execute the pipeline are still up for debate. + +> Note: The pipeline will use many other tools to perform certain actions such as testing, building, and deploying. This ADR is focused on the tools that will be used to compose and execute the pipeline itself. + +In general, there are 3 decisions to make: + +- Do we want to have 2 separate tools for the execution and composition of the pipeline? +- What tools should we use to execute the pipeline? +- What tools should we use to compose the pipeline? + +## Decision Drivers + +- Level of Maturity +- Integration into ecosystem +- Community support +- Ability to execute code on a system (Workflow Runner) +- Ability to compose pipelines (Workflow Engine) + +## Considered Options + +- Argo Workflows + Events (as Runner and Engine) +- Forgejo Actions (as Runner and Engine) +- Dagger (as Engine) +- Shuttle (as Engine) + +## Decision Outcome + +TBD + +## Pros and Cons of the Options + +### Argo Workflows + Events (as Runner and Engine) + +- Good, because of tight integration with ArgoCD +- Good, because of the ability to trigger additional workflows based on events. +- Good, because of the level of maturity and community support. + +- Bad, because of the way how composition for pipelines works (based on Kubernetes CRDs). + - Templates must be available in the cluster where the pipelines are executed, so any imported templates must be applied into the cluster before the pipeline can be executed and cannot simply reference a repository. +- Bad, because of additional UI to manage the pipeline. +- Bad, because of the learning curve for developers. + +### Forgejo Actions (as Runner and Engine) + +- Good, because of tight integration with GitHub Actions providing a familiar interface for developers and a vast catalog of actions to choose from. +- Good, because of the ability to compose pipelines without relying on another tool. +- Neutral, because of the level of maturity - will require additional investments to provide a production-grade system. + +### Shuttle (as Engine) + +- Neutral, because of simplicity. +- Neutral, because of increased complexity by an additional tool. + +### Dagger (as Engine) + +- Good, because of Pipeline as Code approach. +- Good, because of vendoring of dependencies (no runtime dependency to another repository or network connectivity). +- Neutral, because of increased complexity by an additional tool. + +## More Information diff --git a/content/en/docs/decisions/README.md b/content/en/docs/decisions/README.md new file mode 100644 index 0000000..ae4dc5a --- /dev/null +++ b/content/en/docs/decisions/README.md @@ -0,0 +1,5 @@ +# ADRs + +Architecture Decision Records (ADRs) are a way to capture the important architectural decisions made during the development of a project. They are a way to document the context, the decision, and the consequences of the decision. They are a way to keep track of the architectural decisions made in a project and to communicate them to the team. + +The [Markdown Architectural Decision Records](https://adr.github.io/madr/) (MADR) format is a simple and easy-to-use format for writing ADRs in Markdown. diff --git a/content/en/docs/decisions/_adr-template.md b/content/en/docs/decisions/_adr-template.md new file mode 100644 index 0000000..fa87ccc --- /dev/null +++ b/content/en/docs/decisions/_adr-template.md @@ -0,0 +1,67 @@ + + +# {short title, representative of solved problem and found solution} + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.} + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. + + +### Consequences + +* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …} +* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …} +* … + + +### Confirmation + +{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.} + + +## Pros and Cons of the Options + +### {title of option 1} + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}