stereoscope

README

stereoscope

           

A library for working with container image contents, layer file trees, and squashed file trees.

Getting Started

See examples/basic.go

docker image save centos:8 -o centos.tar
go run examples/basic.go ./centos.tar

Note: To run tests you will need skopeo installed.

Overview

This library provides the means to:

• parse and read images from multiple sources, supporting:
  • docker V2 schema images from the docker daemon, podman, or archive
  • OCI images from disk, directory, or registry
  • images in the local containers-storage store (e.g. images built with buildah or rootless podman) — see containers-storage source
  • singularity formatted image files
• build a file tree representing each layer blob
• create a squashed file tree representation for each layer
• search one or more file trees for selected paths
• catalog file metadata in all layers
• query the underlying image tar for content (file content within a layer)

containers-storage source

Images that are built with buildah (or rootless podman) usually live in the local containers-storage store rather than in the docker daemon. The containers-storage source resolves these images directly from the current user's default store, before falling back to a remote registry pull.

Storage location follows the current process/user via the default containers-storage configuration: rootless users use their rootless store (typically ~/.local/share/containers/storage) and root uses the rootful store (typically /var/lib/containers/storage). Stereoscope does not probe both locations; it uses the default store for the current user.

Usage (assuming the consuming binary, e.g. syft, was itself built with the containers_image_openpgp build tag described below — a stock syft release build does not include this source):

# explicit source selection
syft containers-storage:localhost/myimage:latest

# implicit resolution: a plain reference is checked against the local containers-storage
# store before falling back to the OCI registry
syft localhost/myimage:latest

[!NOTE] The containers-storage source depends on the image and storage libraries (the go.podman.io/image and go.podman.io/storage module paths that github.com/containers/image and github.com/containers/storage have moved to) and is only compiled into binaries built with the containers_image_openpgp build tag:

go build -tags containers_image_openpgp ./...

Without that tag, a stub provider keeps the source registered but reports that support was not compiled in, so default builds (and downstream consumers) are unaffected. On Linux you may additionally need to exclude the cgo graph drivers you do not have headers for, e.g. -tags "containers_image_openpgp exclude_graphdriver_btrfs exclude_graphdriver_devicemapper".

Documentation

Index

• Constants
• func Cleanup()
• func ExtractSchemeSource(userInput string, sources ...string) (source, newInput string)
• func GetImage(ctx context.Context, imgStr string, options ...Option) (*image.Image, error)
• func GetImageFromSource(ctx context.Context, imgStr string, source image.Source, options ...Option) (*image.Image, error)
• func ImageProviders(cfg ImageProviderConfig) []collections.TaggedValue[image.Provider]
• func SetBus(b *partybus.Bus)
• func SetLogger(logger logger.Logger)
• type ImageProviderConfig
• type Option
  • func WithAdditionalMetadata(metadata ...image.AdditionalMetadata) Option
  • func WithCredentials(credentials ...image.RegistryCredentials) Option
  • func WithInsecureAllowHTTP() Option
  • func WithInsecureSkipTLSVerify() Option
  • func WithLazyLayerSquashes() Option
  • func WithPlatform(platform string) Option
  • func WithRegistryOptions(options image.RegistryOptions) Option

Constants

const (
	// FileTag marks providers that read a pre-existing archive/directory from disk (no daemon or store involved).
	FileTag = "file"
	// DirTag marks providers that read from an OCI directory layout on disk.
	DirTag = "dir"
	// DaemonTag marks providers that resolve images via a running local daemon (docker, podman, containerd).
	DaemonTag = "daemon"
	// PullTag marks providers usable for auto-resolution of a bare image reference (i.e. not a file/dir path):
	// daemon providers, local content-addressed stores (e.g. containers-storage), and registry pulls all carry
	// this tag. It does not imply network access on its own.
	PullTag = "pull"
	// RegistryTag marks providers that resolve images directly from an OCI/docker registry.
	RegistryTag = "registry"
)

Functions

func Cleanup

func Cleanup()

Cleanup deletes all directories created by stereoscope calls.

Deprecated: please use image.Image.Cleanup() over this.

func ExtractSchemeSource

func ExtractSchemeSource(userInput string, sources ...string) (source, newInput string)

ExtractSchemeSource parses a string with any colon-delimited prefix and validates it against the set of known provider tags, returning a valid source name and input string to use for GetImageFromSource

NOTE: since it is now possible to select which providers to use, using schemes in the user input text is not necessary and should be avoided due to some ambiguity this introduces

func GetImage

func GetImage(ctx context.Context, imgStr string, options ...Option) (*image.Image, error)

GetImage parses the user provided image string and provides an image object; note: the source where the image should be referenced from is automatically inferred.

Cancelling ctx stops the read, but does not cut it short: see image.Image.Read for what a cancelled read still waits for and how long that can be.

func GetImageFromSource

func GetImageFromSource(ctx context.Context, imgStr string, source image.Source, options ...Option) (*image.Image, error)

GetImageFromSource returns an image from the explicitly provided source. See GetImage for what cancelling ctx does.

func ImageProviders

func ImageProviders(cfg ImageProviderConfig) []collections.TaggedValue[image.Provider]

func SetBus

func SetBus(b *partybus.Bus)

func SetLogger

func SetLogger(logger logger.Logger)

Types

type ImageProviderConfig

type ImageProviderConfig struct {
	UserInput string
	Platform  *image.Platform
	Registry  image.RegistryOptions
}

ImageProviderConfig is the user-configuration containing all configuration needed by stereoscope image providers

type Option

type Option func(*config) error

func WithAdditionalMetadata

func WithAdditionalMetadata(metadata ...image.AdditionalMetadata) Option

func WithCredentials

func WithCredentials(credentials ...image.RegistryCredentials) Option

func WithInsecureAllowHTTP

func WithInsecureAllowHTTP() Option

func WithInsecureSkipTLSVerify

func WithInsecureSkipTLSVerify() Option

func WithLazyLayerSquashes

func WithLazyLayerSquashes() Option

WithLazyLayerSquashes builds only the image squash during the read, and each lower layer's squash the first time something uses it. It applies to this call only. A context from image.WithLazyLayerSquashes gets lazy squashes with or without it. See image.WithLazyLayerSquashes for what changes for lower layers.

func WithPlatform

func WithPlatform(platform string) Option

func WithRegistryOptions

func WithRegistryOptions(options image.RegistryOptions) Option