bottle

Documentation

Overview

Package bottle provides functions for managing transfer of bottle objects to and from an OCI registry, including configuring a pulled bottle, and establishing local metadata and file structure.

Index

• func FetchBottleMetadata(ctx context.Context, src content.ReadOnlyGraphStorage, desc ocispec.Descriptor, ...) ([]byte, []byte, error)
• func Pull(ctx context.Context, src content.ReadOnlyStorage, desc ocispec.Descriptor, ...) error
• func Resolve(ctx context.Context, reference string, src reg.ReadOnlyGraphTargeter, ...) (oras.ReadOnlyGraphTarget, ocispec.Descriptor, error)
• type PartSelectorOptions
• type PullOptions
• type TransferOptions

Examples

• Pull
• Pull (Partselection)

Functions

func FetchBottleMetadata

func FetchBottleMetadata(ctx context.Context, src content.ReadOnlyGraphStorage, desc ocispec.Descriptor,
	pullOpts PullOptions,
) ([]byte, []byte, error)

FetchBottleMetadata retrieves a bottle's config and manifest from a remote source.

func Pull

func Pull(ctx context.Context, src content.ReadOnlyStorage, desc ocispec.Descriptor, pullPath string,
	pullOpts PullOptions,
) error

Pull facilitates the copying of bottles, and signatures, from a remote registry to a local directory.

Example

log := slog.New(slog.Default().Handler())
ctx := logger.NewContext(context.Background(), log)

// setup pull destination
bottleDir, err := pullDirHelper.SetupPullDir()
if err != nil {
	panic(fmt.Sprintf("Failed to set up bottle pull directory: %v", err))
}

// define default configuration
// overrides are only necessary if the desired configuration is not
// available by default or loaded from a file with config.AddConfigFiles().
config := conf.New()
config.AddConfigOverride(conf.WithRegistryConfig(registryConfig), conf.WithCachePath(cachePath)) // configure testing registry for plain-http

src, desc, err := Resolve(ctx, ociReference, config, TransferOptions{})
if err != nil {
	panic(fmt.Sprintf("Failed to resolve OCI reference: %v", err))
}

// also fails on send telemetry event failure
err = Pull(ctx, src, desc, bottleDir, PullOptions{TransferOptions: TransferOptions{CachePath: cachePath}})
if err != nil {
	panic(fmt.Sprintf("Bottle pull failed: %v\n", err))
}
fmt.Fprintf(os.Stdout, "Success")

Output:

Success

Example (Partselection)

log := slog.New(slog.Default().Handler())
ctx := logger.NewContext(context.Background(), log)

// setup pull destination
pullDir, err := pullDirHelper.SetupPullDir()
if err != nil {
	panic(fmt.Sprintf("Failed to set up bottle pull directory: %v", err))
}

// define default configuration
// overrides are only necessary if the desired configuration is not
// available by default or loaded from a file with config.AddConfigFiles().
config := conf.New()
config.AddConfigOverride(conf.WithRegistryConfig(registryConfig)) // configure testing registry for plain-http

src, desc, err := Resolve(ctx, ociReference, config, TransferOptions{})
if err != nil {
	panic(fmt.Sprintf("Failed to resolve OCI reference: %v", err))
}

// define part selection
labelSelectors := []string{"foo=bar"}

pullOpts := PullOptions{
	TransferOptions: TransferOptions{
		CachePath: cachePath,
	},
	PartSelectorOptions: PartSelectorOptions{
		Labels: labelSelectors,
	},
}

// also fails on send telemetry event failure
err = Pull(ctx, src, desc, pullDir, pullOpts)
if err != nil {
	panic(fmt.Sprintf("Bottle pull failed: %v\n", err))
}
fmt.Fprintf(os.Stdout, "Success")

Output:

Success

func Resolve

func Resolve(ctx context.Context, reference string, src reg.ReadOnlyGraphTargeter, transferOpts TransferOptions) (oras.ReadOnlyGraphTarget, ocispec.Descriptor, error)

Resolve uses the source ReadOnlyGraphTargeter to resolve an OCI reference to a manifest descriptor. At minimum the reference must include the "<registry>/<repository>" section of an OCI reference.

Types

type PartSelectorOptions

type PartSelectorOptions = bottle.PartSelectorOptions

PartSelectorOptions are options for creating a PartSelector. Bottle parts may be selected by label, part name, or included public artifact. It is highly recommended to use the CachePath option in TransferOptions alongside these options to enable pushing of a partially pulled bottle, otherwise it will fail.

type PullOptions

type PullOptions struct {
	TransferOptions
	PartSelectorOptions
}

PullOptions provides options for pulling bottles from remote registry to the localhost.

type TransferOptions

type TransferOptions struct {
	// Optional, with defaults
	Concurrency int // default: 5

	// Optional, used for tracking virtual parts when pulling bottles with selectors
	// as well as caching blobs
	CachePath string
}

TransferOptions configures bottle transfers between a remote registry and localhost. Used to compose PullOptions and PushOptions.