Documentation
¶
Overview ¶
Package oci reads what a registry says about an image, before anything is pulled.
An app deployed from a prebuilt image (R-101) has no repository for detection to look at, so the registry is the only place its port, its storage and its health check can be read from ahead of running it. The same read answers two questions the deploy path needs settled before it starts anything: which digest a tag names right now, so that is what the revision pins (R-120's rule for commits, applied to images), and whether there is a build for the host's CPU at all, so a mismatch is a plan-time error rather than a container that exits on start.
Read-only and side-effect free: manifests and config blobs, never layers.
Index ¶
- Variables
- func DockerLogin() authn.Keychain
- func ECRRegion(registry string) (string, bool)
- func NormalizeArch(arch string) string
- func Pin(reference, digest string) string
- func PlatformMismatch(image string, host Platform, published []Platform) error
- func Reference(src spec.Source) string
- func Registry(reference string) (string, error)
- type Auth
- type Config
- type Credential
- type CredentialKind
- type CredentialStore
- type CredentialSummary
- type Health
- type Images
- func (im *Images) Auth(ctx context.Context, appID, reference string) (*Auth, error)
- func (im *Images) DescribeCredential(ctx context.Context, appID string) (CredentialSummary, bool, error)
- func (im *Images) Inspect(ctx context.Context, appID, reference string, want Platform) (Inspection, error)
- func (im *Images) RemoveCredential(ctx context.Context, appID string) error
- func (im *Images) SaveCredential(ctx context.Context, appID string, c Credential) error
- type Inspection
- type Inspector
- type Platform
- type Resolver
Constants ¶
This section is empty.
Variables ¶
var CredentialFields = []string{"kind", "username", "password", "access_key_id", "secret_access_key", "region"}
CredentialFields is every field a credential may store, so replacing one can remove what the previous kind left behind.
Functions ¶
func DockerLogin ¶
DockerLogin is the Docker login on the machine Pando runs on: config.json under DOCKER_CONFIG or ~/.docker, and the credential helpers it names.
func ECRRegion ¶
ECRRegion reads the region from an ECR registry host: 123456789012.dkr.ecr.us-east-1.amazonaws.com is us-east-1.
func NormalizeArch ¶
NormalizeArch maps the kernel's names for an architecture to the registry's.
func Pin ¶
Pin replaces a reference's tag with a digest: ghcr.io/acme/web:1.4 and sha256:ab… make ghcr.io/acme/web@sha256:ab….
The registry and repository are kept as the user wrote them rather than as a parser normalizes them, so a Docker Hub image stays nginx@sha256:… and not index.docker.io/library/nginx@sha256:….
func PlatformMismatch ¶
PlatformMismatch is the refusal for an image with no build for the host: said before anything is pulled, rather than as a container that exits on start with "exec format error".
Types ¶
type Auth ¶
type Auth struct {
Registry string
Username string
Password secret.Value
// IdentityToken is what `docker login` keeps for a registry signed in to
// through a browser, in place of a password.
IdentityToken secret.Value
}
Auth is what one pull authenticates with: resolved, short-lived, for one registry.
type Config ¶
type Config struct {
// ExposedPorts are EXPOSE'd TCP ports, lowest first.
ExposedPorts []int `json:"exposed_ports,omitempty"`
Volumes []string `json:"volumes,omitempty"`
Entrypoint []string `json:"entrypoint,omitempty"`
Cmd []string `json:"cmd,omitempty"`
WorkingDir string `json:"working_dir,omitempty"`
User string `json:"user,omitempty"`
Healthcheck *Health `json:"healthcheck,omitempty"`
}
Config is what an image's configuration declares, for one platform.
type Credential ¶
type Credential struct {
Kind CredentialKind `json:"kind"`
Username string `json:"username,omitempty"`
Password secret.Value `json:"password,omitempty"`
AccessKeyID string `json:"access_key_id,omitempty"`
SecretAccessKey secret.Value `json:"secret_access_key,omitempty"`
// Region is the ECR region. Empty reads it from the registry host.
Region string `json:"region,omitempty"`
}
Credential is an app's registry credential, as stored (O-3: it belongs to the app). Every field is sealed at rest; the secret ones are secret.Value so they cannot reach a log line (R-194).
func CredentialFrom ¶
func CredentialFrom(fields map[string]secret.Value) (Credential, bool)
CredentialFrom reads a credential back from its stored fields. It reports false when there is none.
func (Credential) Fields ¶
func (c Credential) Fields() map[string]secret.Value
Fields is the credential as stored, one sealed value per field.
func (Credential) Validate ¶
func (c Credential) Validate() error
Validate checks that a credential is complete.
type CredentialKind ¶
type CredentialKind string
CredentialKind is how an app authenticates to its image's registry.
const ( // CredentialBasic is a username and a password or token: Docker Hub, GHCR, // GitLab, Quay, Harbor, and most registries. CredentialBasic CredentialKind = "basic" // CredentialECR is an AWS access key. ECR's own registry passwords expire // after twelve hours, so the key is kept and a password minted from it for // every read and every pull. CredentialECR CredentialKind = "ecr" )
type CredentialStore ¶
type CredentialStore interface {
Put(ctx context.Context, appID, field string, v secret.Value) error
Delete(ctx context.Context, appID, field string) error
Resolve(ctx context.Context, appID string) (map[string]secret.Value, error)
}
CredentialStore keeps an app's sealed registry credential fields (state.NewRegistryCredentials).
type CredentialSummary ¶
type CredentialSummary struct {
Kind CredentialKind `json:"kind"`
Username string `json:"username,omitempty"`
AccessKeyID string `json:"access_key_id,omitempty"`
Region string `json:"region,omitempty"`
}
CredentialSummary is what may be said about an app's credential without revealing it: which kind, and the parts of it that are names rather than secrets.
type Health ¶
type Health struct {
// Command is the check to run, without Docker's CMD/CMD-SHELL marker: a
// CMD-SHELL check arrives as ["/bin/sh", "-c", script].
Command []string `json:"command"`
Interval time.Duration `json:"interval,omitempty"`
Timeout time.Duration `json:"timeout,omitempty"`
Retries int `json:"retries,omitempty"`
}
Health is a HEALTHCHECK, as the image declares it.
type Images ¶
type Images struct {
Inspector Inspector
Resolver Resolver
Credentials CredentialStore
// Docker is the Docker login on the Pando server, used for an app with no
// credential of its own (apps.docker_credentials). Nil is off.
Docker authn.Keychain
}
Images reads an app's image with the app's own credential, and keeps that credential. It is what detection, the planner, the deployer and the API share, so all of them see the same registry with the same identity.
func (*Images) Auth ¶
Auth resolves the credential for pulling reference: the app's own, or, when it has none and the install allows it, the server's Docker login. Nil, with no error, when there is neither and the pull is anonymous.
func (*Images) DescribeCredential ¶
func (im *Images) DescribeCredential(ctx context.Context, appID string) (CredentialSummary, bool, error)
DescribeCredential says whether the app has a credential and of which kind. False when it has none.
func (*Images) Inspect ¶
func (im *Images) Inspect(ctx context.Context, appID, reference string, want Platform) (Inspection, error)
Inspect reads reference as the app would pull it.
func (*Images) RemoveCredential ¶
RemoveCredential deletes the app's registry credential. Removing one that is not there is not an error.
func (*Images) SaveCredential ¶
SaveCredential replaces the app's registry credential. Every field the previous one stored is removed first, so switching from a token to AWS keys leaves no token behind.
type Inspection ¶
type Inspection struct {
// Reference is what was asked for, as given.
Reference string `json:"reference"`
// Digest is the content digest the reference resolved to — of the index
// for a multi-platform image, so the runtime still picks its own platform
// from it.
Digest string `json:"digest"`
// Platforms is every platform the image is published for.
Platforms []Platform `json:"platforms"`
// Config is the configuration of the build for the requested platform,
// and nil when there is none.
Config *Config `json:"config,omitempty"`
// Matched is the platform Config was read from.
Matched *Platform `json:"matched,omitempty"`
}
Inspection is what one read of a reference found.
func (Inspection) Pinned ¶
func (i Inspection) Pinned() string
Pinned is the reference with its digest in place of any tag.
func (Inspection) Supports ¶
func (i Inspection) Supports(host Platform) bool
Supports reports whether the image has a build that runs on host.
type Inspector ¶
type Inspector struct {
// Transport is the HTTP transport registry calls go through. Nil means the
// default; tests point it at an in-memory registry.
Transport http.RoundTripper
// Insecure allows plain HTTP, for a registry on localhost in tests.
Insecure bool
}
Inspector reads images from registries.
func (Inspector) Inspect ¶
func (in Inspector) Inspect(ctx context.Context, reference string, auth *Auth, want Platform) (Inspection, error)
Inspect resolves a reference and reads the configuration for want.
auth is nil for an anonymous read. A zero want reads no configuration and only resolves the digest, with a HEAD where the registry allows: Platforms is then empty.
type Platform ¶
type Platform struct {
OS string `json:"os"`
Architecture string `json:"architecture"`
Variant string `json:"variant,omitempty"`
}
Platform is an operating system and CPU architecture, as a registry names them: linux/amd64, linux/arm64.
func ParsePlatform ¶
ParsePlatform reads os/arch[/variant]. Docker's own spellings of the architecture (x86_64, aarch64) are accepted, because a runtime reports the host's that way.