specutils

package
v0.0.0-...-9fcf0b5 Latest Latest
Warning

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

 Go to latest Published: Dec 13, 2024 License: Apache-2.0, MIT Imports: 27 Imported by: 32

Documentation

Overview

Package specutils contains utility functions for working with OCI runtime specs.

Index

Constants

View Source 
const (
	// ContainerdContainerTypeAnnotation is the OCI annotation set by
	// containerd to indicate whether the container to create should have
	// its own sandbox or a container within an existing sandbox.
	ContainerdContainerTypeAnnotation = "io.kubernetes.cri.container-type"
	// ContainerdContainerTypeContainer is the container type value
	// indicating the container should be created in an existing sandbox.
	ContainerdContainerTypeContainer = "container"
	// ContainerdContainerTypeSandbox is the container type value
	// indicating the container should be created in a new sandbox.
	ContainerdContainerTypeSandbox = "sandbox"

	// ContainerdSandboxIDAnnotation is the OCI annotation set to indicate
	// which sandbox the container should be created in when the container
	// is not the first container in the sandbox.
	ContainerdSandboxIDAnnotation = "io.kubernetes.cri.sandbox-id"

	// CRIOContainerTypeAnnotation is the OCI annotation set by
	// CRI-O to indicate whether the container to create should have
	// its own sandbox or a container within an existing sandbox.
	CRIOContainerTypeAnnotation = "io.kubernetes.cri-o.ContainerType"

	// CRIOContainerTypeContainer is the container type value
	// indicating the container should be created in an existing sandbox.
	CRIOContainerTypeContainer = "container"
	// CRIOContainerTypeSandbox is the container type value
	// indicating the container should be created in a new sandbox.
	CRIOContainerTypeSandbox = "sandbox"

	// CRIOSandboxIDAnnotation is the OCI annotation set to indicate
	// which sandbox the container should be created in when the container
	// is not the first container in the sandbox.
	CRIOSandboxIDAnnotation = "io.kubernetes.cri-o.SandboxID"
)
View Source 
const (

	// AnnotationNVProxy enables nvproxy.
	AnnotationNVProxy = "dev.gvisor.internal.nvproxy"
)
View Source 
const (
	// AnnotationTPU is the annotation used to enable TPU proxy on a pod.
	AnnotationTPU = "dev.gvisor.internal.tpuproxy"
)

Variables

View Source 
var ExePath = "/proc/self/exe"

ExePath must point to runsc binary, which is normally the same binary. It's changed in tests that aren't linked in the same binary.

View Source 
var Version = specs.Version

Version is the supported spec version.

Functions

func AcceleratorFunctionalityRequested 

func AcceleratorFunctionalityRequested(dev *specs.LinuxDevice) bool

AcceleratorFunctionalityRequested returns true if the container should have access to compute accelerators. Compute accelerators are different from GPUs by using a different major number and different device char files.

func AllCapabilities 

func AllCapabilities() *specs.LinuxCapabilities

AllCapabilities returns a LinuxCapabilities struct with all capabilities.

func AllCapabilitiesUint64 

func AllCapabilitiesUint64() uint64

AllCapabilitiesUint64 returns a bitmask containing all capabilities set.

func AnnotationToBool 

func AnnotationToBool(spec *specs.Spec, annotation string) bool

AnnotationToBool parses the annotation value as a bool. On failure, it logs a warning and returns false.

func ApplyNS 

func ApplyNS(ns specs.LinuxNamespace) (func() error, error)

ApplyNS applies the namespace on the current thread and returns a function that will restore the namespace to the original value.

Preconditions: Must be called with os thread locked.

func Capabilities 

func Capabilities(enableRaw bool, specCaps *specs.LinuxCapabilities) (*auth.TaskCapabilities, error)

Capabilities takes in spec and returns a TaskCapabilities corresponding to the spec.

func ChangeMountType 

func ChangeMountType(m *specs.Mount, newType string)

ChangeMountType changes m.Type to the specified type. It may do necessary amends to m.Options.

func ContainerName 

func ContainerName(spec *specs.Spec) string

ContainerName looks for an annotation in the spec with the container name. Returns empty string if no annotation is found.

func DebugLogFile 

func DebugLogFile(logPattern, command, test string, timestamp time.Time) (*os.File, error)

DebugLogFile opens a log file using 'logPattern' as location. If 'logPattern' ends with '/', it's used as a directory with default file name. 'logPattern' can contain variables that are substituted:

  • %TIMESTAMP%: is replaced with a timestamp using the following format: <yyyymmdd-hhmmss.uuuuuu>
  • %COMMAND%: is replaced with 'command'
  • %TEST%: is replaced with 'test' (omitted by default)

func DropCapability 

func DropCapability(caps *specs.LinuxCapabilities, drop string)

DropCapability removes the specified capability from all capability sets.

func EnvVar 

func EnvVar(env []string, name string) (string, bool)

EnvVar looks for a variable value in the env slice assuming the following format: "NAME=VALUE". If a variable is defined multiple times, the last value is used.

func FaqErrorMsg 

