Documentation
¶
Overview ¶
Package registry is the thin domain layer of `d8 cr` on top of go-containerregistry/pkg/v1/*. It replaces the upstream pkg/crane facade - we own every entry point, error message and option default.
Index ¶
- func Fetch(ctx context.Context, ref string, opts *Options) (v1.Image, error)
- func FetchConfig(ctx context.Context, ref string, opts *Options) ([]byte, error)
- func FetchDigest(ctx context.Context, ref string, opts *Options) (string, error)
- func FetchIndex(ctx context.Context, ref string, opts *Options) (v1.ImageIndex, error)
- func FetchManifest(ctx context.Context, ref string, opts *Options) ([]byte, error)
- func IsIndex(ctx context.Context, ref string, opts *Options) (bool, error)
- func ListCatalog(ctx context.Context, regRef string, opts *Options) ([]string, error)
- func ListTags(ctx context.Context, repoRef string, opts *Options) ([]string, error)
- func ParseReference(ref string, opts *Options) (name.Reference, error)
- func ParseRepository(repoRef string, opts *Options) (name.Repository, error)
- func Push(ctx context.Context, ref string, obj partial.WithRawManifest, opts *Options) (v1.Hash, error)
- type LoginResult
- type Options
- func (o *Options) WithAuth(auth authn.Authenticator) *Options
- func (o *Options) WithInsecure() *Options
- func (o *Options) WithKeychain(kc authn.Keychain) *Options
- func (o *Options) WithNondistributable() *Options
- func (o *Options) WithPlatform(p *v1.Platform) *Options
- func (o *Options) WithVerbose() *Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Fetch ¶
Fetch resolves ref to a single image.
For a multi-arch index the platform pinned on Options wins; without one the underlying library falls back to a hardcoded linux/amd64 rather than the host's platform, so commands that must match the caller's architecture have to pass --platform.
func FetchConfig ¶
FetchConfig returns the raw config JSON for ref, byte-for-byte as stored, so it stays pipeable into jq and comparable across pulls.
func FetchDigest ¶
FetchDigest returns "sha256:<hex>" for ref.
With a platform pinned this is the digest of that child image, not of the index - the whole point of asking for a digest is to pin what will actually run, and an index digest does not identify a single image.
func FetchIndex ¶ added in v0.33.16
FetchIndex resolves ref to a multi-arch index, resolving nothing. An image reference is an error - the caller asked for an index.
func FetchManifest ¶
FetchManifest returns the raw manifest bytes as the registry served them, which is what signature verification and audit trails need - a manifest decoded and re-encoded no longer hashes to its own digest.
With a platform pinned, a multi-arch reference resolves to that child's manifest instead of the index. Without one the index is returned as served.
func IsIndex ¶ added in v0.33.16
IsIndex reports whether ref is a multi-arch index rather than a single image, which is what pull needs to know before deciding what to write to disk.
func ListCatalog ¶
ListCatalog returns every repository on the given registry.
Registries that do not implement /v2/_catalog - Docker Hub, GCR and Artifact Registry among them - are reported as such rather than as a bare 404, which otherwise reads like a missing repository and sends users hunting for a permissions problem they do not have.
func ListTags ¶
ListTags returns every tag of repoRef.
The registry's page-by-page protocol is the client's business and has no console equivalent - there is no way for a user to ask for "the next range" - so callers get the complete list or an error, never a truncated one.
func ParseReference ¶ added in v0.33.16
ParseReference parses a user-supplied image reference under the flags on Options - notably --insecure, which permits a plain-HTTP registry.
Commands need this to echo a canonical reference back to the user (push prints the pushed digest reference, ls --full-ref prefixes every tag), and routing it through here keeps one set of parsing flags for the whole subtree.
func ParseRepository ¶ added in v0.33.16
func ParseRepository(repoRef string, opts *Options) (name.Repository, error)
ParseRepository is ParseReference for arguments that name a repository.
Types ¶
type LoginResult ¶ added in v0.30.18
type LoginResult struct {
// ServerAddress is the key the credentials were stored under. For Docker
// Hub this is the canonical "https://index.docker.io/v1/".
ServerAddress string
// ConfigFile is the path to the Docker config the credentials were
// written to (or the backing file of the active credential store).
ConfigFile string
}
LoginResult reports where the credentials ended up so the caller can tell the user which file/store now holds them.
func Login ¶ added in v0.30.18
func Login(ctx context.Context, host, username, password string, opts *Options) (*LoginResult, error)
Login verifies username/password against host and, on success, persists them into the Docker config (the same store authn.DefaultKeychain reads), so every other cr command can authenticate transparently afterwards.
An empty host targets Docker Hub. Verification builds the registry's auth transport and then performs an authenticated GET /v2/: a rejected login answers 401 there, so invalid credentials fail rather than silently writing a broken config. (The transport handshake alone only validates bearer-token registries; the explicit /v2/ probe is what also covers basic-auth ones.)
type Options ¶
type Options struct {
// PlainHTTP talks to the registry over HTTP instead of HTTPS.
PlainHTTP bool
// TLSSkipVerify accepts any server certificate.
TLSSkipVerify bool
// Nondistributable uploads foreign layers on push instead of skipping them.
Nondistributable bool
// Verbose routes the client's debug log to stderr.
Verbose bool
// Platform pins a target platform for multi-arch indices. Nil means the
// reference is used as served, except where a command must resolve to a
// single image - see Fetch.
Platform *v1.Platform
// Auth authenticates every request when the user passed --username/--password.
// It takes precedence over Keychain, and being per-client it cannot leak
// credentials to a registry the user did not name.
Auth authn.Authenticator
// Keychain resolves credentials from the Docker config when Auth is unset.
Keychain authn.Keychain
// ClientFactory builds the registry client for one host. Nil means the real
// deckhouse/pkg/registry client.
//
// Tests set it to drive this package against pkg/registry's in-memory fake
// and stay off the network entirely: standing up an HTTP registry per test
// both slows the suite down and produces timeout flake under parallel
// `go test ./...` load. It is a field rather than a package-level hook so
// tests can run in parallel without fighting over global state.
ClientFactory func(host string, opts ...dkpclient.Option) dkpreg.Client
}
Options carries the `d8 cr` persistent flags and turns them into a deckhouse/pkg/registry client scoped to whatever reference a command names.
The flags live here rather than in a client instance because `d8 cr` is reference-oriented - every command takes a full "host/repo:tag" argument - while the client is scoped to one repository. clientForRef bridges the two.
func New ¶
func New() *Options
New returns Options seeded with the default Docker keychain, so every command authenticates from ~/.docker/config.json without a prior `cr login`.
func (*Options) WithAuth ¶ added in v0.33.16
func (o *Options) WithAuth(auth authn.Authenticator) *Options
WithAuth pins explicit credentials, as --username/--password do.
func (*Options) WithInsecure ¶
WithInsecure opts into plain HTTP and accepts any TLS certificate.
The two are separate on the client (WithInsecure / WithTLSSkipVerify) and deserve separate flags here too, but `--insecure` has always meant both, so the flag keeps setting both until it is split.
func (*Options) WithKeychain ¶
WithKeychain replaces the keychain that authenticates registry calls.
func (*Options) WithNondistributable ¶
WithNondistributable allows pushing foreign (non-distributable) layers.
func (*Options) WithPlatform ¶
WithPlatform pins a target platform. Nil is a no-op so a flag-driven caller can pass the parsed result without branching.
func (*Options) WithVerbose ¶ added in v0.33.16
WithVerbose enables the client's debug log on stderr.
Source Files