storage

Documentation

Overview

Package storage provides helper functions for creating and managing CRI pod sandboxes and containers and metadata associated with them in the format that crio understands. The API it provides should be considered to be unstable.

Index

• Variables
• func CompileRegexpsForPinnedImages(patterns []string) []*regexp.Regexp
• func FilterPinnedImage(image string, pinnedImages []*regexp.Regexp) bool
• func IsCrioContainer(md *RuntimeContainerMetadata) bool
• type CgroupPullConfiguration
• type ContainerInfo
• type ImageCopyOptions
• type ImageResult
• type ImageServer
  • func GetImageService(ctx context.Context, store storage.Store, storageTransport StorageTransport, ...) (ImageServer, error)
• type RegistryImageReference
• type RuntimeContainerMetadata
  • func (metadata *RuntimeContainerMetadata) SetMountLabel(mountLabel string)
• type RuntimeServer
  • func GetRuntimeService(ctx context.Context, storageImageServer ImageServer, ...) RuntimeServer
• type StorageImageID
  • func ParseStorageImageIDFromOutOfProcessData(input string) (StorageImageID, error)
  • func (id StorageImageID) Format(f fmt.State, verb rune)
  • func (id StorageImageID) IDStringForOutOfProcessConsumptionOnly() string
• type StorageTransport

Variables

var (
	// ErrInvalidPodName is returned when a pod name specified to a
	// function call is found to be invalid (most often, because it's
	// empty).
	ErrInvalidPodName = errors.New("invalid pod name")
	// ErrInvalidContainerName is returned when a container name specified
	// to a function call is found to be invalid (most often, because it's
	// empty).
	ErrInvalidContainerName = errors.New("invalid container name")
	// ErrInvalidSandboxID is returned when a sandbox ID specified to a
	// function call is found to be invalid (because it's either
	// empty or doesn't match a valid sandbox).
	ErrInvalidSandboxID = errors.New("invalid sandbox ID")
	// ErrInvalidContainerID is returned when a container ID specified to a
	// function call is found to be invalid (because it's either
	// empty or doesn't match a valid container).
	ErrInvalidContainerID = errors.New("invalid container ID")
)

var ImageBeingPulled sync.Map

ImageBeingPulled map[string]bool to keep track of the images haven't done pulling.

Functions

func CompileRegexpsForPinnedImages

func CompileRegexpsForPinnedImages(patterns []string) []*regexp.Regexp

CompileRegexpsForPinnedImages compiles regular expressions for the given list of pinned images.

func FilterPinnedImage

func FilterPinnedImage(image string, pinnedImages []*regexp.Regexp) bool

FilterPinnedImage checks if the given image needs to be pinned and excluded from kubelet's image GC.

func IsCrioContainer

func IsCrioContainer(md *RuntimeContainerMetadata) bool

IsCrioContainer returns whether a container coming from storage was created by CRI-O sandboxes and containers differ from podman container and pods because they require a PodName and PodID annotation

Types

type CgroupPullConfiguration

type CgroupPullConfiguration struct {
	UseNewCgroup bool
	ParentCgroup string
}

CgroupPullConfiguration WARNING: All of imageLookupService must be JSON-representable because it is included in pullImageArgs.

type ContainerInfo

type ContainerInfo struct {
	ID           string
	Dir          string
	RunDir       string
	Config       *v1.Image
	ProcessLabel string
	MountLabel   string
}

ContainerInfo wraps a subset of information about a container: its ID and the locations of its nonvolatile and volatile per-container directories, along with a copy of the configuration blob from the image that was used to create the container, if the image had a configuration.

type ImageCopyOptions

type ImageCopyOptions struct {
	SourceCtx        *types.SystemContext
	DestinationCtx   *types.SystemContext
	OciDecryptConfig *encconfig.DecryptConfig
	ProgressInterval time.Duration
	Progress         chan types.ProgressProperties `json:"-"`
	CgroupPull       CgroupPullConfiguration
}

subset of copy.Options that is supported by reexec. WARNING: All ofImageCopyOptions must be JSON-representable because it is included in pullImageArgs.

type ImageResult

type ImageResult struct {
	ID StorageImageID
	// May be nil if the image was referenced by ID and has no names.
	// It also has NO RELATIONSHIP to user input when returned by ImageStatusByName.
	SomeNameOfThisImage *RegistryImageReference
	RepoTags            []string
	RepoDigests         []string
	Size                *uint64
	Digest              digest.Digest
	ConfigDigest        digest.Digest
	User                string
	PreviousName        string
	Labels              map[string]string
	OCIConfig           *specs.Image
	Annotations         map[string]string
	Pinned              bool // pinned image to prevent it from garbage collection
}

ImageResult wraps a subset of information about an image: its ID, its names, and the size, if known, or nil if it isn't.

type ImageServer