func FaqErrorMsg(anchor, msg string) string

FaqErrorMsg returns an error message pointing to the FAQ.

func FilterMountOptions 

func FilterMountOptions(opts []string) []string

FilterMountOptions filters out all invalid mount options.

func GPUFunctionalityRequested 

func GPUFunctionalityRequested(spec *specs.Spec, conf *config.Config) bool

GPUFunctionalityRequested returns true if the container should have access to GPU functionality.

func GPUFunctionalityRequestedViaHook 

func GPUFunctionalityRequestedViaHook(spec *specs.Spec, conf *config.Config) bool

GPUFunctionalityRequestedViaHook returns true if the container should have access to GPU functionality configured via nvidia-container-runtime-hook. This hook is used by: - Docker when using `--gpus` flag from the CLI. - nvidia-container-runtime when using its legacy mode.

func GetNS 

func GetNS(nst specs.LinuxNamespaceType, s *specs.Spec) (specs.LinuxNamespace, bool)

GetNS returns true and the namespace with the given type from the slice of namespaces in the spec. It returns false if the slice does not contain a namespace with the type.

func GetOOMScoreAdj 

func GetOOMScoreAdj(pid int) (int, error)

GetOOMScoreAdj reads the given process' oom_score_adj

func HasCapabilities 

func HasCapabilities(cs ...capability.Cap) bool

HasCapabilities returns true if the user has all capabilities in 'cs'.

func IsDebugCommand 

func IsDebugCommand(conf *config.Config, command string) bool

IsDebugCommand returns true if the command should be debugged or not, based on the current configuration.

func IsGoferMount 

func IsGoferMount(m specs.Mount) bool

IsGoferMount returns true if the given mount can be mounted as an external gofer.

func IsLegacyCudaImage 

func IsLegacyCudaImage(spec *specs.Spec) bool

IsLegacyCudaImage returns true if spec represents a legacy CUDA image. See nvidia-container-toolkit/internal/config/image/cuda_image.go:IsLegacy().

func IsReadonlyMount 

func IsReadonlyMount(opts []string) bool

IsReadonlyMount returns true if the mount options has read only option.

func LogSpecDebug 

func LogSpecDebug(orig *specs.Spec, logSeccomp bool)

LogSpecDebug writes the spec in a human-friendly format to the debug log.

func MaybeConvertToBindMount 

func MaybeConvertToBindMount(m *specs.Mount)

MaybeConvertToBindMount converts mount type to "bind" in case any of the mount options are either "bind" or "rbind" as required by the OCI spec.

"For bind mounts (when options include either bind or rbind), the type is a dummy, often "none" (not listed in /proc/filesystems)."

func MaybeRunAsRoot 

func MaybeRunAsRoot() error

MaybeRunAsRoot ensures the process runs with capabilities needed to create a sandbox, e.g. CAP_SYS_ADMIN, CAP_SYS_CHROOT, etc. If capabilities are needed, it will create a new user namespace and re-execute the process as root inside the namespace with the same arguments and environment.

This function returns immediately when no new capability is needed. If another process is executed, it returns straight from here with the same exit code as the child.

func MergeCapabilities 

func MergeCapabilities(first, second *specs.LinuxCapabilities) *specs.LinuxCapabilities

MergeCapabilities merges the capabilites from first and second.

func NVProxyDriverCapsAllowed 

func NVProxyDriverCapsAllowed(conf *config.Config) (nvconf.DriverCaps, error)

NVProxyDriverCapsAllowed returns the driver capabilities allowed by the configuration, irrespective of what a container requests. This should be used to determine the bounding set of driver capabilities that a container can request.

func NVProxyDriverCapsFromEnv 

func NVProxyDriverCapsFromEnv(spec *specs.Spec, conf *config.Config) (nvconf.DriverCaps, error)

NVProxyDriverCapsFromEnv returns the driver capabilities requested by the application via the NVIDIA_DRIVER_CAPABILITIES env var. See nvidia-container-toolkit/cmd/nvidia-container-runtime-hook/container_config.go:getDriverCapabilities().

func NVProxyEnabled 

func NVProxyEnabled(spec *specs.Spec, conf *config.Config) bool

NVProxyEnabled checks both the nvproxy annotation and conf.NVProxy to see if nvproxy is enabled.

func OpenSpec 

func OpenSpec(bundleDir string) (*os.File, error)

OpenSpec opens an OCI runtime spec from the given bundle directory.

func OptionsToFlags 

func OptionsToFlags(opts []string) uint32

OptionsToFlags converts mount options to syscall flags.

func ParseNvidiaVisibleDevices 

func ParseNvidiaVisibleDevices(spec *specs.Spec) (string, error)

ParseNvidiaVisibleDevices parses NVIDIA_VISIBLE_DEVICES env var and returns the devices specified in it. This can be passed to nvidia-container-cli.

Precondition: conf.NVProxyDocker && GPUFunctionalityRequested(spec, conf).

func PropOptionsToFlags 

func PropOptionsToFlags(opts []string) uint32

