storage

package
v1.29.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2024 License: Apache-2.0 Imports: 34 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
var ImageBeingPulled sync.Map

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

Functions

func CompileRegexpsForPinnedImages added in v1.28.0 

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

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

func FilterPinnedImage added in v1.28.0 

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 added in v1.20.0 

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 added in v1.20.0 

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(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)
}

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 added in v1.29.0 

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 added in v1.29.0 

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 added in v1.29.0 

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 added in v1.29.0 

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 added in v1.29.0 

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 added in v1.29.0 

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

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.