type ImageServer interface {
	// ListImages returns list of all images.
	ListImages(systemContext *types.SystemContext) ([]ImageResult, error)
	// ImageStatusByID returns status of a single image
	ImageStatusByID(systemContext *types.SystemContext, id StorageImageID) (*ImageResult, error)
	// ImageStatusByName returns status of an image tagged with name.
	ImageStatusByName(systemContext *types.SystemContext, name RegistryImageReference) (*ImageResult, error)

	// PrepareImage returns an Image where the config digest can be grabbed
	// for further analysis. Call Close() on the resulting image.
	PrepareImage(systemContext *types.SystemContext, imageName RegistryImageReference) (types.ImageCloser, error)
	// PullImage imports an image from the specified location.
	PullImage(ctx context.Context, imageName RegistryImageReference, options *ImageCopyOptions) (types.ImageReference, error)

	// DeleteImage deletes a storage image (impacting all its tags)
	DeleteImage(systemContext *types.SystemContext, id StorageImageID) error
	// UntagImage removes a name from the specified image, and if it was
	// the only name the image had, removes the image.
	UntagImage(systemContext *types.SystemContext, name RegistryImageReference) error

	// GetStore returns the reference to the storage library Store which
	// the image server uses to hold images, and is the destination used
	// when it's asked to pull an image.
	GetStore() storage.Store

	// HeuristicallyTryResolvingStringAsIDPrefix checks if heuristicInput could be a valid image ID or a prefix, and returns
	// a StorageImageID if so, or nil if the input can be something else.
	// DO NOT CALL THIS from in-process callers who know what their input is and don't NEED to involve heuristics.
	HeuristicallyTryResolvingStringAsIDPrefix(heuristicInput string) *StorageImageID
	// CandidatesForPotentiallyShortImageName resolves an image name into a set of fully-qualified image names (domain/repo/image:tag|@digest).
	// It will only return an empty slice if err != nil.
	CandidatesForPotentiallyShortImageName(systemContext *types.SystemContext, imageName string) ([]RegistryImageReference, error)

	// UpdatePinnedImagesList updates pinned and pause images list in imageService.
	UpdatePinnedImagesList(imageList []string)
}

ImageServer wraps up various CRI-related activities into a reusable implementation.

func GetImageService

func GetImageService(ctx context.Context, store storage.Store, storageTransport StorageTransport, serverConfig *config.Config) (ImageServer, error)

GetImageService returns an ImageServer that uses the passed-in store, and which will prepend the passed-in DefaultTransport value to an image name if a name that's passed to its PullImage() method can't be resolved to an image in the store and can't be resolved to a source on its own.

type RegistryImageReference

type RegistryImageReference = references.RegistryImageReference

RegistryImageReference is a name of a specific image location on a registry. The image may or may not exist, and, in general, what image the name points to may change over time.

More specifically: - The name always specifies a registry; it is not an alias nor a short name input to a search - The name contains a tag or digest; it does not specify just a repo.

This is intended to be a value type; if a value exists, it contains a valid reference.

type RuntimeContainerMetadata

type RuntimeContainerMetadata struct {
	// The pod's name and ID, kept for use by upper layers in determining
	// which containers belong to which pods.
	PodName string `json:"pod-name"` // Applicable to both PodSandboxes and Containers, mandatory
	PodID   string `json:"pod-id"`   // Applicable to both PodSandboxes and Containers, mandatory
	// The users' input originally used to find imageID; it might evaluate to a different image (or to a different kind of reference!) at any future time.
	ImageName string `json:"image-name"` // Applicable to both PodSandboxes and Containers
	// The ID of the image that was used to instantiate the container.
	ImageID string `json:"image-id"` // Applicable to both PodSandboxes and Containers
	// The container's name, which for an infrastructure container is usually PodName + "-infra".
	ContainerName string `json:"name"` // Applicable to both PodSandboxes and Containers, mandatory
	// The name as originally specified in PodSandbox or Container CRI metadata.
	MetadataName string `json:"metadata-name"`        // Applicable to both PodSandboxes and Containers, mandatory
	UID          string `json:"uid,omitempty"`        // Only applicable to pods
	Namespace    string `json:"namespace,omitempty"`  // Only applicable to pods
	MountLabel   string `json:"mountlabel,omitempty"` // Applicable to both PodSandboxes and Containers
	CreatedAt    int64  `json:"created-at"`           // Applicable to both PodSandboxes and Containers
	Attempt      uint32 `json:"attempt,omitempty"`    // Applicable to both PodSandboxes and Containers
	// Pod is true if this is the pod's infrastructure container.
	Pod        bool `json:"pod,omitempty"`        // Applicable to both PodSandboxes and Containers
	Privileged bool `json:"privileged,omitempty"` // Applicable to both PodSandboxes and Containers
}

RuntimeContainerMetadata is the structure that we encode as JSON and store in the metadata field of storage.Container objects. It is used for specifying attributes of pod sandboxes and containers when they are being created, and allows a container's MountLabel, and possibly other values, to be modified in one read/write cycle via calls to RuntimeServer.ContainerMetadata, RuntimeContainerMetadata.SetMountLabel, and RuntimeServer.SetContainerMetadata.

