Documentation
¶
Overview ¶
Package image parses, prints and identifies container image references.
A reference has up to three parts: the repo (registry path without tag or digest), an optional tag and an optional sha256 digest. All four shapes seen in manifests and pod status are accepted by Parse and printed back canonically by String. Nothing here talks to a registry.
Index ¶
Constants ¶
const PullablePrefix = "docker-pullable://"
PullablePrefix is the scheme some container runtimes prepend to status.containerStatuses[].imageID. Parse strips it; String never emits it.
Variables ¶
This section is empty.
Functions ¶
func Canonical ¶
Canonical returns the repo in the registry's own spelling, so that the repo a manifest names and the repo a pod's imageID names can be compared: docker.io/library/nginx, docker.io/nginx and nginx all become index.docker.io/library/nginx, while ghcr.io/example/app is already canonical. It is go-containerregistry's name parsing; a repo it cannot parse is returned unchanged rather than failing a comparison.
func PromotionID ¶
PromotionID is the deterministic identity of one promotion (AGENTS.md §4.1). Exactly:
- lines = the distinct "<repo>@<digest>" strings of refs (Tag ignored; a repo@digest pair that appears more than once contributes one line — §4.1 defines the input as a *set*, so two occurrences of one image in the target env do not change the id),
- sorted bytewise (sort.Strings),
- preimage = "hoist/v1\n" + repoFullName + "\n" + targetEnv + "\n" + strings.Join(lines, "\n"),
- id = the first 10 characters of the lowercase, unpadded standard base32 encoding of sha256(preimage).
The M1 brief's formula omits step 1's dedup; this is the deliberate reading, and TestPromotionIDFixedVectorWithDuplicate freezes it. Callers pass pinned refs; an unpinned ref contributes "<repo>@" and is the caller's bug, not this function's concern.
Types ¶
type Ref ¶
Ref is one image reference. Tag == "" means the reference carried no tag (implicit "latest"); String prints it back without a tag so that Parse/String round-trips.
func Parse ¶
Parse accepts repo:tag@sha256:…, repo:tag, repo@sha256:… (optionally prefixed with docker-pullable://) and repo alone. A digest that is not sha256 followed by 64 lowercase hex characters is an error, not a digest.
func ParseOverride ¶ added in v0.2.0
ParseOverride parses one digest override as an operator writes it — `repo=repo:tag@sha256:…` — and is the one predicate both faces apply to it: `hoist plan|promote --digest` (cmd/hoist's digestFlag.Set) and the plan screen's `o` dialog (internal/app/plan) call this and nothing else, so the two can never drift on what an override is (AGENTS.md §8, layered checks). It lives here rather than in pkg/resolve because it is a rule about the shape of a reference string — the same rules Parse applies plus three of its own — and knows nothing about resolution order or sources: the left side must name the reference's own repo (a typo there would otherwise plan a different repo than the one the operator meant), and the reference must carry a tag and a digest, since hoist never writes anything else to a manifest (§4.2). The returned Ref's Repo is the override's key.
Politeness, not enforcement: gitops.BuildPlan refuses an unpinned or tagless override on its own, whichever face let it through, so deleting a check here moves the refusal rather than making a new state possible.
func (Ref) Pinned ¶
Pinned reports whether the reference carries a digest. Only pinned references may be written to a manifest (AGENTS.md §4.2).
func (Ref) Validate ¶
Validate checks a Ref that did not come from Parse — a caller-built override, say — against the same rules Parse applies: a non-empty repo, a well-formed tag if present, and a digest that is exactly "sha256:" followed by 64 lowercase hex characters if present. It is the one definition of "well-formed"; Parse and Validate share the expressions.
Source Files