Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyOpts(ctx context.Context, client Client, c *containers.Container, s *Spec, ...) error
- func DeviceFromPath(path string) (*specs.LinuxDevice, error)
- func GIDFromPath(root string, filter func(user.Group) bool) (gid uint32, err error)
- func HostDevices() ([]specs.LinuxDevice, error)
- func UserFromPath(root string, filter func(user.User) bool) (user.User, error)
- func WithAllDevicesAllowed(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithDefaultPathEnv(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithDefaultUnixDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithHostDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithHostHostsFile(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithHostLocaltime(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithHostResolvconf(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithNewPrivileges(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithNoNewPrivileges(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithParentCgroupDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithSeccompUnconfined(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithTTY(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithWindowsHyperV(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithWriteableCgroupfs(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithWriteableSysfs(_ context.Context, _ Client, _ *containers.Container, s *Spec) error
- func WithoutRunMount(ctx context.Context, client Client, c *containers.Container, s *Spec) error
- type Client
- type Image
- type Spec
- type SpecOpts
- func Compose(opts ...SpecOpts) SpecOpts
- func WithAddedCapabilities(caps []string) SpecOpts
- func WithAdditionalGIDs(userstr string) SpecOpts
- func WithAmbientCapabilities(caps []string) SpecOpts
- func WithAnnotations(annotations map[string]string) SpecOpts
- func WithApparmorProfile(profile string) SpecOpts
- func WithAppendAdditionalGroups(groups ...string) SpecOpts
- func WithCPUCFS(quota int64, period uint64) SpecOpts
- func WithCPUShares(shares uint64) SpecOpts
- func WithCPUs(cpus string) SpecOpts
- func WithCPUsMems(mems string) SpecOpts
- func WithCapabilities(caps []string) SpecOpts
- func WithCgroup(path string) SpecOpts
- func WithDefaultSpec() SpecOpts
- func WithDefaultSpecForPlatform(platform string) SpecOpts
- func WithDevShmSize(kb int64) SpecOpts
- func WithDevices(devicePath, containerPath, permissions string) SpecOpts
- func WithDroppedCapabilities(caps []string) SpecOpts
- func WithEnv(environmentVariables []string) SpecOpts
- func WithEnvFile(path string) SpecOpts
- func WithHostNamespace(ns specs.LinuxNamespaceType) SpecOpts
- func WithHostname(name string) SpecOpts
- func WithImageConfig(image Image) SpecOpts
- func WithImageConfigArgs(image Image, args []string) SpecOpts
- func WithLinuxDevice(path, permissions string) SpecOpts
- func WithLinuxDevices(devices []specs.LinuxDevice) SpecOpts
- func WithLinuxNamespace(ns specs.LinuxNamespace) SpecOpts
- func WithMaskedPaths(paths []string) SpecOpts
- func WithMemoryLimit(limit uint64) SpecOpts
- func WithMemorySwap(swap int64) SpecOpts
- func WithMounts(mounts []specs.Mount) SpecOpts
- func WithNamespacedCgroup() SpecOpts
- func WithPidsLimit(limit int64) SpecOpts
- func WithProcessArgs(args ...string) SpecOpts
- func WithProcessCwd(cwd string) SpecOpts
- func WithRdt(closID, l3CacheSchema, memBwSchema string) SpecOpts
- func WithReadonlyPaths(paths []string) SpecOpts
- func WithRootFSPath(path string) SpecOpts
- func WithRootFSReadonly() SpecOpts
- func WithSelinuxLabel(label string) SpecOpts
- func WithSpecFromBytes(p []byte) SpecOpts
- func WithSpecFromFile(filename string) SpecOpts
- func WithTTYSize(width, height int) SpecOpts
- func WithUIDGID(uid, gid uint32) SpecOpts
- func WithUser(userstr string) SpecOpts
- func WithUserID(uid uint32) SpecOpts
- func WithUserNamespace(uidMap, gidMap []specs.LinuxIDMapping) SpecOpts
- func WithUsername(username string) SpecOpts
- func WithoutMounts(dests ...string) SpecOpts
Constants ¶
const ConfigFilename = "config.json"
Variables ¶
var ErrNoGroupsFound = errors.New("no groups found")
ErrNoGroupsFound can be returned from GIDFromPath
var ErrNoShmMount = errors.New("no /dev/shm mount specified")
ErrNoShmMount is returned when there is no /dev/shm mount specified in the config and an Opts was trying to set a configuration value on the mount.
var ErrNoUsersFound = errors.New("no users found")
ErrNoUsersFound can be returned from UserFromPath
var ErrNotADevice = errors.New("not a device node")
ErrNotADevice denotes that a file is not a valid linux device.
var WithAllCurrentCapabilities = func(ctx context.Context, client Client, c *containers.Container, s *Spec) error { caps, err := cap.Current() if err != nil { return err } return WithCapabilities(caps)(ctx, client, c, s) }
WithAllCurrentCapabilities propagates the effective capabilities of the caller process to the container process. The capability set may differ from WithAllKnownCapabilities when running in a container.
var WithAllKnownCapabilities = func(ctx context.Context, client Client, c *containers.Container, s *Spec) error { caps := cap.Known() return WithCapabilities(caps)(ctx, client, c, s) }
WithAllKnownCapabilities sets all the known linux capabilities for the container process
var WithPrivileged = Compose( WithAllCurrentCapabilities, WithMaskedPaths(nil), WithReadonlyPaths(nil), WithWriteableSysfs, WithWriteableCgroupfs, WithSelinuxLabel(""), WithApparmorProfile(""), WithSeccompUnconfined, )
WithPrivileged sets up options for a privileged container
Functions ¶
func ApplyOpts ¶ added in v1.2.0
func ApplyOpts(ctx context.Context, client Client, c *containers.Container, s *Spec, opts ...SpecOpts) error
ApplyOpts applies the options to the given spec, injecting data from the context, client and container instance.
func DeviceFromPath ¶ added in v1.6.0
func DeviceFromPath(path string) (*specs.LinuxDevice, error)
DeviceFromPath takes the path to a device to look up the information about a linux device and returns that information as a LinuxDevice struct.
func GIDFromPath ¶ added in v1.5.0
GIDFromPath inspects the GID using /etc/group in the specified rootfs. filter can be nil.
func HostDevices ¶ added in v1.5.0
func HostDevices() ([]specs.LinuxDevice, error)
HostDevices returns all devices that can be found under /dev directory.
func UserFromPath ¶ added in v1.5.0
UserFromPath inspects the user object using /etc/passwd in the specified rootfs. filter can be nil.
func WithAllDevicesAllowed ¶ added in v1.4.0
WithAllDevicesAllowed permits READ WRITE MKNOD on all devices nodes for the container
func WithDefaultPathEnv ¶ added in v1.2.8
WithDefaultPathEnv sets the $PATH environment variable to the default PATH defined in this package.
func WithDefaultUnixDevices ¶ added in v1.2.0
WithDefaultUnixDevices adds the default devices for unix such as /dev/null, /dev/random to the container's resource cgroup spec
func WithHostDevices ¶ added in v1.4.0
WithHostDevices adds all the hosts device nodes to the container's spec
func WithHostHostsFile ¶
WithHostHostsFile bind-mounts the host's /etc/hosts into the container as readonly
func WithHostLocaltime ¶
WithHostLocaltime bind-mounts the host's /etc/localtime into the container as readonly
func WithHostResolvconf ¶
WithHostResolvconf bind-mounts the host's /etc/resolv.conf into the container as readonly
func WithNewPrivileges ¶ added in v1.1.4
WithNewPrivileges turns off the NoNewPrivileges feature flag in the spec
func WithNoNewPrivileges ¶
WithNoNewPrivileges sets no_new_privileges on the process for the container
func WithParentCgroupDevices ¶ added in v1.2.0
WithParentCgroupDevices uses the default cgroup setup to inherit the container's parent cgroup's allowed and denied devices
func WithSeccompUnconfined ¶ added in v1.1.0
WithSeccompUnconfined clears the seccomp profile
func WithTTY ¶
WithTTY sets the information on the spec as well as the environment variables for using a TTY
func WithWindowsHyperV ¶ added in v1.2.0
WithWindowsHyperV sets the Windows.HyperV section for HyperV isolation of containers.
func WithWriteableCgroupfs ¶ added in v1.1.0
WithWriteableCgroupfs makes any cgroup mounts writeable
func WithWriteableSysfs ¶ added in v1.1.0
WithWriteableSysfs makes any sysfs mounts writeable
func WithoutRunMount ¶ added in v1.5.0
WithoutRunMount removes the `/run` inside the spec
Types ¶
type Client ¶
type Client interface {
SnapshotService(snapshotterName string) snapshots.Snapshotter
}
Client interface used by SpecOpt
type Image ¶
type Image interface { // Config descriptor for the image. Config(ctx context.Context) (ocispec.Descriptor, error) // ContentStore provides a content store which contains image blob data ContentStore() content.Store }
Image interface used by some SpecOpt to query image configuration
type Spec ¶ added in v1.2.0
Spec is a type alias to the OCI runtime spec to allow third part SpecOpts to be created without the "issues" with go vendoring and package imports
func GenerateSpec ¶
func GenerateSpec(ctx context.Context, client Client, c *containers.Container, opts ...SpecOpts) (*Spec, error)
GenerateSpec will generate a default spec from the provided image for use as a containerd container
func GenerateSpecWithPlatform ¶ added in v1.2.0
func GenerateSpecWithPlatform(ctx context.Context, client Client, platform string, c *containers.Container, opts ...SpecOpts) (*Spec, error)
GenerateSpecWithPlatform will generate a default spec from the provided image for use as a containerd container in the platform requested.
type SpecOpts ¶
SpecOpts sets spec specific information to a newly generated OCI spec
func Compose ¶ added in v1.1.0
Compose converts a sequence of spec operations into a single operation
func WithAddedCapabilities ¶ added in v1.3.0
WithAddedCapabilities adds the provided capabilities
func WithAdditionalGIDs ¶ added in v1.1.4
WithAdditionalGIDs sets the OCI spec's additionalGids array to any additional groups listed for a particular user in the /etc/group file of the image's root filesystem The passed in user can be either a uid or a username.
func WithAmbientCapabilities ¶ added in v1.2.0
WithAmbientCapabilities set the Linux ambient capabilities for the process Ambient capabilities should only be set for non-root users or the caller should understand how these capabilities are used and set
func WithAnnotations ¶ added in v1.3.0
WithAnnotations appends or replaces the annotations on the spec with the provided annotations
func WithApparmorProfile ¶ added in v1.1.0
WithApparmorProfile sets the Apparmor profile for the process
func WithAppendAdditionalGroups ¶ added in v1.5.18
WithAppendAdditionalGroups append additional groups within the container. The passed in groups can be either a gid or a groupname.
func WithCPUCFS ¶ added in v1.4.0
WithCPUCFS sets the container's Completely fair scheduling (CFS) quota and period
func WithCPUShares ¶ added in v1.4.0
WithCPUShares sets the container's cpu shares
func WithCPUsMems ¶ added in v1.4.0
WithCPUsMems sets the container's cpu mems for use by the container
func WithCapabilities ¶ added in v1.1.0
WithCapabilities sets Linux capabilities on the process
func WithDefaultSpec ¶ added in v1.2.0
func WithDefaultSpec() SpecOpts
WithDefaultSpec returns a SpecOpts that will populate the spec with default values.
Use as the first option to clear the spec, then apply options afterwards.
func WithDefaultSpecForPlatform ¶ added in v1.2.0
WithDefaultSpecForPlatform returns a SpecOpts that will populate the spec with default values for a given platform.
Use as the first option to clear the spec, then apply options afterwards.
func WithDevShmSize ¶ added in v1.3.0
WithDevShmSize sets the size of the /dev/shm mount for the container.
The size value is specified in kb, kilobytes.
func WithDevices ¶ added in v1.5.0
WithDevices recursively adds devices from the passed in path and associated cgroup rules for that device. If devicePath is a dir it traverses the dir to add all devices in that dir. If devicePath is not a dir, it attempts to add the single device. If containerPath is not set then the device path is used for the container path.
func WithDroppedCapabilities ¶ added in v1.3.0
WithDroppedCapabilities removes the provided capabilities
func WithEnvFile ¶ added in v1.3.0
WithEnvFile adds environment variables from a file to the container's spec
func WithHostNamespace ¶
func WithHostNamespace(ns specs.LinuxNamespaceType) SpecOpts
WithHostNamespace allows a task to run inside the host's linux namespace
func WithHostname ¶
WithHostname sets the container's hostname
func WithImageConfig ¶
WithImageConfig configures the spec to from the configuration of an Image
func WithImageConfigArgs ¶ added in v1.2.0
WithImageConfigArgs configures the spec to from the configuration of an Image with additional args that replaces the CMD of the image
func WithLinuxDevice ¶ added in v1.3.0
WithLinuxDevice adds the device specified by path to the spec
func WithLinuxDevices ¶ added in v1.3.0
func WithLinuxDevices(devices []specs.LinuxDevice) SpecOpts
WithLinuxDevices adds the provided linux devices to the spec
func WithLinuxNamespace ¶
func WithLinuxNamespace(ns specs.LinuxNamespace) SpecOpts
WithLinuxNamespace uses the passed in namespace for the spec. If a namespace of the same type already exists in the spec, the existing namespace is replaced by the one provided.
func WithMaskedPaths ¶ added in v1.1.0
WithMaskedPaths sets the masked paths option
func WithMemoryLimit ¶ added in v1.3.0
WithMemoryLimit sets the `Linux.LinuxResources.Memory.Limit` section to the `limit` specified if the `Linux` section is not `nil`. Additionally sets the `Windows.WindowsResources.Memory.Limit` section if the `Windows` section is not `nil`.
func WithMemorySwap ¶ added in v1.4.0
WithMemorySwap sets the container's swap in bytes
func WithMounts ¶ added in v1.1.0
func WithMounts(mounts []specs.Mount) SpecOpts
WithMounts appends mounts
func WithNamespacedCgroup ¶
func WithNamespacedCgroup() SpecOpts
WithNamespacedCgroup uses the namespace set on the context to create a root directory for containers in the cgroup with the id as the subcgroup
func WithPidsLimit ¶ added in v1.4.0
WithPidsLimit sets the container's pid limit or maximum
func WithProcessArgs ¶
WithProcessArgs replaces the args on the generated spec
func WithProcessCwd ¶
WithProcessCwd replaces the current working directory on the generated spec
func WithReadonlyPaths ¶ added in v1.1.0
WithReadonlyPaths sets the read only paths option
func WithRootFSPath ¶
WithRootFSPath specifies unmanaged rootfs path.
func WithRootFSReadonly ¶
func WithRootFSReadonly() SpecOpts
WithRootFSReadonly sets specs.Root.Readonly to true
func WithSelinuxLabel ¶ added in v1.1.0
WithSelinuxLabel sets the process SELinux label
func WithSpecFromBytes ¶ added in v1.2.0
WithSpecFromBytes loads the spec from the provided byte slice.
func WithSpecFromFile ¶ added in v1.2.0
WithSpecFromFile loads the specification from the provided filename.
func WithTTYSize ¶ added in v1.2.0
WithTTYSize sets the information on the spec as well as the environment variables for using a TTY
func WithUIDGID ¶
WithUIDGID allows the UID and GID for the Process to be set
func WithUser ¶ added in v1.1.0
WithUser sets the user to be used within the container. It accepts a valid user string in OCI Image Spec v1.0.0:
user, uid, user:group, uid:gid, uid:group, user:gid
func WithUserID ¶
WithUserID sets the correct UID and GID for the container based on the image's /etc/passwd contents. If /etc/passwd does not exist, or uid is not found in /etc/passwd, it sets the requested uid, additionally sets the gid to 0, and does not return an error.
func WithUserNamespace ¶
func WithUserNamespace(uidMap, gidMap []specs.LinuxIDMapping) SpecOpts
WithUserNamespace sets the uid and gid mappings for the task this can be called multiple times to add more mappings to the generated spec
func WithUsername ¶
WithUsername sets the correct UID and GID for the container based on the image's /etc/passwd contents. If /etc/passwd does not exist, or the username is not found in /etc/passwd, it returns error. On Windows this sets the username as provided, the operating system will validate the user when going to run the container.
func WithoutMounts ¶ added in v1.5.0
WithoutMounts removes mounts