Documentation
¶
Overview ¶
Package registry answers one question: where do images this install builds go, and how does the cluster get them back.
Its own package rather than another setting on the cluster Joiner. That type already holds two unrelated install-wide settings, and a third would make it the place install settings go rather than a thing with a job. The seam also earns its keep: the builder needs push credentials, the orchestrator needs pull credentials, and neither should reach into a database to find them.
Index ¶
- Variables
- func ValidateHost(host string) error
- func ValidateRepository(repo string) error
- type Credentials
- type Settings
- type Store
- func (s *Store) CanStore() bool
- func (s *Store) CheckDigest(ctx context.Context, ref string) error
- func (s *Store) Clear(ctx context.Context) error
- func (s *Store) Configured(ctx context.Context) bool
- func (s *Store) Credentials(ctx context.Context) (Credentials, error)
- func (s *Store) DockerConfig(ctx context.Context) ([]byte, error)
- func (s *Store) ImageFor(ctx context.Context, ownerID, app, revision string) (string, error)
- func (s *Store) Insecure(ctx context.Context) bool
- func (s *Store) ResolveDigest(ctx context.Context, ref string) (string, error)
- func (s *Store) Set(ctx context.Context, by uuid.UUID, host, repository, username, password string, ...) error
- func (s *Store) Settings(ctx context.Context) (Settings, error)
Constants ¶
This section is empty.
Variables ¶
var ErrCredentialsRejected = errors.New("registry: the registry could not be authenticated to")
ErrCredentialsRejected means authentication could not be completed.
Either the registry refused the credential, or its challenge could not be answered safely — a token endpoint Yacht will not send a request to is the same practical outcome as one that refused it. Distinguished from both of the above because it is neither transient nor a statement about the image: it is a configuration fault, and the person who can fix it is the one who set the registry up.
var ErrManifestNotFound = errors.New("registry: the image is not in the registry")
ErrManifestNotFound means the registry answered, authoritatively, that the image is not there.
A separate answer from a failure because the two lead to opposite decisions. An image that is genuinely absent will not appear by waiting, so the deploy that wanted it has to fail and say to build again. Anything short of an authoritative answer says nothing about whether the image exists, so failing on it would discard an image that is sitting in the registry.
Two responses produce it, and nothing else does: a 404, and a registry that names the image unknown — MANIFEST_UNKNOWN or NAME_UNKNOWN — once Yacht has authenticated. The second exists because some registries answer a missing repository with 401 rather than 404, and after the credential has been presented "unknown" is about the image rather than about the caller.
Everything else is deliberately excluded, and the exclusions are the point. A registry that says "unknown image" before Yacht has authenticated at all is describing what an anonymous caller can see, not what is there. A registry that answers something unclassifiable is describing nothing. Both are "we do not know yet", because the cost of the two mistakes is not symmetric: a false "unreachable" retries, and a false "not found" throws away a successfully pushed image.
var ErrNoSecretKey = errors.New(
"registry: no YACHT_SECRET_KEY is configured, so a registry password cannot be stored safely")
ErrNoSecretKey means a password was offered with no key to seal it.
Refused rather than stored readable, for the reason the join token is: a credential protected in name only is worse than one nobody stored, because nothing about it looks wrong.
var ErrNotConfigured = errors.New("registry: no image registry is configured")
ErrNotConfigured means nobody has stored a registry.
Distinguished from a failure because it is the normal state of a fresh install, and because it is the difference between "building is broken" and "building is not set up yet" — which are different things to tell somebody.
var ErrUnreachable = errors.New("registry: the registry could not be asked about the image")
ErrUnreachable means nothing was learned about the image.
It covers the transport failing, the request being cancelled, the registry refusing service for now (429), the registry failing on its own account (5xx), and the registry answering something that is not an answer — an unexpected status, a body that is not a manifest, a digest that contradicts its own content. All of them are the same answer to the only question a caller has here: no, not yet, and nothing has been ruled out.
The cause is kept in the chain, so errors.Is finds context.Canceled and context.DeadlineExceeded through it as well as this.
Functions ¶
func ValidateRepository ¶
ValidateRepository checks the path images are pushed under. Empty is valid.
Types ¶
type Credentials ¶
type Credentials struct {
Host string
Username string
Password string
// Insecure means push and pull go over plain HTTP.
Insecure bool
}
Credentials is what actually authenticates to the registry.
Separate from Settings and returned by its own method, so that reading the password is something a caller asks for explicitly rather than something it receives whenever it asks where images go.
func (Credentials) DockerConfigJSON ¶
func (c Credentials) DockerConfigJSON() ([]byte, error)
DockerConfigJSON is the contents of a kubernetes.io/dockerconfigjson secret.
Built here rather than in the Kubernetes layer because the shape belongs to the registry, and because keeping it here means the credential is turned into its wire form in the one package that is allowed to see it.
type Settings ¶
type Settings struct {
Host string
Repository string
Username string
// Insecure means the registry is served over plain HTTP.
//
// Yacht can only act on half of this. It can tell the builder to push over
// HTTP; it cannot tell the cluster's container runtime to pull that way,
// because that is node configuration and Yacht does not touch nodes. The
// page says so rather than leaving somebody to discover it as
// ImagePullBackOff.
Insecure bool
UpdatedAt string
}
Settings is where images go, without the password.
The password is deliberately absent. Everything that renders a page takes this type, so there is no path by which a template can print the credential even by accident.
func (Settings) Configured ¶
Configured reports whether images have somewhere to go.
func (Settings) ImageRef ¶
ImageRef is the full name an app's build is pushed to and pulled from.
The path is derived from the owner and the app rather than chosen, because one registry account holds every team's images: a person picking their own path could pick another team's, and pushing over somebody else's tag is a way to have the cluster run your image under their name.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store reads and writes the install's registry.
func New ¶
New returns a Store. keeper may be nil, in which case storing a password is refused rather than done unsafely.
func (*Store) CanStore ¶
CanStore reports whether a password can be sealed.
Asked rather than discovered, so a page can say a credential cannot be kept safely before offering a box to type one into.
func (*Store) CheckDigest ¶
CheckDigest proves that a pinned image is still present. Unlike ResolveDigest, it deliberately asks the registry: rollback needs an availability answer before it may create an operation or touch the cluster.
func (*Store) Configured ¶
Configured reports whether there is a registry to push to.
Swallows the read error deliberately: this answers a question a picker asks while rendering, and "the database is unreachable" is not something a source list can act on. An install that cannot read its settings shows building as unavailable, which is what it is.
func (*Store) Credentials ¶
func (s *Store) Credentials(ctx context.Context) (Credentials, error)
Credentials returns what authenticates to the registry.
func (*Store) DockerConfig ¶
DockerConfig returns the credential in the form Kubernetes and BuildKit read.
func (*Store) ImageFor ¶
ImageFor returns the reference a build should push to.
Reads the settings on every call rather than caching them. A registry that changed between two deploys should take effect on the second, and a cache here would mean builds pushing to a registry nobody configured any more.
func (*Store) Insecure ¶
Insecure reports whether the registry is served over plain HTTP.
Swallows the read error like Configured does, and for the same reason: this answers a question asked while assembling a build, and the safe answer to "should this connection expect TLS" is yes.
func (*Store) ResolveDigest ¶
ResolveDigest returns the digest behind an image reference.
A reference that already names a digest is returned unchanged without a request, because it is already the answer and a lookup could only disagree with itself.
The install's credential is read per call rather than held, the way DockerConfig reads it, so it is unsealed only when something is about to ask and a registry password changed between two deploys takes effect on the second. It is sent only to the host this install configured: a reference to somebody else's registry is resolved anonymously rather than by presenting this install's password to a host that never asked for it.
Source Files