Skip to content

Latest commit

 

History

History
55 lines (47 loc) · 5.68 KB

design-principles.md

File metadata and controls

55 lines (47 loc) · 5.68 KB
Raw

Tekton Design Principles

API conventions

  1. Changes to Tekton APIs, especially CRD (Custom Resource Definition) based APIs should comply with Kubernetes API Conventions.

Reusability

  1. Existing features should be reused when possible instead of adding new ones. Before proposing a feature, try solving the problem with existing features first.
  2. Prefer providing a solution in the Catalog when possible to adding a feature.
  3. At authoring time (i.e. when authoring Pipelines and Tasks), authors should be able to include anything that is required for every execution of the Task or Pipeline. At run time (i.e. when invoking a Pipeline or Task via PipelineRun or TaskRun), users should be able to control execution as needed by their context without having to modify Tasks and Pipelines.
  4. In TEPs, discuss how a new feature affects the reusability of Tasks and Pipelines.

Simplicity

  1. Tekton should contain only the bare minimum and simplest features needed to meet the largest number of CI/CD use cases.
  2. Prefer a simple solution that solves most use cases to a complex solution that solves all use cases (can be revisited later).
  3. New features should be consistent with existing components, in structure and behavior, to make learnability, trialability and adoption easy.
  4. Any new feature should have been previously discussed and agreed upon in a Tekton Enhancement Proposal.
  5. In TEPs, demonstrate that the proposed feature is absolutely necessary. What’s the current experience without the feature and how challenging is it?

Flexibility

  1. Tekton has a ton of flexibility, which means a lot of things can be implemented by some kind of plugin, such as using CustomTasks or in the Step level. When considering adding something to Tekton itself, we should consider and exhaust all opportunities to implement it using one of the existing plugin mechanisms.
  2. To keep Tekton flexible, Tekton should avoid being opinionated in the Task and Pipeline API, and Tasks (e.g. from the catalog) should be a valid place where to be specific and opinionated.
  3. When a specific choice (tool, resource, language, etc) has to be made at the Task or Pipeline levels, users should be able to extend it to add their own choices.
  4. When a specific choice is in consideration, evaluate what we’re coupling Tekton to and what it means in terms of support and maintenance.
  5. Avoid implementing templating logic; prefer variable replacement.
  6. Avoid implementing our own expression syntax; when required prefer existing languages which are widely used and include supporting development tools.
  7. In TEPs, discuss how the proposal affects the flexibility of Tekton and demonstrate that any specific/opinionated choices are necessary but extensible.

Conformance

  1. Tekton features should work as the user expects in varied environment setup.
  2. Tekton users should not need to understand the implementation details of the API on any specific platform. In general, TEPs should make Tekton more platform-agnostic, not more platform-specific.
  3. To the greatest extent possible, the Tekton API should not contain Kubernetes-specific features, such as configuration for Pods. While the "main" implementation of the Tekton API is built on Kubernetes, there is also (for example) a buildkit implementation of Tekton, and platform builders may choose to implement the Tekton API in other ways that don't rely on Kubernetes. When Kubernetes-specific features have to be added, they should be explicitly called out in the design docs, and consider shunting them together into a section of the API, such as podTemplate. The Tekton API currently contains some Kubernetes-isms. These should be treated as potentential long-term opportunities for improvement of our abstractions.
  4. In TEPs, discuss how the proposal affects conformance. As mentioned in the conformance document, newly added API fields shouldn't be required for Tekton conformance, but can transition to becoming required over time.
  5. Limit introducing feature flags that make Tasks and Pipelines behave differently. It should be possible to take a Task or Pipeline and reuse it across systems without requiring that a controller be configured in a specific way to make it work. Exceptions should be discussed with in the TEP and agreed upon with the Tekton community.

Security

  1. Implement secure design principles as described by the OpenSSF badge requirements
  2. Use the security sections of TEPs when applicable:
    1. Does the change increase the attack surface of Tekton / significantly impact the threat model?
    2. Does the change makes it harder for users to follow security best practices through Tekton?
    3. Does the change impact Tekton users ability to achieve SLSA compliance for any of the four levels?
    4. Does the change introduce features that could be problematic from a provenance point of view?
  3. Do not implement cryptographic algorithms in Tekton, rely on proven tools and libraries