Documentation
¶
Overview ¶
Package images centralises the policy for selecting Docker image references in embedded Kubernetes manifests and dynamically-created workloads.
Design (post digests-in-git removal):
- Embedded templates mark stack-owned images with the PlaceholderTag (`:__OBOL_IMAGE__`). Digests are never committed to git.
- At apply time (CopyInfrastructure / dynamic resource creation), Resolve rewrites each managed image to a short-SHA tag from version.GitCommit.
- For production security, Resolve binds the multi-arch index digest from GHCR on first resolve for that (repo, tag) and persists it under the config dir (`image-digests.json`). Later applies with the same CLI GitCommit reuse the stored digest — they do NOT re-query GHCR — so a retagged short-SHA cannot change the image under a running install. Set OBOL_REFRESH_IMAGE_DIGESTS=true to re-bind from the registry.
- Digest fetch is best-effort when no pin exists yet: if GHCR is unreachable, the short-SHA tag alone is used (still preferred over :latest). Dev mode uses a caller-supplied dev tag with no digest.
Threat model notes: short-SHA tags on GHCR are mutable if a package writer overwrites them. We rely on (a) CI never retagging published short SHAs, (b) first-bind-then-persist digests for install stability, and (c) package write ACLs on ghcr.io/obolnetwork. Digests-in-git were stronger for "same manifest everywhere forever" but forced the repin PR train; this is the intentional trade-off. See docs/release-images.md.
Index ¶
- Constants
- Variables
- func BuildReplacers(resolve func(repo string) string) []replacer
- func ClearDigestCache()
- func ClearPersistedDigests()
- func FetchIndexDigest(repo, tag string) (string, error)
- func Resolve(repo string) string
- func ResolveDev(repo, devTag string) string
- func RewriteBytes(data []byte, replacers []replacer) []byte
- func RewriteTree(root string, resolve func(repo string) string) error
- func StampIdentity() string
- type Replacer
Constants ¶
const PlaceholderTag = "__OBOL_IMAGE__"
PlaceholderTag is the sentinel tag embedded templates use for stack-owned images. CopyInfrastructure rewrites every occurrence before helmfile apply. Leaving it unreplaced would fail image pulls loudly (fail-closed).
Variables ¶
var Managed = []string{
"ghcr.io/obolnetwork/x402-verifier",
"ghcr.io/obolnetwork/serviceoffer-controller",
"ghcr.io/obolnetwork/x402-buyer",
"ghcr.io/obolnetwork/job-broker",
"ghcr.io/obolnetwork/demo-server",
"ghcr.io/obolnetwork/obol-stack-public-storefront",
}
ManagedRepos that go through Resolve / RewriteTree. Keep in lockstep with internal/stack baseLocalImages and the image groups in .github/scripts/lib-ghcr.sh (publish workflows + release gate).
Functions ¶
func BuildReplacers ¶ added in v0.13.0
BuildReplacers is exported for tests; production uses RewriteTree.
func ClearDigestCache ¶ added in v0.13.0
func ClearDigestCache()
ClearDigestCache is for tests (process-local GHCR cache only).
func ClearPersistedDigests ¶ added in v0.13.0
func ClearPersistedDigests()
ClearPersistedDigests clears the in-memory mirror of the durable pin file (tests). Does not delete the file unless digestsPath is under a temp dir the test owns.
func FetchIndexDigest ¶ added in v0.13.0
FetchIndexDigest returns the multi-arch index digest GHCR serves for repo:tag (e.g. "sha256:deadbeef…"). Matches `docker buildx imagetools inspect --format '{{ .Manifest.Digest }}'`. Process-local cache only — durable pins live in image-digests.json.
func Resolve ¶
Resolve returns the fully-qualified image reference for a managed repo.
images.Resolve("ghcr.io/obolnetwork/demo-server")
// → "ghcr.io/obolnetwork/demo-server:abc1234@sha256:…" (prod, registry up)
// → "ghcr.io/obolnetwork/demo-server:abc1234" (prod, offline)
// → "ghcr.io/obolnetwork/demo-server:latest" (dev / unknown commit)
Prefer ResolveDev under OBOL_DEVELOPMENT so the local import tag matches — dynamically-created workloads should go through defaults.ResolveWorkloadImage, which handles that switch.
func ResolveDev ¶ added in v0.13.0
ResolveDev returns repo:devTag with no digest — local builds are imported into k3d under that exact tag.
func RewriteBytes ¶ added in v0.13.0
RewriteBytes applies the pre-built replacers to a single YAML blob. Exported for tests.
func RewriteTree ¶ added in v0.13.0
RewriteTree walks a directory of YAML files and rewrites every managed image reference via resolve. resolve receives the bare repository (e.g. "ghcr.io/obolnetwork/x402-verifier") and returns the full ref.
func StampIdentity ¶ added in v0.13.0
func StampIdentity() string
StampIdentity is included in the defaults-tree stamp so upgrading the binary (new GitCommit) or flipping dev mode re-renders image pins even when embedded template bytes are unchanged.
Source Files