chore(docs): zarf principles draft #3562
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| --- | ||
| title: Zarf Principles | ||
| --- | ||
|
|
||
| Zarf is a tool for continuous software delivery to disconnected environments. To ensure that Zarf remains true to its mission and continues to provide value for its users, the following design principles serve as a framework for evaluating new features and capabilities. | ||
|
|
||
| ## 1. Airgap-First Functionality | ||
| Zarf is designed for airgapped environments, meaning that all functionality should operate without requiring external dependencies. This includes: | ||
| - Ensuring that all packaged software and dependencies are self-contained. | ||
| - Avoiding reliance on external repositories or registries during runtime. | ||
| - Providing a seamless user experience for both online and offline operations. | ||
|
|
||
| ## 2. Minimal and Secure Binary | ||
| The Zarf binary must remain lightweight and secure while offering core functionality. Considerations include: | ||
| - Baking in only essential tools necessary for package management, deployment, and validation. | ||
| - Avoiding unnecessary bloat by carefully selecting embedded utilities. | ||
| - Ensuring security best practices, including dependency verification and signed releases. | ||
|
|
||
| ## 3. Clear Scope Within Kubernetes Environments | ||
| Zarf operates in Kubernetes clusters but does not attempt to replace existing Kubernetes tooling. Instead, Zarf should: | ||
| - Focus on enabling package management and deployment in airgapped clusters. | ||
| - Complement, rather than compete with, Kubernetes-native solutions (e.g., Helm, Kustomize, and Operator patterns). | ||
| - Facilitate cluster initialization and ongoing software management without enforcing opinionated infrastructure choices. | ||
|
|
||
| ## 4. Declarative and Reproducible Workflows | ||
| To maintain consistency in deployments, Zarf should emphasize: | ||
| - Declarative package definitions that allow for repeatable deployments. | ||
| - Versioned and auditable package formats that ensure integrity across different environments. | ||
| - Support for GitOps workflows where applicable. | ||
|
|
||
| ## 5. Operational Simplicity | ||
| Zarf should remain simple to use and operationalize, with considerations such as: | ||
| - Clear and concise configuration files that reduce complexity. | ||
| - A user-friendly CLI that abstracts away unnecessary details while allowing expert-level control when needed. | ||
| - Automation and scripting capabilities that streamline usage in constrained environments. | ||
|
There was a problem hiding this comment. Developer simplicity I think is also key here - there are special things like the |
||
|
|
||
| ## 6. Compatibility and Extensibility | ||
|
There was a problem hiding this comment. It may be worth calling out specific expectations around stability of interfaces - i.e. what is "stable" in the CLI (probably a lot but not |
||
| Zarf should be flexible enough to work in various environments while maintaining its core mission. This means: | ||
| - Supporting multiple architectures and operating systems where feasible. | ||
| - Allowing extensibility through custom package configurations and integrations. | ||
|
There was a problem hiding this comment. Worth calling out its use as a library explicitly here? (since "integrations" could be many things and some of them we may not prefer (i.e. a python script that generates Zarf packages and drives Zarf's CLI would be an "integration" but IMO that would be treated differently from a Go CLI importing Zarf as a library) |
||
| - Ensuring compatibility with industry standards to facilitate interoperability. | ||
|
|
||
| ## 7. Community and Open Source Focus | ||
| As an open-source project, Zarf should prioritize community involvement and transparency by: | ||
| - Encouraging feedback and contributions from users and maintainers. | ||
| - Providing clear documentation and guidance for adoption. | ||
| - Adhering to open governance principles to guide long-term sustainability. | ||
|
|
||
| These principles help guide the evolution of Zarf while ensuring that new features and capabilities align with its core mission. By adhering to these guidelines, Zarf can continue to serve as a robust, reliable tool for software delivery. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It may be worth calling out that in complementing the K8s environment it should also "fit in" from a user and dev experience perspective - i.e. Zarf shouldn't invent its own workflows unless that workflow is just something that doesn't exist (Zarf Values <> Zarf Variables would be a good example there).