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
  • 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)

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 WithPlatform(platform string) Option
  • func WithRegistryOptions(options image.RegistryOptions) Option

Constants

const (
	FileTag     = "file"
	DirTag      = "dir"
	DaemonTag   = "daemon"
	PullTag     = "pull"
	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.

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.

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 uber-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 WithPlatform

func WithPlatform(platform string) Option

func WithRegistryOptions

func WithRegistryOptions(options image.RegistryOptions) Option