func (*RuntimeContainerMetadata) SetMountLabel

func (metadata *RuntimeContainerMetadata) SetMountLabel(mountLabel string)

SetMountLabel updates the mount label held by a RuntimeContainerMetadata object.

type RuntimeServer

type RuntimeServer interface {
	// CreatePodSandbox creates a pod infrastructure container, using the
	// specified PodID for the infrastructure container's ID.  In the CRI
	// view of things, a sandbox is distinct from its containers, including
	// its infrastructure container, but at this level the sandbox is
	// essentially the same as its infrastructure container, with a
	// container's membership in a pod being signified by it listing the
	// same pod ID in its metadata that the pod's other members do, and
	// with the pod's infrastructure container having the same value for
	// both its pod's ID and its container ID.
	// Pointer arguments can be nil.  All other arguments are required.
	CreatePodSandbox(systemContext *types.SystemContext, podName, podID string, pauseImage RegistryImageReference, imageAuthFile, containerName, metadataName, uid, namespace string, attempt uint32, idMappingsOptions *storage.IDMappingOptions, labelOptions []string, privileged bool) (ContainerInfo, error)

	// GetContainerMetadata returns the metadata we've stored for a container.
	GetContainerMetadata(idOrName string) (RuntimeContainerMetadata, error)
	// SetContainerMetadata updates the metadata we've stored for a container.
	SetContainerMetadata(idOrName string, metadata *RuntimeContainerMetadata) error

	// CreateContainer creates a container with the specified ID.
	// Pointer arguments can be nil.
	// All other arguments are required.
	CreateContainer(systemContext *types.SystemContext, podName, podID, userRequestedImage string, imageID StorageImageID, containerName, containerID, metadataName string, attempt uint32, idMappingsOptions *storage.IDMappingOptions, labelOptions []string, privileged bool) (ContainerInfo, error)
	// DeleteContainer deletes a container, unmounting it first if need be.
	DeleteContainer(ctx context.Context, idOrName string) error

	// StartContainer makes sure a container's filesystem is mounted, and
	// returns the location of its root filesystem, which is not guaranteed
	// by lower-level drivers to never change.
	StartContainer(idOrName string) (string, error)
	// StopContainer attempts to unmount a container's root filesystem,
	// freeing up any kernel resources which may be limited.
	StopContainer(ctx context.Context, idOrName string) error

	// GetWorkDir returns the path of a nonvolatile directory on the
	// filesystem (somewhere under the Store's Root directory) which can be
	// used to store arbitrary data that is specific to the container.  It
	// will be removed automatically when the container is deleted.
	GetWorkDir(id string) (string, error)
	// GetRunDir returns the path of a volatile directory (does not survive
	// the host rebooting, somewhere under the Store's RunRoot directory)
	// on the filesystem which can be used to store arbitrary data that is
	// specific to the container.  It will be removed automatically when
	// the container is deleted.
	GetRunDir(id string) (string, error)
}

RuntimeServer wraps up various CRI-related activities into a reusable implementation.

func GetRuntimeService

func GetRuntimeService(ctx context.Context, storageImageServer ImageServer, storageTransport StorageTransport) RuntimeServer

GetRuntimeService returns a RuntimeServer that uses the passed-in image service to pull and manage images, and its store to manage containers based on those images.

type StorageImageID

type StorageImageID struct {
	// contains filtered or unexported fields
}

StorageImageID is a stable identifier for a (deduplicated) image in a local storage. The image referenced by the ID is _mostly_ immutable, notably the layers and config will never change; the names and some other metadata may change (as images are deduplicated).

An ID might not refer to an image (e.g. if the image was deleted, or if the ID never referred to an image in the first place).

This is intended to be a value type; if a value exists, it is a correctly-formatted ID. The values can be compared for equality, or used as map keys.

func ParseStorageImageIDFromOutOfProcessData

func ParseStorageImageIDFromOutOfProcessData(input string) (StorageImageID, error)

ParseStorageImageIDFromOutOfProcessData constructs a StorageImageID from a string. It is only intended for communication with OUT-OF-PROCESS APIs, like image IDs provided by CRI by Kubelet (who got it from CRI-O’s StorageImageID.IDStringForOutOfProcessConsumptionOnly() in the first place).

func (StorageImageID) Format

func (id StorageImageID) Format(f fmt.State, verb rune)

Format() is implemented so that log entries can be written, without providing a convenient String() method.

func (StorageImageID) IDStringForOutOfProcessConsumptionOnly

func (id StorageImageID) IDStringForOutOfProcessConsumptionOnly() string

IDStringForOutOfProcessConsumptionOnly is only intended for communication with OUT-OF-PROCESS APIs, like image IDs in CRI to provide stable identifiers to Kubelet.

StorageImageID intentionally does not implement String(). Use typed values wherever possible.

type StorageTransport

type StorageTransport interface {
	ResolveReference(ref types.ImageReference) (types.ImageReference, *storage.Image, error)
}

StorageTransport is a level of indirection to allow mocking istorage.ResolveReference