Documentation
¶
Overview ¶
Package run provides configuration options for running containers.
Index ¶
- type Opt
- func ClearLabels() Opt
- func WithAllPortsPublished() Opt
- func WithAutoRemove() Opt
- func WithCapAdd(cap string) Opt
- func WithCapDropAll() Opt
- func WithCgroupnsMode(mode string) Opt
- func WithCombinedOutput(w io.Writer) Opt
- func WithCommand(cmd ...string) Opt
- func WithConsoleSize(width, height uint) Opt
- func WithCustomInit() Opt
- func WithDemuxedOutput(out io.Writer, err io.Writer) Opt
- func WithDevice(dev string) Opt
- func WithEnvVars(vars ...string) Opt
- func WithHostname(host string) Opt
- func WithIPCMode(mode string) Opt
- func WithInput(r io.Reader) Opt
- func WithLabel(label string) Opt
- func WithLabels(labels ...string) Opt
- func WithMount(mnt string) Opt
- func WithName(name string) Opt
- func WithNetwork(net string) Opt
- func WithNetworkMode(mode string) Opt
- func WithPIDMode(mode string) Opt
- func WithPrivileged() Opt
- func WithPublishedPort(mapping string) Opt
- func WithReadOnlyRootfs() Opt
- func WithRestartPolicy(policy string, maxretry int) Opt
- func WithSecurityOpt(opt string) Opt
- func WithStopSignal(s string) Opt
- func WithStopTimeout(secs int) Opt
- func WithTTY() Opt
- func WithTmpfs(path string) Opt
- func WithTmpfsOpts(path string, opts string) Opt
- func WithVolume(vol string) Opt
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Opt ¶
Opt is a configuration option to run a container using github.com/thediveo/morbyd.Session.Run. Please see also Options for more information.
func ClearLabels ¶
func ClearLabels() Opt
ClearLabels clears any labels inherited from the [Session] when creating a new container.
func WithAllPortsPublished ¶
func WithAllPortsPublished() Opt
WithAllPortsPublished instructs Docker to publish all exposed ports on the host. Use with great care.
func WithAutoRemove ¶
func WithAutoRemove() Opt
WithAutoRemove removes the container after it has stopped.
func WithCapAdd ¶
WithCapAdd adds an individual kernel capabilities to the initial process in the container.
func WithCapDropAll ¶
func WithCapDropAll() Opt
WithCapDropAll drops all kernel capabilities for the initial process in the container.
Please note that we don't provide dropping individual capabilities on purpose: the default set of Docker container capabilities depend on the Docker engine and Linux kernel, so this would result in non-deterministic behavior. Drop them all, or drop none.
func WithCgroupnsMode ¶
WithCgroupnsMode configures the cgroup namespace to use when creating the new container; it can be either “” (empty, use the daemon's default) configuration, “private”, or “host”.
func WithCombinedOutput ¶
WithCombinedOutput sends the container's stdout and stderr to the specified io.Writer. This also automatically attaches the container's stdout and stderr after the container has been created.
Please note that you should WithCombinedOutput when using [WithTTYP],as Docker then combines the container's stdout and stderr into a single output stream.
func WithCommand ¶
WithCommand sets the optional command to execute at container start.
func WithConsoleSize ¶
WithConsoleSize sets with width and height of the pseudo TTY; please note the width-height order in contrast to the Docker API order.
func WithCustomInit ¶
func WithCustomInit() Opt
func WithDemuxedOutput ¶
WithDemuxedOutput disables the TTY option in order to send the container's stdout and stderr properly separated to the specified out and err io.Writer.
It is a known limitation of the (pseudo) TTY to combine both stdout and stderr of the container's output streams, and there is no way for Docker (and thus for us) to demultiplex this output sludge after the fact.
func WithDevice ¶
WithDevice specifies a host device to be added to the container to be created. The format is either:
- /dev/foo
- /dev/foo:/dev/bar
- /dev/foo:/dev/bar:rwm
WithDevice will panic if the first (host path) element is empty. If the container path is empty, the same path as in the host is assumed.The cgroup permissions default to “rwm”.
See also: https://docs.docker.com/engine/reference/commandline/container_run/#device
func WithEnvVars ¶
WithEnvVars adds multiple environment variables to the container to be started.
func WithHostname ¶
WithHostname configures the host name to use inside the container.
func WithIPCMode ¶
WithIPCMode configures the IPC namespace to use when creating the new container; it can be either “” (empty, use the daemon's default), “none” (private, but without /dev/shm mounted), “private”, “shareable”, “host”, or container:NAMEID”.
func WithInput ¶
WithInput sends input data from the specified io.Reader to the container's stdin. For this, it allocates a stdin for the container when creating it and then attaches to this stdin after creation.
func WithLabels ¶
WithLabels adds multiple labels in “key=value” format to the container's labels.
func WithMount ¶
WithMount adds a (bind) mount. Please see also Docker's Bind mounts documentation.
func WithNetwork ¶
WithNetwork attaches the new container to a particular network. The nameid parameter either identifies a network by its name or ID, or can be in long format, consisting of comma-separated key-value pairs.
- “bridge”
- “name=bridge,ip=128.0.0.1”
Please do not confuse with WithNetworkMode mode, where the latter configures the Linux kernel net namespace to use.
func WithNetworkMode ¶
WithNetworkMode configures the net(work) namespace to use when creating the new container; it can be either “” (create a new one), “none”, “host”, or container:NAMEID”.
func WithPIDMode ¶
WithPIDMode configures the PID namespace to use when creating the new container; it can be either “” (create a new one), “host”, or container:NAMEID”.
func WithPrivileged ¶
func WithPrivileged() Opt
WithPrivileged runs the container as privileged, including all capabilities and not masking out certain filesystem elements.
func WithPublishedPort ¶ added in v0.11.1
WithPublishedPort exposes a container's port on the host, similar to the “-p” and “--publish” flags in the “docker create” and “docker run” CLI commands. The mapping syntax supported is a superset of Docker's, supporting a random host port while binding to a specific host IP address only:
[HOSTIP:][HOSTPORT:]CONTAINERPORT[/L4PROTO]
An IPv6 HOSTIP needs to be in “[::]” format.
Illustrative examples:
- "1234" publishes the container's TCP port 1234 on a random, available host TCP port, bound to the host's unspecified IP address(es).
- "1234/tcp" is the same as "1234".
- "1234:1234" publishes the container's TCP port 1234 on the host's TCP port 1234, bound to the host's unspecified IP address(es).
- (superset) "127.0.0.1:1234" publishes the container's TCP port 1234 on a random, available host TCP port, bound the the IPv4 loopback address 127.0.0.1.
- (superset) "127.0.0.1:1234/tcp" is the same as "127.0.0.1:1234".
- "127.0.0.1:666:1234" publishes the container's TCP port 1234 on the host's TCP port 666, bound to the IPv4 loopback address 127.0.0.1.
- "[::1]:1234" publishes the container's TCP port 1234 on a random, available host TCP port, bound the the host's IPv6 loopback address ::1.
func WithReadOnlyRootfs ¶
func WithReadOnlyRootfs() Opt
WithReadOnlyRootfs configures the new container to use a ready-only topmost layer.
func WithRestartPolicy ¶
WithRestartPolicy configures the restart policy (“no”, “always”, “on-failure”, “unless-stopped”) as well as the maximum attempts at restarting the container.
func WithSecurityOpt ¶
WithSecurityOpt configures an additional security option, such as “seccomp=unconfined”.
func WithStopSignal ¶
WithStopSignal sets the name of the signal to be sent to its initial process when stopping the container.
func WithStopTimeout ¶
WithStopTimeout sets the timeout (in seconds) to stop the container.
func WithTTY ¶
func WithTTY() Opt
WithTTY allocates a pseudo TTY for the container's input and output.
Please note that using a TTY causes the container's stdout and stderr streams to get mixed together, so this option can be used only in combination with WithCombinedOutput. Specifying it after WithDemuxedOutput will cause the combined stdout+stderr output to appear only on the specified output io.Writer, whereas the specified error io.Writer won't receive any (error) output at all.
When WithTTY is used before WithDemuxedOutput, it'll become ineffective.
func WithTmpfs ¶
WithTmpfs specifies the path inside the container to mount a new tmpfs instance on, using default options (unlimited size, world-writable).
func WithTmpfsOpts ¶
WithTmpfsOpts specifies the path isnide the container to mount a new tmpfs instance, as well as options in form of comma-separated “key=value”.
These options are available:
- tmpfs-size=<bytes>; defaults to unlimited.
- tmpfs-mode=<oct>, where <oct> format can be “700” and “0770”. Defaults to “1777”, that is, “world-writable”.
func WithVolume ¶
WithVolume adds a volume, in the format “source:target:options”. Please see also Docker's Volumes documentation.
- “/var”: an anonymous volume.
Options are comma-separated values:
- “ro” for read-only; if not present, the default is read-write.
- “z” (sharing content among multiple containers) or “Z” (content is private and unshared).
type Options ¶
type Options struct {
Name string
In io.Reader
Out io.Writer
Err io.Writer
Conf container.Config
Host container.HostConfig
Net network.NetworkingConfig
}
Options represent the plethora of options for creating a container from an image, attaching to it, and finally starting it, as well as additional options for handling the input and output of containers.
Please note that the defaults are:
- don't allocate a pseudo TTY (a.k.a “-t” CLI arg); that means that the container gets fifos/pipes assigned to its stdin, stdout, and stderr, but not a pseudo TTY.
- don't allocate stdin; use WithInput to set an io.Reader from which the container gets its stdin data stream fed. Please note that this additionally also sets OpenStdIn and StdinOnce. However, WithInput is not the same as the “-i” CLI arg; “-i” additionally sets AttachStdin, an API option that still is unknown to as what exactly it does during container creation...
Source Files
Directories