Documentation
¶
Overview ¶
Package ocibundle pulls a bundle of configuration files from an OCI registry. It is shared by the clients that pull on the user's machine and by the server, which pulls on the caller's behalf; the server passes the limits and the restricted HTTP client from NewPublicHTTPClient.
Index ¶
- Constants
- func IsPublicAddress(addr netip.Addr) bool
- func IsRef(input string) bool
- func NewPublicHTTPClient() *http.Client
- func NewestRelease(ctx context.Context, rawRepo string, opts Options) (string, error)
- func ReadImageFile(ctx context.Context, rawRef, filePath string, opts Options) ([]byte, string, error)
- type Bundle
- type Credentials
- type File
- type Limits
- type Options
Constants ¶
const Scheme = "oci://"
Scheme prefixes an OCI reference given where a file or directory could be.
Variables ¶
This section is empty.
Functions ¶
func IsPublicAddress ¶
IsPublicAddress reports whether addr is a globally routable unicast address: not loopback, private, link-local (which holds the 169.254.169.254 metadata endpoint), unique-local, multicast, or unspecified.
func IsRef ¶
IsRef reports whether an input is an OCI reference rather than a file, directory, or "-".
func NewPublicHTTPClient ¶
NewPublicHTTPClient returns a client for pulling on someone else's behalf: it speaks only HTTPS and connects only to public addresses. A registry reference is caller-supplied, so without these checks a pull could reach the puller's own network -- a cloud metadata endpoint, a database, an internal service. The address is checked when each connection is dialed, after DNS resolution, so a name that resolves to a private address is refused too, as is every redirect and token request, since they are all dialed the same way.
func NewestRelease ¶ added in v0.9.12
NewestRelease returns the newest tag of a repository that names a release: X.Y.Z, with or without a leading "v". Other tags, such as latest or a pre-release, are passed over. rawRepo names the repository, without a tag.
func ReadImageFile ¶ added in v0.9.12
func ReadImageFile(ctx context.Context, rawRef, filePath string, opts Options) ([]byte, string, error)
ReadImageFile reads one file from a container image without running it, such as configuration an image ships beside its binary. Layers are read from the newest down, and the first that holds the file wins, as in the image's filesystem, so an image that adds the file in its last layer costs one small fetch. An image index is read through its first platform's image, so the file has to be the same on every platform. It returns the file and the digest of the manifest the reference resolved to. opts.Include is ignored.
Types ¶
type Bundle ¶
type Bundle struct {
// Digest is the digest of the manifest the reference resolved to. Pulling
// Ref@Digest later reads exactly the same bundle.
Digest string
Files []File
}
Bundle is what a pull extracted.
func Pull ¶
Pull fetches an OCI artifact and extracts the files it carries. The artifact may carry them as a tar or tar+gzip layer (as `cub release publish` and Flux produce) or as individual file layers (as `oras push <files>` produces), so any bundle a GitOps toolchain can consume works here. A non-empty digest pulls that manifest instead of the one the reference's tag names now.
type Credentials ¶
Credentials authenticate a pull. Registries that issue access tokens take the token as the password.
type Limits ¶
type Limits struct {
MaxManifestBytes int64
MaxLayers int
// MaxLayerBytes bounds each layer as stored, before decompression.
MaxLayerBytes int64
// MaxFiles and MaxTotalBytes bound the files extracted, after decompression,
// so a small compressed layer cannot expand without bound.
MaxFiles int
MaxTotalBytes int64
}
Limits bound what a pull reads. A zero field is unlimited.
type Options ¶
type Options struct {
// Credentials are used for this pull only. Nil pulls anonymously.
Credentials *Credentials
UserAgent string
// HTTPClient carries every request, including token and redirect requests.
// Nil uses a client that retries transient failures.
HTTPClient *http.Client
// PlainHTTPLoopback pulls from a loopback registry over plain HTTP, as local
// development registries are served.
PlainHTTPLoopback bool
// Include selects the files to extract by path. Nil extracts every file.
Include func(path string) bool
Limits Limits
}
Options configure a pull.