PropOptionsToFlags converts propagation mount options to syscall flags. Propagation options cannot be set other with other options and must be handled separately.

func ReadMounts 

func ReadMounts(f *os.File) ([]specs.Mount, error)

ReadMounts reads mount list from a file.

func ReadSpec 

func ReadSpec(bundleDir string, conf *config.Config) (*specs.Spec, error)

ReadSpec reads an OCI runtime spec from the given bundle directory. ReadSpec also normalizes all potential relative paths into absolute path, e.g. spec.Root.Path, mount.Source.

func ReadSpecFromFile 

func ReadSpecFromFile(bundleDir string, specFile *os.File, conf *config.Config) (*specs.Spec, error)

ReadSpecFromFile reads an OCI runtime spec from the given file. It also fixes up the spec so that the rest of the code doesn't need to worry about it.

  1. Normalizes all relative paths into absolute by prepending the bundle dir to them.
  2. Looks for flag overrides and applies them if any.
  3. Removes seccomp rules if `RuntimeDefault` was used.

func ResolveEnvs 

func ResolveEnvs(envs ...[]string) ([]string, error)

ResolveEnvs transforms lists of environment variables into a single list of environment variables. If a variable is defined multiple times, the last value is used.

func RetryEintr 

func RetryEintr(f func() (uintptr, uintptr, error)) (uintptr, uintptr, error)

RetryEintr retries the function until an error different than EINTR is returned.

func SafeMount 

func SafeMount(src, dst, fstype string, flags uintptr, data, procPath string) error

SafeMount is like unix.Mount, but will fail if dst is a symlink. procPath is the path to procfs. If it is "", procfs is assumed to be mounted at /proc.

SafeMount can fail when dst contains a symlink. However, it is called in the normal case with a destination consisting of a known root (/proc/root) and symlink-free path (from resolveSymlink).

func SafeSetupAndMount 

func SafeSetupAndMount(src, dst, typ string, flags uint32, procPath string) error

SafeSetupAndMount creates the mount point and calls Mount with the given flags. procPath is the path to procfs. If it is "", procfs is assumed to be mounted at /proc.

func SandboxID 

func SandboxID(spec *specs.Spec) (string, bool)

SandboxID returns the ID of the sandbox to join and whether an ID was found in the spec.

func SetUIDGIDMappings 

func SetUIDGIDMappings(cmd *exec.Cmd, s *specs.Spec)

SetUIDGIDMappings sets the given uid/gid mappings from the spec on the cmd.

func StartInNS 

func StartInNS(cmd *exec.Cmd, nss []specs.LinuxNamespace) error

StartInNS joins or creates the given namespaces and calls cmd.Start before restoring the namespaces to the original values.

func TPUFunctionalityRequested 

func TPUFunctionalityRequested(spec *specs.Spec, conf *config.Config) bool

TPUFunctionalityRequested returns true if the container should have access to TPU functionality.

func TPUProxyIsEnabled 

func TPUProxyIsEnabled(spec *specs.Spec, conf *config.Config) bool

TPUProxyIsEnabled checks if tpuproxy is enabled in the config or annotations.

func VFIOFunctionalityRequested 

func VFIOFunctionalityRequested(dev *specs.LinuxDevice) bool

VFIOFunctionalityRequested returns true if the container should have access to VFIO functionality.

func ValidateMountOptions 

func ValidateMountOptions(opts []string) error

ValidateMountOptions validates that mount options are correct.

func ValidateSpec 

func ValidateSpec(spec *specs.Spec) error

ValidateSpec validates that the spec is compatible with runsc.

func WaitForReady 

func WaitForReady(pid int, timeout time.Duration, ready func() (bool, error)) error

WaitForReady waits for a process to become ready. The process is ready when the 'ready' function returns true. It continues to wait if 'ready' returns false. It returns error on timeout, if the process stops or if 'ready' fails.

Types

type ContainerType 

type ContainerType int

ContainerType represents the type of container requested by the calling container manager. 

const (
	// ContainerTypeUnspecified indicates that no known container type
	// annotation was found in the spec.
	ContainerTypeUnspecified ContainerType = iota
	// ContainerTypeUnknown indicates that a container type was specified
	// but is unknown to us.
	ContainerTypeUnknown
	// ContainerTypeSandbox indicates that the container should be run in a
	// new sandbox.
	ContainerTypeSandbox
	// ContainerTypeContainer indicates that the container should be run in
	// an existing sandbox.
	ContainerTypeContainer
)

func SpecContainerType 

func SpecContainerType(spec *specs.Spec) ContainerType

SpecContainerType tries to determine the type of container specified by the container manager using well-known container annotations.

type ErrSymlinkMount 

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

ErrSymlinkMount is returned by SafeMount when the mount destination is found to be a symlink.

Source Files

View all Source files

Directories

Path Synopsis
safemount_runner is used to test the SafeMount function.
 safemount_runner is used to test the SafeMount function.
Package seccomp implements some features of libseccomp in order to support OCI.
 Package seccomp implements some features of libseccomp in order to support OCI.

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.