2018-02-05 21:05:59 +00:00
|
|
|
package container // import "github.com/docker/docker/api/types/container"
|
2016-09-06 18:18:12 +00:00
|
|
|
|
|
|
|
import (
|
2022-06-15 07:28:20 +00:00
|
|
|
"io"
|
2016-09-06 18:18:12 +00:00
|
|
|
"time"
|
|
|
|
|
|
|
|
"github.com/docker/docker/api/types/strslice"
|
|
|
|
"github.com/docker/go-connections/nat"
|
|
|
|
)
|
|
|
|
|
2017-04-11 01:58:31 +00:00
|
|
|
// MinimumDuration puts a minimum on user configured duration.
|
|
|
|
// This is to prevent API error on time unit. For example, API may
|
|
|
|
// set 3 as healthcheck interval with intention of 3 seconds, but
|
|
|
|
// Docker interprets it as 3 nanoseconds.
|
|
|
|
const MinimumDuration = 1 * time.Millisecond
|
|
|
|
|
2021-08-20 22:23:26 +00:00
|
|
|
// StopOptions holds the options to stop or restart a container.
|
|
|
|
type StopOptions struct {
|
2021-08-22 10:46:43 +00:00
|
|
|
// Signal (optional) is the signal to send to the container to (gracefully)
|
|
|
|
// stop it before forcibly terminating the container with SIGKILL after the
|
|
|
|
// timeout expires. If not value is set, the default (SIGTERM) is used.
|
|
|
|
Signal string `json:",omitempty"`
|
|
|
|
|
2021-08-20 22:23:26 +00:00
|
|
|
// Timeout (optional) is the timeout (in seconds) to wait for the container
|
|
|
|
// to stop gracefully before forcibly terminating it with SIGKILL.
|
|
|
|
//
|
|
|
|
// - Use nil to use the default timeout (10 seconds).
|
|
|
|
// - Use '-1' to wait indefinitely.
|
|
|
|
// - Use '0' to not wait for the container to exit gracefully, and
|
|
|
|
// immediately proceeds to forcibly terminating the container.
|
|
|
|
// - Other positive values are used as timeout (in seconds).
|
|
|
|
Timeout *int `json:",omitempty"`
|
|
|
|
}
|
|
|
|
|
2016-09-06 18:18:12 +00:00
|
|
|
// HealthConfig holds configuration settings for the HEALTHCHECK feature.
|
|
|
|
type HealthConfig struct {
|
|
|
|
// Test is the test to perform to check that the container is healthy.
|
|
|
|
// An empty slice means to inherit the default.
|
|
|
|
// The options are:
|
|
|
|
// {} : inherit healthcheck
|
|
|
|
// {"NONE"} : disable healthcheck
|
|
|
|
// {"CMD", args...} : exec arguments directly
|
|
|
|
// {"CMD-SHELL", command} : run command with system's default shell
|
|
|
|
Test []string `json:",omitempty"`
|
|
|
|
|
|
|
|
// Zero means to inherit. Durations are expressed as integer nanoseconds.
|
2016-11-29 09:58:47 +00:00
|
|
|
Interval time.Duration `json:",omitempty"` // Interval is the time to wait between checks.
|
|
|
|
Timeout time.Duration `json:",omitempty"` // Timeout is the time to wait before considering the check to have hung.
|
|
|
|
StartPeriod time.Duration `json:",omitempty"` // The start period for the container to initialize before the retries starts to count down.
|
2016-09-06 18:18:12 +00:00
|
|
|
|
|
|
|
// Retries is the number of consecutive failures needed to consider a container as unhealthy.
|
|
|
|
// Zero means inherit.
|
|
|
|
Retries int `json:",omitempty"`
|
|
|
|
}
|
|
|
|
|
2022-06-15 07:28:20 +00:00
|
|
|
// ExecStartOptions holds the options to start container's exec.
|
|
|
|
type ExecStartOptions struct {
|
|
|
|
Stdin io.Reader
|
|
|
|
Stdout io.Writer
|
|
|
|
Stderr io.Writer
|
|
|
|
ConsoleSize *[2]uint `json:",omitempty"`
|
|
|
|
}
|
|
|
|
|
2016-09-06 18:18:12 +00:00
|
|
|
// Config contains the configuration data about a container.
|
|
|
|
// It should hold only portable information about the container.
|
|
|
|
// Here, "portable" means "independent from the host we are running on".
|
|
|
|
// Non-portable information *should* appear in HostConfig.
|
|
|
|
// All fields added to this struct must be marked `omitempty` to keep getting
|
|
|
|
// predictable hashes from the old `v1Compatibility` configuration.
|
|
|
|
type Config struct {
|
2016-12-05 15:00:36 +00:00
|
|
|
Hostname string // Hostname
|
|
|
|
Domainname string // Domainname
|
|
|
|
User string // User that will run the command(s) inside the container, also support user:group
|
|
|
|
AttachStdin bool // Attach the standard input, makes possible user interaction
|
|
|
|
AttachStdout bool // Attach the standard output
|
|
|
|
AttachStderr bool // Attach the standard error
|
|
|
|
ExposedPorts nat.PortSet `json:",omitempty"` // List of exposed ports
|
|
|
|
Tty bool // Attach standard streams to a tty, including stdin if it is not closed.
|
|
|
|
OpenStdin bool // Open stdin
|
|
|
|
StdinOnce bool // If true, close stdin after the 1 attached client disconnects.
|
|
|
|
Env []string // List of environment variable to set in the container
|
|
|
|
Cmd strslice.StrSlice // Command to run when starting the container
|
|
|
|
Healthcheck *HealthConfig `json:",omitempty"` // Healthcheck describes how to check the container is healthy
|
Windows: (WCOW) Generate OCI spec that remote runtime can escape
Signed-off-by: John Howard <jhoward@microsoft.com>
Also fixes https://github.com/moby/moby/issues/22874
This commit is a pre-requisite to moving moby/moby on Windows to using
Containerd for its runtime.
The reason for this is that the interface between moby and containerd
for the runtime is an OCI spec which must be unambigious.
It is the responsibility of the runtime (runhcs in the case of
containerd on Windows) to ensure that arguments are escaped prior
to calling into HCS and onwards to the Win32 CreateProcess call.
Previously, the builder was always escaping arguments which has
led to several bugs in moby. Because the local runtime in
libcontainerd had context of whether or not arguments were escaped,
it was possible to hack around in daemon/oci_windows.go with
knowledge of the context of the call (from builder or not).
With a remote runtime, this is not possible as there's rightly
no context of the caller passed across in the OCI spec. Put another
way, as I put above, the OCI spec must be unambigious.
The other previous limitation (which leads to various subtle bugs)
is that moby is coded entirely from a Linux-centric point of view.
Unfortunately, Windows != Linux. Windows CreateProcess uses a
command line, not an array of arguments. And it has very specific
rules about how to escape a command line. Some interesting reading
links about this are:
https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/
https://stackoverflow.com/questions/31838469/how-do-i-convert-argv-to-lpcommandline-parameter-of-createprocess
https://docs.microsoft.com/en-us/cpp/cpp/parsing-cpp-command-line-arguments?view=vs-2017
For this reason, the OCI spec has recently been updated to cater
for more natural syntax by including a CommandLine option in
Process.
What does this commit do?
Primary objective is to ensure that the built OCI spec is unambigious.
It changes the builder so that `ArgsEscaped` as commited in a
layer is only controlled by the use of CMD or ENTRYPOINT.
Subsequently, when calling in to create a container from the builder,
if follows a different path to both `docker run` and `docker create`
using the added `ContainerCreateIgnoreImagesArgsEscaped`. This allows
a RUN from the builder to control how to escape in the OCI spec.
It changes the builder so that when shell form is used for RUN,
CMD or ENTRYPOINT, it builds (for WCOW) a more natural command line
using the original as put by the user in the dockerfile, not
the parsed version as a set of args which loses fidelity.
This command line is put into args[0] and `ArgsEscaped` is set
to true for CMD or ENTRYPOINT. A RUN statement does not commit
`ArgsEscaped` to the commited layer regardless or whether shell
or exec form were used.
2019-01-18 00:03:29 +00:00
|
|
|
ArgsEscaped bool `json:",omitempty"` // True if command is already escaped (meaning treat as a command line) (Windows specific).
|
2016-12-05 15:00:36 +00:00
|
|
|
Image string // Name of the image as it was passed by the operator (e.g. could be symbolic)
|
|
|
|
Volumes map[string]struct{} // List of volumes (mounts) used for the container
|
|
|
|
WorkingDir string // Current directory (PWD) in the command will be launched
|
|
|
|
Entrypoint strslice.StrSlice // Entrypoint to run when starting the container
|
|
|
|
NetworkDisabled bool `json:",omitempty"` // Is network disabled
|
|
|
|
MacAddress string `json:",omitempty"` // Mac Address of the container
|
|
|
|
OnBuild []string // ONBUILD metadata that were defined on the image Dockerfile
|
|
|
|
Labels map[string]string // List of labels set to this container
|
|
|
|
StopSignal string `json:",omitempty"` // Signal to stop a container
|
|
|
|
StopTimeout *int `json:",omitempty"` // Timeout (in seconds) to stop a container
|
|
|
|
Shell strslice.StrSlice `json:",omitempty"` // Shell for shell-form of RUN, CMD, ENTRYPOINT
|
2016-09-06 18:18:12 +00:00
|
|
|
}
|