specutils

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Apr 30, 2024 License: Apache-2.0, MIT Imports: 28 Imported by: 0

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

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

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 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 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.

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