Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNoGroupsFound = errors.New("no groups found")

    ErrNoGroupsFound can be returned from GIDFromPath

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

      View Source
      var ErrNoUsersFound = errors.New("no users found")

        ErrNoUsersFound can be returned from UserFromPath

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

          View Source
          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 the known linux capabilities for the container process

              WithPrivileged sets up options for a privileged container

              Functions

              func ApplyOpts

              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 GIDFromPath

                func GIDFromPath(root string, filter func(user.Group) bool) (gid uint32, err error)

                  GIDFromPath inspects the GID using /etc/passwd in the specified rootfs. filter can be nil.

                  func HostDevices

                  func HostDevices() ([]specs.LinuxDevice, error)

                    HostDevices returns all devices that can be found under /dev directory.

                    func UserFromPath

                    func UserFromPath(root string, filter func(user.User) bool) (user.User, error)

                      UserFromPath inspects the user object using /etc/passwd in the specified rootfs. filter can be nil.

                      func WithAllDevicesAllowed

                      func WithAllDevicesAllowed(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                        WithAllDevicesAllowed permits READ WRITE MKNOD on all devices nodes for the container

                        func WithDefaultPathEnv

                        func WithDefaultPathEnv(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                          WithDefaultPathEnv sets the $PATH environment variable to the default PATH defined in this package.

                          func WithDefaultUnixDevices

                          func WithDefaultUnixDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                            WithDefaultUnixDevices adds the default devices for unix such as /dev/null, /dev/random to the container's resource cgroup spec

                            func WithHostDevices

                            func WithHostDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                              WithHostDevices adds all the hosts device nodes to the container's spec

                              func WithHostHostsFile

                              func WithHostHostsFile(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                WithHostHostsFile bind-mounts the host's /etc/hosts into the container as readonly

                                func WithHostLocaltime

                                func WithHostLocaltime(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                  WithHostLocaltime bind-mounts the host's /etc/localtime into the container as readonly

                                  func WithHostResolvconf

                                  func WithHostResolvconf(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                    WithHostResolvconf bind-mounts the host's /etc/resolv.conf into the container as readonly

                                    func WithNewPrivileges

                                    func WithNewPrivileges(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                      WithNewPrivileges turns off the NoNewPrivileges feature flag in the spec

                                      func WithNoNewPrivileges

                                      func WithNoNewPrivileges(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                        WithNoNewPrivileges sets no_new_privileges on the process for the container

                                        func WithParentCgroupDevices

                                        func WithParentCgroupDevices(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                          WithParentCgroupDevices uses the default cgroup setup to inherit the container's parent cgroup's allowed and denied devices

                                          func WithSeccompUnconfined

                                          func WithSeccompUnconfined(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                            WithSeccompUnconfined clears the seccomp profile

                                            func WithTTY

                                            func WithTTY(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                              WithTTY sets the information on the spec as well as the environment variables for using a TTY

                                              func WithWindowsHyperV

                                              func WithWindowsHyperV(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                                WithWindowsHyperV sets the Windows.HyperV section for HyperV isolation of containers.

                                                func WithWriteableCgroupfs

                                                func WithWriteableCgroupfs(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                                  WithWriteableCgroupfs makes any cgroup mounts writeable

                                                  func WithWriteableSysfs

                                                  func WithWriteableSysfs(_ context.Context, _ Client, _ *containers.Container, s *Spec) error

                                                    WithWriteableSysfs makes any sysfs mounts writeable

                                                    func WithoutRunMount

                                                    func WithoutRunMount(ctx context.Context, client Client, c *containers.Container, s *Spec) error

                                                      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

                                                          type Spec = specs.Spec

                                                            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

                                                              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

                                                                type SpecOpts func(context.Context, Client, *containers.Container, *Spec) error

                                                                  SpecOpts sets spec specific information to a newly generated OCI spec

                                                                  func Compose

                                                                  func Compose(opts ...SpecOpts) SpecOpts

                                                                    Compose converts a sequence of spec operations into a single operation

                                                                    func WithAddedCapabilities

                                                                    func WithAddedCapabilities(caps []string) SpecOpts

                                                                      WithAddedCapabilities adds the provided capabilities

                                                                      func WithAdditionalGIDs

                                                                      func WithAdditionalGIDs(userstr string) SpecOpts

                                                                        WithAdditionalGIDs sets the OCI spec's additionalGids array to any additional groups listed for a particular user in the /etc/groups file of the image's root filesystem The passed in user can be either a uid or a username.

                                                                        func WithAmbientCapabilities

                                                                        func WithAmbientCapabilities(caps []string) SpecOpts

                                                                          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

                                                                          func WithAnnotations(annotations map[string]string) SpecOpts

                                                                            WithAnnotations appends or replaces the annotations on the spec with the provided annotations

                                                                            func WithApparmorProfile

                                                                            func WithApparmorProfile(profile string) SpecOpts

                                                                              WithApparmorProfile sets the Apparmor profile for the process

                                                                              func WithCPUCFS

                                                                              func WithCPUCFS(quota int64, period uint64) SpecOpts

                                                                                WithCPUCFS sets the container's Completely fair scheduling (CFS) quota and period

                                                                                func WithCPUShares

                                                                                func WithCPUShares(shares uint64) SpecOpts

                                                                                  WithCPUShares sets the container's cpu shares

                                                                                  func WithCPUs

                                                                                  func WithCPUs(cpus string) SpecOpts

                                                                                    WithCPUs sets the container's cpus/cores for use by the container

                                                                                    func WithCPUsMems

                                                                                    func WithCPUsMems(mems string) SpecOpts

                                                                                      WithCPUsMems sets the container's cpu mems for use by the container

                                                                                      func WithCapabilities

                                                                                      func WithCapabilities(caps []string) SpecOpts

                                                                                        WithCapabilities sets Linux capabilities on the process

                                                                                        func WithCgroup

                                                                                        func WithCgroup(path string) SpecOpts

                                                                                          WithCgroup sets the container's cgroup path

                                                                                          func WithDefaultSpec

                                                                                          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

                                                                                            func WithDefaultSpecForPlatform(platform string) SpecOpts

                                                                                              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

                                                                                              func WithDevShmSize(kb int64) SpecOpts

                                                                                                WithDevShmSize sets the size of the /dev/shm mount for the container.

                                                                                                The size value is specified in kb, kilobytes.

                                                                                                func WithDevices

                                                                                                func WithDevices(devicePath, containerPath, permissions string) SpecOpts

                                                                                                  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

                                                                                                  func WithDroppedCapabilities(caps []string) SpecOpts

                                                                                                    WithDroppedCapabilities removes the provided capabilities

                                                                                                    func WithEnv

                                                                                                    func WithEnv(environmentVariables []string) SpecOpts

                                                                                                      WithEnv appends environment variables

                                                                                                      func WithEnvFile

                                                                                                      func WithEnvFile(path string) SpecOpts

                                                                                                        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

                                                                                                          func WithHostname(name string) SpecOpts

                                                                                                            WithHostname sets the container's hostname

                                                                                                            func WithImageConfig

                                                                                                            func WithImageConfig(image Image) SpecOpts

                                                                                                              WithImageConfig configures the spec to from the configuration of an Image

                                                                                                              func WithImageConfigArgs

                                                                                                              func WithImageConfigArgs(image Image, args []string) SpecOpts

                                                                                                                WithImageConfigArgs configures the spec to from the configuration of an Image with additional args that replaces the CMD of the image

                                                                                                                func WithLinuxDevice

                                                                                                                func WithLinuxDevice(path, permissions string) SpecOpts

                                                                                                                  WithLinuxDevice adds the device specified by path to the spec

                                                                                                                  func WithLinuxDevices

                                                                                                                  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

                                                                                                                      func WithMaskedPaths(paths []string) SpecOpts

                                                                                                                        WithMaskedPaths sets the masked paths option

                                                                                                                        func WithMemoryLimit

                                                                                                                        func WithMemoryLimit(limit uint64) SpecOpts

                                                                                                                          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

                                                                                                                          func WithMemorySwap(swap int64) SpecOpts

                                                                                                                            WithMemorySwap sets the container's swap in bytes

                                                                                                                            func WithMounts

                                                                                                                            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

                                                                                                                                func WithPidsLimit(limit int64) SpecOpts

                                                                                                                                  WithPidsLimit sets the container's pid limit or maximum

                                                                                                                                  func WithProcessArgs

                                                                                                                                  func WithProcessArgs(args ...string) SpecOpts

                                                                                                                                    WithProcessArgs replaces the args on the generated spec

                                                                                                                                    func WithProcessCwd

                                                                                                                                    func WithProcessCwd(cwd string) SpecOpts

                                                                                                                                      WithProcessCwd replaces the current working directory on the generated spec

                                                                                                                                      func WithReadonlyPaths

                                                                                                                                      func WithReadonlyPaths(paths []string) SpecOpts

                                                                                                                                        WithReadonlyPaths sets the read only paths option

                                                                                                                                        func WithRootFSPath

                                                                                                                                        func WithRootFSPath(path string) SpecOpts

                                                                                                                                          WithRootFSPath specifies unmanaged rootfs path.

                                                                                                                                          func WithRootFSReadonly

                                                                                                                                          func WithRootFSReadonly() SpecOpts

                                                                                                                                            WithRootFSReadonly sets specs.Root.Readonly to true

                                                                                                                                            func WithSelinuxLabel

                                                                                                                                            func WithSelinuxLabel(label string) SpecOpts

                                                                                                                                              WithSelinuxLabel sets the process SELinux label

                                                                                                                                              func WithSpecFromBytes

                                                                                                                                              func WithSpecFromBytes(p []byte) SpecOpts

                                                                                                                                                WithSpecFromBytes loads the spec from the provided byte slice.

                                                                                                                                                func WithSpecFromFile

                                                                                                                                                func WithSpecFromFile(filename string) SpecOpts

                                                                                                                                                  WithSpecFromFile loads the specification from the provided filename.

                                                                                                                                                  func WithTTYSize

                                                                                                                                                  func WithTTYSize(width, height int) SpecOpts

                                                                                                                                                    WithTTYSize sets the information on the spec as well as the environment variables for using a TTY

                                                                                                                                                    func WithUIDGID

                                                                                                                                                    func WithUIDGID(uid, gid uint32) SpecOpts

                                                                                                                                                      WithUIDGID allows the UID and GID for the Process to be set

                                                                                                                                                      func WithUser

                                                                                                                                                      func WithUser(userstr string) SpecOpts

                                                                                                                                                        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

                                                                                                                                                        func WithUserID(uid uint32) SpecOpts

                                                                                                                                                          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

                                                                                                                                                            func WithUsername(username string) SpecOpts

                                                                                                                                                              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.

                                                                                                                                                              func WithoutMounts

                                                                                                                                                              func WithoutMounts(dests ...string) SpecOpts

                                                                                                                                                                WithoutMounts removes mounts