|
| 1 | +# BuildKit project process guide |
| 2 | + |
| 3 | +* [Issue categorization guidelines](#issue-categorization-guidelines) |
| 4 | + + [P0](#p0) |
| 5 | + + [P1](#p1) |
| 6 | + + [P2](#p2) |
| 7 | +* [Release milestones](#release-milestones) |
| 8 | + + [Feature releases](#feature-releases) |
| 9 | + + [Patch releases](#patch-releases) |
| 10 | + + [Updating dependencies](#updating-dependencies) |
| 11 | +* [Project scope](#project-scope) |
| 12 | +* [Security boundary](#security-boundary) |
| 13 | + + [Host](#host) |
| 14 | + + [Client](#client) |
| 15 | + + [Untrusted sources](#untrusted-sources) |
| 16 | + + [Stored data](#stored-data) |
| 17 | + + [Examples of issues not (currently) considered security](#examples-of-issues-not--currently--considered-security) |
| 18 | + |
| 19 | + |
| 20 | +## Issue categorization guidelines |
| 21 | + |
| 22 | +Following categorization describes how priorities are assigned to bug reports, and how the priority is used to determine whether a fix will be included in a patch release. Note that not all issues need to have priority assigned if they don't need any special tracking for an upcoming patch release of a feature milestone. |
| 23 | + |
| 24 | +### P0 |
| 25 | + |
| 26 | +Fixing this issue is the highest priority. As soon as a patch is available and verified a patch release will follow. |
| 27 | + |
| 28 | +Examples: |
| 29 | + |
| 30 | +- Regression in a critical code path |
| 31 | +- Panic in a critical code path |
| 32 | +- Corruption in critical code path or rest of the system |
| 33 | +- Leaked zero-day critical security |
| 34 | + |
| 35 | +### P1 |
| 36 | + |
| 37 | +Issues should be fixed with high priority and almost always included in a patch release. Unless waiting for another issue, patch releases should happen within a week. |
| 38 | + |
| 39 | +Examples: |
| 40 | + |
| 41 | +- Any regression, panic |
| 42 | +- Measurable performance regression |
| 43 | +- A major bug in a new feature in the latest release |
| 44 | +- Incompatibility with upgraded external dependency |
| 45 | + |
| 46 | +### P2 |
| 47 | + |
| 48 | +PRs opened for P2 bugs should be included in the next feature release milestone. A P2 fix may be included in a patch release, depending on the patch size and how likely the patch may break something some other functionality. Patch release is usually only done if there are P1 fixes, and in that case some of the P2 fixes may be included as well. |
| 49 | + |
| 50 | +Examples: |
| 51 | + |
| 52 | +- Confirmed bug |
| 53 | +- Bugs in non-default configurations |
| 54 | + |
| 55 | +## Release milestones |
| 56 | + |
| 57 | +BuildKit is released with feature releases, patch releases, and security releases. |
| 58 | + |
| 59 | +### Feature releases |
| 60 | + |
| 61 | +Feature releases happen from the development branch, after which a release branch is cut for future patch releases (this can also happen in the code freeze time). |
| 62 | + |
| 63 | +Users can expect 2-3 release candidate test releases before a feature release. First of these usually happens around 2 weeks before the actual release. |
| 64 | + |
| 65 | +BuildKit maintains backward compatibility in the gRPC API with previous releases, so it is possible to use old clients with new daemon and vice versa. If a feature needs to be removed, then it is first marked deprecated in a feature release. We do not plan to ever make backward incompatible changes in certain areas like the LLB API. BuildKit APIs internally use feature detection to understand what features the other side of the API supports. |
| 66 | + |
| 67 | +Go modules in the BuildKit repository aren't guaranteed to be backward compatible with previous release branches. |
| 68 | + |
| 69 | +Once a new feature release is cut, no support is offered for the previous feature release. An exception might be if a security release suddenly appears very soon after a new feature release. There are no LTS releases. If you need a different support cycle, consider using a [product that includes BuildKit](https://github.com/moby/buildkit#used-by), (eg. Docker) instead. |
| 70 | + |
| 71 | +Anyone can ask for an issue or PR to be included in the next feature- or patch release milestone, assuming it passes the requirements. |
| 72 | + |
| 73 | +### Patch releases |
| 74 | + |
| 75 | +Patch releases should only include the most critical patches. Everyone should always use the latest patch release, so stability is very important. |
| 76 | + |
| 77 | +If a fix is needed but it does not qualify for patch release because of the code size or other criteria that make it too unpredictable, we will prioritize cutting a new feature release sooner, rather than making an exception for backporting. |
| 78 | + |
| 79 | +Following PRs are included in patch releases |
| 80 | + |
| 81 | +- P0 fixes |
| 82 | +- P1 fixes, assuming maintainers don’t object because of the patch size |
| 83 | +- P2 fixes, only if (both required) |
| 84 | + - proposed by maintainer |
| 85 | + - the patch is trivial and self-contained |
| 86 | +- Documentation-only patches |
| 87 | +- Runtime dependency updates (e.g. Alpine packages, runc) |
| 88 | + - may be updated to the latest patch release of the dependency |
| 89 | +- Vendored dependency updates, only if |
| 90 | + - Fixing (qualifying) bug or security issue in BuildKit |
| 91 | + - Patch is small, otherwise a forked version of dependency with only the patches required |
| 92 | + |
| 93 | +New features do not qualify for patch release. |
| 94 | + |
| 95 | +### Updating dependencies |
| 96 | + |
| 97 | +Runtime dependencies should usually use the latest stable release available when the first RC of the feature release was cut. Patch releases may update such dependencies to their own latest matching patch release. |
| 98 | + |
| 99 | +The core vendored dependencies (eg. `x/sys` , OTEL, grpc, protobuf) should use the same dependency version that is used by the vendored `containerd` library. At feature release time containerd library should use a version from a containerd release branch. If you need to update such dependency, update it in containerd repository first and then update containerd in BuildKit. During development, using containerd development branch is allowed if the release timeline shows that containerd release (and matching update in BuildKit) will happen before next BuildKit feature release. |
| 100 | + |
| 101 | +Docker dependencies from `moby/moby` and `docker/cli` may use versions from the development branch. |
| 102 | + |
| 103 | +For other dependencies, updating to the latest patch release is always allowed in the development branch. Updating to a new feature release should have a reason unless the dependency is very stale. Dependencies should use a tagged version if one is available and there isn’t a need for a specific patch from an untagged commit. Go modules should define the lowest compatible version for their dependencies so there is no goal that all dependencies need to be in their latest versions before a new BuildKit feature release is cut. |
| 104 | + |
| 105 | +Vendored dependency updates are considered for patch releases, except for rare cases defined in the earlier section. |
| 106 | + |
| 107 | +A security scanner report for a dependency that isn't exploitable via BuildKit is not considered a valid reason for backports. |
| 108 | + |
| 109 | +## Project scope |
| 110 | + |
| 111 | +The following characteristics define the scope and purpose of the BuildKit project: |
| 112 | + |
| 113 | +- BuildKit provides the best solution for defining a build graph, executing and caching it as efficiently as possible, and exporting the result to a place where it can be used by other tools. |
| 114 | +- BuildKit is a place for fast collaboration around modern containerized build tooling. |
| 115 | +- BuildKit uses containers as an execution sandbox and distribution platform. |
| 116 | +- BuildKit provides an API that is flexible enough to be used in many tools and use cases. |
| 117 | +- BuildKit is secure by default and can be used with untrusted sources. |
| 118 | +- The purpose of BuildKit's command line tool `buildctl` is to expose API features as directly as possible. |
| 119 | +- BuildKit isn't limited to only supporting features used by Docker build. |
| 120 | + |
| 121 | +Things that **do not** define BuildKit: |
| 122 | + |
| 123 | +- Running processes on the host. |
| 124 | +- Solving the following issues that should be left for external projects, such as: |
| 125 | + - Combining multiple build requests together |
| 126 | + - Managing and deploying BuildKit instances |
| 127 | + - Inventing new frontends |
| 128 | + - Running containers from mutable state |
| 129 | +- Opinionated client-side UX features. An exception here is a `buildctl debug` command where we can experiment with ways to extract more debugging data out of BuildKit. |
| 130 | + |
| 131 | +If you are an end user, you should probably consider a tool built with BuildKit, rather than using BuildKit directly. |
| 132 | + |
| 133 | +## Security boundary |
| 134 | + |
| 135 | +This section is for some guidelines about what BuildKit considers a security issue and what kind of guarantees all future BuildKit features should provide. If you are unsure if the case you have found is a security issue, it is always better to ask privately first. |
| 136 | + |
| 137 | +### Host |
| 138 | + |
| 139 | +- The BuildKit API with default daemon configuration does not allow changes to the host filesystem or reading the host filesystem outside of the BuildKit state directory. |
| 140 | +- Application and frontend containers are not allowed to read or write to the host system, run privileged system calls, or access external devices directly. Monitoring the load of the system is allowed. |
| 141 | + |
| 142 | +### Client |
| 143 | + |
| 144 | +- Buildctl does not allow access to any directories or file paths that are not explicitly set by the user with command line arguments. The untrusted BuildKit daemon does not have any way to access files that were not listed. |
| 145 | +- When extracting build results to a directory specified with `--output` or `--cache-to`, no subfile can escape to the outside directory (e.g. via symlinks) |
| 146 | + |
| 147 | +### Untrusted sources |
| 148 | + |
| 149 | +- Although discouraged, you can use untrusted resources in your build, like images, frontend, URLs. These resources, or containers created from the files of these resources, should not have a way to read/write/execute in the host or crash the BuildKit daemon. |
| 150 | + |
| 151 | + Exceptions: |
| 152 | + |
| 153 | + - Containers can use system resources (CPU, memory, disk) without specific limits. |
| 154 | + - Untrusted remote cache imports may not be used. |
| 155 | + |
| 156 | +- An untrusted frontend may not export build results to a location (client-side directory, registry) without user permission with a specific build request. If the frontend initializes a pull with credentials from the client, this needs to be logged on the client-side progress stream. |
| 157 | +- Frontends can not access registry credentials or tokens that a build is using, the SSH private keys used in SSH forwarding, nor keys that may be used to sign build results or attestations. Frontends can provide SBOM attestation for the builds it has performed but it can not alter the contents of provenance attestations generated by BuildKit daemon. |
| 158 | +- If a build was started with a policy file, the untrusted frontend has no way to use resources that are denied by that policy. |
| 159 | + |
| 160 | +### Stored data |
| 161 | + |
| 162 | +- Credentials should not be logged or written to OpenTelemetry trace or progress stream. Note that this applies to registry credentials and URL sources, if user writes credentials into the arguments of their application containers, there is nothing BuildKit can do about it. |
| 163 | +- Values of the build secrets should never be stored anywhere on the disk or included in the cache checksums. |
| 164 | + |
| 165 | +### Examples of issues not (currently) considered security |
| 166 | + |
| 167 | +- Multiple concurrent builds from separate client share their build resources without namespacing. For example, if both builds require pulling the same image, the pull only happens once and is authenticated only once. The same behavior happens with containers that use the same build secret or if local cache or cache mounts of a previous build are reused. If different behavior is needed, consider running multiple instances of buildkitd for each of the namespaces. |
| 168 | +- Remote cache resources provided with `--cache-to` need to be trusted by the user. If they have been manipulated by an attacker, this can result in an incorrect cache match by BuildKit solver. |
| 169 | +- Application containers may cause the system to run out of resources (e.g. memory). In that case BuildKit should be configured with a cgroup parent. |
| 170 | +- By default, registry credentials are not shared with BuildKit daemon, and short-lived token is generated on client side instead. For backward compatibility this can be bypassed and daemon can choose to ask for credentials instead (this is always required for basic auth). In such cases, the sending of credentials should be logged by the client, but no special confirmation from the user is needed. |
| 171 | +- Untrusted frontends are free to run any builds, for example, they can run a container with a secret mounted and then read out the secret value. They are not allowed to see your registry credentials/tokens or signing keys. |
0 commit comments