container-source-policy-darwin-arm64 0.1.2 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -21
- package/bin/container-source-policy +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,43 +1,50 @@
|
|
|
1
1
|
# container-source-policy
|
|
2
2
|
|
|
3
|
-
Generate a Docker BuildKit **source policy** file
|
|
3
|
+
Generate a Docker BuildKit **source policy** file by parsing Dockerfiles and pinning `FROM` images to immutable digests.
|
|
4
4
|
|
|
5
5
|
This helps make `docker buildx build` inputs reproducible without rewriting your Dockerfile.
|
|
6
6
|
|
|
7
|
+
See the [BuildKit documentation on build reproducibility](https://github.com/moby/buildkit/blob/master/docs/build-repro.md) for more details on source policies.
|
|
8
|
+
|
|
7
9
|
## Quick start
|
|
8
10
|
|
|
9
11
|
```bash
|
|
10
12
|
container-source-policy pin --stdout Dockerfile > source-policy.json
|
|
11
|
-
docker buildx build
|
|
13
|
+
EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=source-policy.json docker buildx build -t my-image:dev .
|
|
12
14
|
```
|
|
13
15
|
|
|
16
|
+
> **Note:** [`EXPERIMENTAL_BUILDKIT_SOURCE_POLICY`](https://docs.docker.com/build/building/variables/#experimental_buildkit_source_policy) is the environment variable used by Docker Buildx to specify a source policy file.
|
|
17
|
+
|
|
14
18
|
## Install
|
|
15
19
|
|
|
16
|
-
|
|
20
|
+
Run directly without installing (recommended):
|
|
17
21
|
|
|
18
22
|
```bash
|
|
19
|
-
|
|
20
|
-
|
|
23
|
+
# npm/bun
|
|
24
|
+
npx container-source-policy --help
|
|
25
|
+
bunx container-source-policy --help
|
|
21
26
|
|
|
22
|
-
|
|
27
|
+
# Python
|
|
28
|
+
uvx container-source-policy --help
|
|
23
29
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
container-source-policy --help
|
|
30
|
+
# Ruby (requires RubyGems 3.3+)
|
|
31
|
+
gem exec container-source-policy --help
|
|
27
32
|
```
|
|
28
33
|
|
|
29
|
-
|
|
34
|
+
Or install globally:
|
|
30
35
|
|
|
31
36
|
```bash
|
|
32
|
-
|
|
33
|
-
container-source-policy
|
|
34
|
-
```
|
|
37
|
+
# Go (build from source)
|
|
38
|
+
go install github.com/tinovyatkin/container-source-policy@latest
|
|
35
39
|
|
|
36
|
-
|
|
40
|
+
# npm
|
|
41
|
+
npm i -g container-source-policy
|
|
37
42
|
|
|
38
|
-
|
|
43
|
+
# Python
|
|
44
|
+
pipx install container-source-policy
|
|
45
|
+
|
|
46
|
+
# Ruby
|
|
39
47
|
gem install container-source-policy
|
|
40
|
-
container-source-policy --help
|
|
41
48
|
```
|
|
42
49
|
|
|
43
50
|
## Usage
|
|
@@ -60,10 +67,16 @@ Write directly to a file:
|
|
|
60
67
|
container-source-policy pin --output source-policy.json Dockerfile
|
|
61
68
|
```
|
|
62
69
|
|
|
63
|
-
Then pass the policy to BuildKit / Buildx:
|
|
70
|
+
Then pass the policy to BuildKit / Buildx via the environment variable:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=source-policy.json docker buildx build .
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Or use `buildctl` directly with the `--source-policy-file` flag:
|
|
64
77
|
|
|
65
78
|
```bash
|
|
66
|
-
|
|
79
|
+
buildctl build --frontend dockerfile.v0 --local dockerfile=. --local context=. --source-policy-file source-policy.json
|
|
67
80
|
```
|
|
68
81
|
|
|
69
82
|
Shell completion scripts are available via Cobra:
|
|
@@ -74,6 +87,8 @@ container-source-policy completion zsh
|
|
|
74
87
|
|
|
75
88
|
## What gets pinned
|
|
76
89
|
|
|
90
|
+
### Container images (`FROM`)
|
|
91
|
+
|
|
77
92
|
- Looks at `FROM …` instructions across all provided Dockerfiles.
|
|
78
93
|
- Skips:
|
|
79
94
|
- `FROM scratch`
|
|
@@ -83,6 +98,20 @@ container-source-policy completion zsh
|
|
|
83
98
|
- Resolves the image manifest digest from the registry and emits BuildKit `CONVERT` rules of the form:
|
|
84
99
|
- `docker-image://<as-written-in-Dockerfile>` → `docker-image://<normalized>@sha256:…`
|
|
85
100
|
|
|
101
|
+
### HTTP sources (`ADD`)
|
|
102
|
+
|
|
103
|
+
- Looks at `ADD <url> …` instructions with HTTP/HTTPS URLs.
|
|
104
|
+
- Skips:
|
|
105
|
+
- `ADD --checksum=… <url>` (already pinned)
|
|
106
|
+
- URLs containing unexpanded variables (`${VAR}`, `$VAR`)
|
|
107
|
+
- Fetches the checksum and emits `CONVERT` rules with `http.checksum` attribute.
|
|
108
|
+
|
|
109
|
+
**Optimized checksum fetching** — avoids downloading large files when possible:
|
|
110
|
+
- `raw.githubusercontent.com`: extracts SHA256 from ETag header
|
|
111
|
+
- GitHub releases: uses the API `digest` field (set `GITHUB_TOKEN` for higher rate limits)
|
|
112
|
+
- S3: uses `x-amz-checksum-sha256` response header (by sending `x-amz-checksum-mode: ENABLED`)
|
|
113
|
+
- Fallback: downloads and computes SHA256
|
|
114
|
+
|
|
86
115
|
## Development
|
|
87
116
|
|
|
88
117
|
```bash
|
|
@@ -100,11 +129,12 @@ UPDATE_SNAPS=true go test ./internal/integration/...
|
|
|
100
129
|
## Repository layout
|
|
101
130
|
|
|
102
131
|
- `cmd/container-source-policy/cmd/`: Cobra CLI commands
|
|
103
|
-
- `internal/dockerfile`: Dockerfile parsing (`FROM` extraction)
|
|
104
|
-
- `internal/registry`: registry client (digest resolution)
|
|
132
|
+
- `internal/dockerfile`: Dockerfile parsing (`FROM` and `ADD` extraction)
|
|
133
|
+
- `internal/registry`: registry client (image digest resolution)
|
|
134
|
+
- `internal/http`: HTTP client (URL checksum fetching with optimizations)
|
|
105
135
|
- `internal/policy`: BuildKit source policy types and JSON output
|
|
106
136
|
- `internal/pin`: orchestration logic for `pin`
|
|
107
|
-
- `internal/integration`: end-to-end tests with
|
|
137
|
+
- `internal/integration`: end-to-end tests with mock registry/HTTP server and snapshots
|
|
108
138
|
- `packaging/`: wrappers for publishing prebuilt binaries to npm / PyPI / RubyGems
|
|
109
139
|
|
|
110
140
|
## Packaging
|
|
Binary file
|