kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Merge pull request #28938 from elifa/master

Browse source 
Grace period option to health checks.
This commit is contained in:
Sebastiaan van Stijn 2017-04-06 19:23:56 +02:00 committed by GitHub
commit c4010e257f
24 changed files with 404 additions and 287 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
api/swagger.yaml
View file

@ -506,6 +506,9 @@ definitions:
Retries:
description: "The number of consecutive failures needed to consider a container as unhealthy. 0 means inherit."
type: "integer"
StartPeriod:
description: "Start period for the container to initialize before starting health-retries countdown in nanoseconds. 0 means inherit."
type: "integer"
HostConfig:
description: "Container configuration that depends on the host we are running on"

5
api/types/container/config.go
View file

@ -19,8 +19,9 @@ type HealthConfig struct {
Test []string `json:",omitempty"`
// Zero means to inherit. Durations are expressed as integer nanoseconds.
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.
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.
// Retries is the number of consecutive failures needed to consider a container as unhealthy.
// Zero means inherit.

7
builder/dockerfile/dispatchers.go
View file

@ -540,6 +540,7 @@ func healthcheck(b *Builder, args []string, attributes map[string]bool, original
flInterval := b.flags.AddString("interval", "")
flTimeout := b.flags.AddString("timeout", "")
flStartPeriod := b.flags.AddString("start-period", "")
flRetries := b.flags.AddString("retries", "")
if err := b.flags.Parse(); err != nil {
@ -574,6 +575,12 @@ func healthcheck(b *Builder, args []string, attributes map[string]bool, original
}
healthcheck.Timeout = timeout
startPeriod, err := parseOptInterval(flStartPeriod)
if err != nil {
return err
}
healthcheck.StartPeriod = startPeriod
if flRetries.Value != "" {
retries, err := strconv.ParseInt(flRetries.Value, 10, 32)
if err != nil {

16
cli/command/container/opts.go
View file

@ -113,6 +113,7 @@ type containerOptions struct {
healthCmd string
healthInterval time.Duration
healthTimeout time.Duration
healthStartPeriod time.Duration
healthRetries int
runtime string
autoRemove bool
@ -232,6 +233,8 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.DurationVar(&copts.healthInterval, "health-interval", 0, "Time between running the check (ns|us|ms|s|m|h) (default 0s)")
flags.IntVar(&copts.healthRetries, "health-retries", 0, "Consecutive failures needed to report unhealthy")
flags.DurationVar(&copts.healthTimeout, "health-timeout", 0, "Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s)")
flags.DurationVar(&copts.healthStartPeriod, "health-start-period", 0, "Start period for the container to initialize before starting health-retries countdown (ns|us|ms|s|m|h) (default 0s)")
flags.SetAnnotation("health-start-period", "version", []string{"1.29"})
flags.BoolVar(&copts.noHealthcheck, "no-healthcheck", false, "Disable any container-specified HEALTHCHECK")
// Resource management
@ -464,6 +467,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions) (*containerConfig, err
haveHealthSettings := copts.healthCmd != "" ||
copts.healthInterval != 0 ||
copts.healthTimeout != 0 ||
copts.healthStartPeriod != 0 ||
copts.healthRetries != 0
if copts.noHealthcheck {
if haveHealthSettings {
@ -486,12 +490,16 @@ func parse(flags *pflag.FlagSet, copts *containerOptions) (*containerConfig, err
if copts.healthRetries < 0 {
return nil, errors.Errorf("--health-retries cannot be negative")
}
if copts.healthStartPeriod < 0 {
return nil, fmt.Errorf("--health-start-period cannot be negative")
}
healthConfig = &container.HealthConfig{
Test: probe,
Interval: copts.healthInterval,
Timeout: copts.healthTimeout,
Retries: copts.healthRetries,
Test: probe,
Interval: copts.healthInterval,
Timeout: copts.healthTimeout,
StartPeriod: copts.healthStartPeriod,
Retries: copts.healthRetries,
}
}

4
cli/command/container/opts_test.go
View file

@ -501,8 +501,8 @@ func TestParseHealth(t *testing.T) {
checkError("--no-healthcheck conflicts with --health-* options",
"--no-healthcheck", "--health-cmd=/check.sh -q", "img", "cmd")
health = checkOk("--health-timeout=2s", "--health-retries=3", "--health-interval=4.5s", "img", "cmd")
if health.Timeout != 2*time.Second || health.Retries != 3 || health.Interval != 4500*time.Millisecond {
health = checkOk("--health-timeout=2s", "--health-retries=3", "--health-interval=4.5s", "--health-start-period=5s", "img", "cmd")
if health.Timeout != 2*time.Second || health.Retries != 3 || health.Interval != 4500*time.Millisecond || health.StartPeriod != 5*time.Second {
t.Fatalf("--health-*: got %#v", health)
}
}

18
cli/command/service/opts.go
View file

@ -282,6 +282,7 @@ type healthCheckOptions struct {
interval PositiveDurationOpt
timeout PositiveDurationOpt
retries int
startPeriod PositiveDurationOpt
noHealthcheck bool
}
@ -301,18 +302,22 @@ func (opts *healthCheckOptions) toHealthConfig() (*container.HealthConfig, error
if opts.cmd != "" {
test = []string{"CMD-SHELL", opts.cmd}
}
var interval, timeout time.Duration
var interval, timeout, startPeriod time.Duration
if ptr := opts.interval.Value(); ptr != nil {
interval = *ptr
}
if ptr := opts.timeout.Value(); ptr != nil {
timeout = *ptr
}
if ptr := opts.startPeriod.Value(); ptr != nil {
startPeriod = *ptr
}
healthConfig = &container.HealthConfig{
Test: test,
Interval: interval,
Timeout: timeout,
Retries: opts.retries,
Test: test,
Interval: interval,
Timeout: timeout,
Retries: opts.retries,
StartPeriod: startPeriod,
}
}
return healthConfig, nil
@ -555,6 +560,8 @@ func addServiceFlags(flags *pflag.FlagSet, opts *serviceOptions) {
flags.SetAnnotation(flagHealthTimeout, "version", []string{"1.25"})
flags.IntVar(&opts.healthcheck.retries, flagHealthRetries, 0, "Consecutive failures needed to report unhealthy")
flags.SetAnnotation(flagHealthRetries, "version", []string{"1.25"})
flags.Var(&opts.healthcheck.startPeriod, flagHealthStartPeriod, "Start period for the container to initialize before counting retries towards unstable (ns|us|ms|s|m|h)")
flags.SetAnnotation(flagHealthStartPeriod, "version", []string{"1.29"})
flags.BoolVar(&opts.healthcheck.noHealthcheck, flagNoHealthcheck, false, "Disable any container-specified HEALTHCHECK")
flags.SetAnnotation(flagNoHealthcheck, "version", []string{"1.25"})
@ -644,6 +651,7 @@ const (
flagHealthInterval = "health-interval"
flagHealthRetries = "health-retries"
flagHealthTimeout = "health-timeout"
flagHealthStartPeriod = "health-start-period"
flagNoHealthcheck = "no-healthcheck"
flagSecret = "secret"
flagSecretAdd = "secret-add"

18
cli/command/service/opts_test.go
View file

@ -71,18 +71,20 @@ func TestUint64OptSetAndValue(t *testing.T) {
func TestHealthCheckOptionsToHealthConfig(t *testing.T) {
dur := time.Second
opt := healthCheckOptions{
cmd: "curl",
interval: PositiveDurationOpt{DurationOpt{value: &dur}},
timeout: PositiveDurationOpt{DurationOpt{value: &dur}},
retries: 10,
cmd: "curl",
interval: PositiveDurationOpt{DurationOpt{value: &dur}},
timeout: PositiveDurationOpt{DurationOpt{value: &dur}},
startPeriod: PositiveDurationOpt{DurationOpt{value: &dur}},
retries: 10,
}
config, err := opt.toHealthConfig()
assert.NilError(t, err)
assert.Equal(t, reflect.DeepEqual(config, &container.HealthConfig{
Test: []string{"CMD-SHELL", "curl"},
Interval: time.Second,
Timeout: time.Second,
Retries: 10,
Test: []string{"CMD-SHELL", "curl"},
Interval: time.Second,
Timeout: time.Second,
StartPeriod: time.Second,
Retries: 10,
}), true)
}

8
cli/command/service/update.go
View file

@ -898,7 +898,7 @@ func updateLogDriver(flags *pflag.FlagSet, taskTemplate *swarm.TaskSpec) error {
}
func updateHealthcheck(flags *pflag.FlagSet, containerSpec *swarm.ContainerSpec) error {
if !anyChanged(flags, flagNoHealthcheck, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout) {
if !anyChanged(flags, flagNoHealthcheck, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout, flagHealthStartPeriod) {
return nil
}
if containerSpec.Healthcheck == nil {
@ -909,7 +909,7 @@ func updateHealthcheck(flags *pflag.FlagSet, containerSpec *swarm.ContainerSpec)
return err
}
if noHealthcheck {
if !anyChanged(flags, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout) {
if !anyChanged(flags, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout, flagHealthStartPeriod) {
containerSpec.Healthcheck = &container.HealthConfig{
Test: []string{"NONE"},
}
@ -928,6 +928,10 @@ func updateHealthcheck(flags *pflag.FlagSet, containerSpec *swarm.ContainerSpec)
val := *flags.Lookup(flagHealthTimeout).Value.(*PositiveDurationOpt).Value()
containerSpec.Healthcheck.Timeout = val
}
if flags.Changed(flagHealthStartPeriod) {
val := *flags.Lookup(flagHealthStartPeriod).Value.(*PositiveDurationOpt).Value()
containerSpec.Healthcheck.StartPeriod = val
}
if flags.Changed(flagHealthRetries) {
containerSpec.Healthcheck.Retries, _ = flags.GetInt(flagHealthRetries)
}

5
cli/command/service/update_test.go
View file

@ -311,6 +311,11 @@ func TestUpdateHealthcheckTable(t *testing.T) {
initial: &container.HealthConfig{Test: []string{"CMD", "cmd1"}, Retries: 10},
expected: &container.HealthConfig{Test: []string{"CMD", "cmd1"}},
},
{
flags: [][2]string{{"health-start-period", "1m"}},
initial: &container.HealthConfig{Test: []string{"CMD", "cmd1"}},
expected: &container.HealthConfig{Test: []string{"CMD", "cmd1"}, StartPeriod: time.Minute},
},
{
flags: [][2]string{{"health-cmd", "cmd1"}, {"no-healthcheck", "true"}},
err: "--no-healthcheck conflicts with --health-* options",

21
cli/compose/convert/service.go
View file

@ -255,9 +255,9 @@ func convertHealthcheck(healthcheck *composetypes.HealthCheckConfig) (*container
return nil, nil
}
var (
err error
timeout, interval time.Duration
retries int
err error
timeout, interval, startPeriod time.Duration
retries int
)
if healthcheck.Disable {
if len(healthcheck.Test) != 0 {
@ -280,14 +280,21 @@ func convertHealthcheck(healthcheck *composetypes.HealthCheckConfig) (*container
return nil, err
}
}
if healthcheck.StartPeriod != "" {
startPeriod, err = time.ParseDuration(healthcheck.StartPeriod)
if err != nil {
return nil, err
}
}
if healthcheck.Retries != nil {
retries = int(*healthcheck.Retries)
}
return &container.HealthConfig{
Test: healthcheck.Test,
Timeout: timeout,
Interval: interval,
Retries: retries,
Test: healthcheck.Test,
Timeout: timeout,
Interval: interval,
Retries: retries,
StartPeriod: startPeriod,
}, nil
}

11
cli/compose/types/types.go
View file

@ -163,11 +163,12 @@ type DeployConfig struct {
// HealthCheckConfig the healthcheck configuration for a service
type HealthCheckConfig struct {
Test HealthCheckTest
Timeout string
Interval string
Retries *uint64
Disable bool
Test HealthCheckTest
Timeout string
Interval string
Retries *uint64
StartPeriod string
Disable bool
}
// HealthCheckTest is the command run to test the health of a service

19
daemon/cluster/convert/container.go
View file

@ -221,19 +221,22 @@ func containerToGRPC(c types.ContainerSpec) (*swarmapi.ContainerSpec, error) {
func healthConfigFromGRPC(h *swarmapi.HealthConfig) *container.HealthConfig {
interval, _ := gogotypes.DurationFromProto(h.Interval)
timeout, _ := gogotypes.DurationFromProto(h.Timeout)
startPeriod, _ := gogotypes.DurationFromProto(h.Timeout)
return &container.HealthConfig{
Test: h.Test,
Interval: interval,
Timeout: timeout,
Retries: int(h.Retries),
Test: h.Test,
Interval: interval,
Timeout: timeout,
Retries: int(h.Retries),
StartPeriod: startPeriod,
}
}
func healthConfigToGRPC(h *container.HealthConfig) *swarmapi.HealthConfig {
return &swarmapi.HealthConfig{
Test: h.Test,
Interval: gogotypes.DurationProto(h.Interval),
Timeout: gogotypes.DurationProto(h.Timeout),
Retries: int32(h.Retries),
Test: h.Test,
Interval: gogotypes.DurationProto(h.Interval),
Timeout: gogotypes.DurationProto(h.Timeout),
Retries: int32(h.Retries),
StartPeriod: gogotypes.DurationProto(h.StartPeriod),
}
}

10
daemon/cluster/executor/container/container.go
View file

@ -326,11 +326,13 @@ func (c *containerConfig) healthcheck() *enginecontainer.HealthConfig {
}
interval, _ := gogotypes.DurationFromProto(hcSpec.Interval)
timeout, _ := gogotypes.DurationFromProto(hcSpec.Timeout)
startPeriod, _ := gogotypes.DurationFromProto(hcSpec.StartPeriod)
return &enginecontainer.HealthConfig{
Test: hcSpec.Test,
Interval: interval,
Timeout: timeout,
Retries: int(hcSpec.Retries),
Test: hcSpec.Test,
Interval: interval,
Timeout: timeout,
Retries: int(hcSpec.Retries),
StartPeriod: startPeriod,
}
}

3
daemon/commit.go
View file

@ -94,6 +94,9 @@ func merge(userConf, imageConf *containertypes.Config) error {
if userConf.Healthcheck.Timeout == 0 {
userConf.Healthcheck.Timeout = imageConf.Healthcheck.Timeout
}
if userConf.Healthcheck.StartPeriod == 0 {
userConf.Healthcheck.StartPeriod = imageConf.Healthcheck.StartPeriod
}
if userConf.Healthcheck.Retries == 0 {
userConf.Healthcheck.Retries = imageConf.Healthcheck.Retries
}

4
daemon/container.go
View file

@ -255,6 +255,10 @@ func (daemon *Daemon) verifyContainerSettings(hostConfig *containertypes.HostCon
if config.Healthcheck.Retries < 0 {
return nil, fmt.Errorf("Retries in Healthcheck cannot be negative")
}
if config.Healthcheck.StartPeriod < 0 {
return nil, fmt.Errorf("StartPeriod in Healthcheck cannot be negative")
}
}
}

31
daemon/health.go
View file

@ -30,6 +30,10 @@ const (
// than this, the check is considered to have failed.
defaultProbeTimeout = 30 * time.Second
// The time given for the container to start before the health check starts considering
// the container unstable. Defaults to none.
defaultStartPeriod = 0 * time.Second
// Default number of consecutive failures of the health check
// for the container to be considered unhealthy.
defaultProbeRetries = 3
@ -133,11 +137,28 @@ func handleProbeResult(d *Daemon, c *container.Container, result *types.Healthch
if result.ExitCode == exitStatusHealthy {
h.FailingStreak = 0
h.Status = types.Healthy
} else {
// Failure (including invalid exit code)
h.FailingStreak++
if h.FailingStreak >= retries {
h.Status = types.Unhealthy
} else { // Failure (including invalid exit code)
shouldIncrementStreak := true
// If the container is starting (i.e. we never had a successful health check)
// then we check if we are within the start period of the container in which
// case we do not increment the failure streak.
if h.Status == types.Starting {
startPeriod := timeoutWithDefault(c.Config.Healthcheck.StartPeriod, defaultStartPeriod)
timeSinceStart := result.Start.Sub(c.State.StartedAt)
// If still within the start period, then don't increment failing streak.
if timeSinceStart < startPeriod {
shouldIncrementStreak = false
}
}
if shouldIncrementStreak {
h.FailingStreak++
if h.FailingStreak >= retries {
h.Status = types.Unhealthy
}
}
// Else we're starting or healthy. Stay in that state.
}

26
daemon/health_test.go
View file

@ -116,4 +116,30 @@ func TestHealthStates(t *testing.T) {
if c.State.Health.FailingStreak != 0 {
t.Errorf("Expecting FailingStreak=0, but got %d\n", c.State.Health.FailingStreak)
}
// Test start period
reset(c)
c.Config.Healthcheck.Retries = 2
c.Config.Healthcheck.StartPeriod = 30 * time.Second
handleResult(c.State.StartedAt.Add(20*time.Second), 1)
if c.State.Health.Status != types.Starting {
t.Errorf("Expecting starting, but got %#v\n", c.State.Health.Status)
}
if c.State.Health.FailingStreak != 0 {
t.Errorf("Expecting FailingStreak=0, but got %d\n", c.State.Health.FailingStreak)
}
handleResult(c.State.StartedAt.Add(50*time.Second), 1)
if c.State.Health.Status != types.Starting {
t.Errorf("Expecting starting, but got %#v\n", c.State.Health.Status)
}
if c.State.Health.FailingStreak != 1 {
t.Errorf("Expecting FailingStreak=1, but got %d\n", c.State.Health.FailingStreak)
}
handleResult(c.State.StartedAt.Add(80*time.Second), 0)
expect("health_status: healthy")
if c.State.Health.FailingStreak != 0 {
t.Errorf("Expecting FailingStreak=0, but got %d\n", c.State.Health.FailingStreak)
}
}

1
docs/api/version-history.md
View file

@ -22,6 +22,7 @@ keywords: "API, Docker, rcli, REST, documentation"
* `POST /networks/create` now supports creating the ingress network, by specifying an `Ingress` boolean field. As of now this is supported only when using the overlay network driver.
* `GET /networks/(name)` now returns an `Ingress` field showing whether the network is the ingress one.
* `GET /networks/` now supports a `scope` filter to filter networks based on the network mode (`swarm`, `global`, or `local`).
* `POST /containers/create`, `POST /service/create` and `POST /services/(id or name)/update` now takes the field `StartPeriod` as a part of the `HealthConfig` allowing for specification of a period during which the container should not be considered unealthy even if health checks do not pass.
## v1.28 API changes

6
docs/reference/builder.md
View file

@ -1591,6 +1591,7 @@ The options that can appear before `CMD` are:
* `--interval=DURATION` (default: `30s`)
* `--timeout=DURATION` (default: `30s`)
* `--start-period=DURATION` (default: `0s`)
* `--retries=N` (default: `3`)
The health check will first run **interval** seconds after the container is
@ -1602,6 +1603,11 @@ is considered to have failed.
It takes **retries** consecutive failures of the health check for the container
to be considered `unhealthy`.
**start period** provides initialization time for containers that need time to bootstrap.
Probe failure during that period will not be counted towards the maximum number of retries.
However, if a health check succeeds during the start period, the container is considered
started and all consecutive failures will be counted towards the maximum number of retries.
There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list
more than one then only the last `HEALTHCHECK` will take effect.

223
docs/reference/commandline/create.md
View file

@ -23,117 +23,118 @@ Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...]
Create a new container
Options:
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
-a, --attach value Attach to STDIN, STDOUT or STDERR (default [])
--blkio-weight value Block IO (relative weight), between 10 and 1000
--blkio-weight-device value Block IO weight (relative device weight) (default [])
--cap-add value Add Linux capabilities (default [])
--cap-drop value Drop Linux capabilities (default [])
--cgroup-parent string Optional parent cgroup for the container
--cidfile string Write the container ID to the file
--cpu-count int The number of CPUs available for execution by the container.
Windows daemon only. On Windows Server containers, this is
approximated as a percentage of total CPU usage.
--cpu-percent int CPU percent (Windows only)
--cpu-period int Limit CPU CFS (Completely Fair Scheduler) period
--cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota
-c, --cpu-shares int CPU shares (relative weight)
--cpus NanoCPUs Number of CPUs (default 0.000)
--cpu-rt-period int Limit the CPU real-time period in microseconds
--cpu-rt-runtime int Limit the CPU real-time runtime in microseconds
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
--device value Add a host device to the container (default [])
--device-cgroup-rule value Add a rule to the cgroup allowed devices list
--device-read-bps value Limit read rate (bytes per second) from a device (default [])
--device-read-iops value Limit read rate (IO per second) from a device (default [])
--device-write-bps value Limit write rate (bytes per second) to a device (default [])
--device-write-iops value Limit write rate (IO per second) to a device (default [])
--disable-content-trust Skip image verification (default true)
--dns value Set custom DNS servers (default [])
--dns-option value Set DNS options (default [])
--dns-search value Set custom DNS search domains (default [])
--entrypoint string Overwrite the default ENTRYPOINT of the image
-e, --env value Set environment variables (default [])
--env-file value Read in a file of environment variables (default [])
--expose value Expose a port or a range of ports (default [])
--group-add value Add additional groups to join (default [])
--health-cmd string Command to run to check health
--health-interval duration Time between running the check (ns|us|ms|s|m|h) (default 0s)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s)
--help Print usage
-h, --hostname string Container host name
--init Run an init inside the container that forwards signals and reaps processes
--init-path string Path to the docker-init binary
-i, --interactive Keep STDIN open even if not attached
--io-maxbandwidth string Maximum IO bandwidth limit for the system drive (Windows only)
--io-maxiops uint Maximum IOps limit for the system drive (Windows only)
--ip string IPv4 address (e.g., 172.30.100.104)
--ip6 string IPv6 address (e.g., 2001:db8::33)
--ipc string IPC namespace to use
--isolation string Container isolation technology
--kernel-memory string Kernel memory limit
-l, --label value Set meta data on a container (default [])
--label-file value Read in a line delimited file of labels (default [])
--link value Add link to another container (default [])
--link-local-ip value Container IPv4/IPv6 link-local addresses (default [])
--log-driver string Logging driver for the container
--log-opt value Log driver options (default [])
--mac-address string Container MAC address (e.g., 92:d0:c6:0a:29:33)
-m, --memory string Memory limit
--memory-reservation string Memory soft limit
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
--memory-swappiness int Tune container memory swappiness (0 to 100) (default -1)
--mount value Attach a filesytem mount to the container (default [])
--name string Assign a name to the container
--network-alias value Add network-scoped alias for the container (default [])
--network string Connect a container to a network (default "default")
'bridge': create a network stack on the default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
--no-healthcheck Disable any container-specified HEALTHCHECK
--oom-kill-disable Disable OOM Killer
--oom-score-adj int Tune host's OOM preferences (-1000 to 1000)
--pid string PID namespace to use
--pids-limit int Tune container pids limit (set -1 for unlimited), kernel >= 4.3
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are: no, on-failure[:max-retry], always, unless-stopped
--rm Automatically remove the container when it exits
--runtime string Runtime to use for this container
--security-opt value Security Options (default [])
--shm-size bytes Size of /dev/shm
The format is `<number><unit>`. `number` must be greater than `0`.
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
or `g` (gigabytes). If you omit the unit, the system uses bytes.
--stop-signal string Signal to stop a container (default "SIGTERM")
--stop-timeout=10 Timeout (in seconds) to stop a container
--storage-opt value Storage driver options for the container (default [])
--sysctl value Sysctl options (default map[])
--tmpfs value Mount a tmpfs directory (default [])
-t, --tty Allocate a pseudo-TTY
--ulimit value Ulimit options (default [])
-u, --user string Username or UID (format: <name|uid>[:<group|gid>])
--userns string User namespace to use
'host': Use the Docker host user namespace
'': Use the Docker daemon user namespace specified by `--userns-remap` option.
--uts string UTS namespace to use
-v, --volume value Bind mount a volume (default []). The format
is `[host-src:]container-dest[:<options>]`.
The comma-delimited `options` are [rw|ro],
[z|Z], [[r]shared|[r]slave|[r]private],
[delegated|cached|consistent], and
[nocopy]. The 'host-src' is an absolute path
or a name value.
--volume-driver string Optional volume driver for the container
--volumes-from value Mount volumes from the specified container(s) (default [])
-w, --workdir string Working directory inside the container
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
-a, --attach value Attach to STDIN, STDOUT or STDERR (default [])
--blkio-weight value Block IO (relative weight), between 10 and 1000
--blkio-weight-device value Block IO weight (relative device weight) (default [])
--cap-add value Add Linux capabilities (default [])
--cap-drop value Drop Linux capabilities (default [])
--cgroup-parent string Optional parent cgroup for the container
--cidfile string Write the container ID to the file
--cpu-count int The number of CPUs available for execution by the container.
Windows daemon only. On Windows Server containers, this is
approximated as a percentage of total CPU usage.
--cpu-percent int CPU percent (Windows only)
--cpu-period int Limit CPU CFS (Completely Fair Scheduler) period
--cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota
-c, --cpu-shares int CPU shares (relative weight)
--cpus NanoCPUs Number of CPUs (default 0.000)
--cpu-rt-period int Limit the CPU real-time period in microseconds
--cpu-rt-runtime int Limit the CPU real-time runtime in microseconds
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
--device value Add a host device to the container (default [])
--device-cgroup-rule value Add a rule to the cgroup allowed devices list
--device-read-bps value Limit read rate (bytes per second) from a device (default [])
--device-read-iops value Limit read rate (IO per second) from a device (default [])
--device-write-bps value Limit write rate (bytes per second) to a device (default [])
--device-write-iops value Limit write rate (IO per second) to a device (default [])
--disable-content-trust Skip image verification (default true)
--dns value Set custom DNS servers (default [])
--dns-option value Set DNS options (default [])
--dns-search value Set custom DNS search domains (default [])
--entrypoint string Overwrite the default ENTRYPOINT of the image
-e, --env value Set environment variables (default [])
--env-file value Read in a file of environment variables (default [])
--expose value Expose a port or a range of ports (default [])
--group-add value Add additional groups to join (default [])
--health-cmd string Command to run to check health
--health-interval duration Time between running the check (ns|us|ms|s|m|h) (default 0s)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s)
--health-start-period duration Start period for the container to initialize before counting retries towards unstable (ns|us|ms|s|m|h) (default 0s)
--help Print usage
-h, --hostname string Container host name
--init Run an init inside the container that forwards signals and reaps processes
--init-path string Path to the docker-init binary
-i, --interactive Keep STDIN open even if not attached
--io-maxbandwidth string Maximum IO bandwidth limit for the system drive (Windows only)
--io-maxiops uint Maximum IOps limit for the system drive (Windows only)
--ip string IPv4 address (e.g., 172.30.100.104)
--ip6 string IPv6 address (e.g., 2001:db8::33)
--ipc string IPC namespace to use
--isolation string Container isolation technology
--kernel-memory string Kernel memory limit
-l, --label value Set meta data on a container (default [])
--label-file value Read in a line delimited file of labels (default [])
--link value Add link to another container (default [])
--link-local-ip value Container IPv4/IPv6 link-local addresses (default [])
--log-driver string Logging driver for the container
--log-opt value Log driver options (default [])
--mac-address string Container MAC address (e.g., 92:d0:c6:0a:29:33)
-m, --memory string Memory limit
--memory-reservation string Memory soft limit
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
--memory-swappiness int Tune container memory swappiness (0 to 100) (default -1)
--mount value Attach a filesytem mount to the container (default [])
--name string Assign a name to the container
--network-alias value Add network-scoped alias for the container (default [])
--network string Connect a container to a network (default "default")
'bridge': create a network stack on the default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
--no-healthcheck Disable any container-specified HEALTHCHECK
--oom-kill-disable Disable OOM Killer
--oom-score-adj int Tune host's OOM preferences (-1000 to 1000)
--pid string PID namespace to use
--pids-limit int Tune container pids limit (set -1 for unlimited), kernel >= 4.3
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are: no, on-failure[:max-retry], always, unless-stopped
--rm Automatically remove the container when it exits
--runtime string Runtime to use for this container
--security-opt value Security Options (default [])
--shm-size bytes Size of /dev/shm
The format is `<number><unit>`. `number` must be greater than `0`.
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
or `g` (gigabytes). If you omit the unit, the system uses bytes.
--stop-signal string Signal to stop a container (default "SIGTERM")
--stop-timeout=10 Timeout (in seconds) to stop a container
--storage-opt value Storage driver options for the container (default [])
--sysctl value Sysctl options (default map[])
--tmpfs value Mount a tmpfs directory (default [])
-t, --tty Allocate a pseudo-TTY
--ulimit value Ulimit options (default [])
-u, --user string Username or UID (format: <name|uid>[:<group|gid>])
--userns string User namespace to use
'host': Use the Docker host user namespace
'': Use the Docker daemon user namespace specified by `--userns-remap` option.
--uts string UTS namespace to use
-v, --volume value Bind mount a volume (default []). The format
is `[host-src:]container-dest[:<options>]`.
The comma-delimited `options` are [rw|ro],
[z|Z], [[r]shared|[r]slave|[r]private],
[delegated|cached|consistent], and
[nocopy]. The 'host-src' is an absolute path
or a name value.
--volume-driver string Optional volume driver for the container
--volumes-from value Mount volumes from the specified container(s) (default [])
-w, --workdir string Working directory inside the container
```
## Description

249
docs/reference/commandline/run.md
View file

@ -21,130 +21,131 @@ Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
Run a command in a new container
Options:
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
-a, --attach value Attach to STDIN, STDOUT or STDERR (default [])
--blkio-weight value Block IO (relative weight), between 10 and 1000
--blkio-weight-device value Block IO weight (relative device weight) (default [])
--cap-add value Add Linux capabilities (default [])
--cap-drop value Drop Linux capabilities (default [])
--cgroup-parent string Optional parent cgroup for the container
--cidfile string Write the container ID to the file
--cpu-count int The number of CPUs available for execution by the container.
Windows daemon only. On Windows Server containers, this is
approximated as a percentage of total CPU usage.
--cpu-percent int Limit percentage of CPU available for execution
by the container. Windows daemon only.
The processor resource controls are mutually
exclusive, the order of precedence is CPUCount
first, then CPUShares, and CPUPercent last.
--cpu-period int Limit CPU CFS (Completely Fair Scheduler) period
--cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota
-c, --cpu-shares int CPU shares (relative weight)
--cpus NanoCPUs Number of CPUs (default 0.000)
--cpu-rt-period int Limit the CPU real-time period in microseconds
--cpu-rt-runtime int Limit the CPU real-time runtime in microseconds
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
-d, --detach Run container in background and print container ID
--detach-keys string Override the key sequence for detaching a container
--device value Add a host device to the container (default [])
--device-cgroup-rule value Add a rule to the cgroup allowed devices list
--device-read-bps value Limit read rate (bytes per second) from a device (default [])
--device-read-iops value Limit read rate (IO per second) from a device (default [])
--device-write-bps value Limit write rate (bytes per second) to a device (default [])
--device-write-iops value Limit write rate (IO per second) to a device (default [])
--disable-content-trust Skip image verification (default true)
--dns value Set custom DNS servers (default [])
--dns-option value Set DNS options (default [])
--dns-search value Set custom DNS search domains (default [])
--entrypoint string Overwrite the default ENTRYPOINT of the image
-e, --env value Set environment variables (default [])
--env-file value Read in a file of environment variables (default [])
--expose value Expose a port or a range of ports (default [])
--group-add value Add additional groups to join (default [])
--health-cmd string Command to run to check health
--health-interval duration Time between running the check (ns|us|ms|s|m|h) (default 0s)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s)
--help Print usage
-h, --hostname string Container host name
--init Run an init inside the container that forwards signals and reaps processes
--init-path string Path to the docker-init binary
-i, --interactive Keep STDIN open even if not attached
--io-maxbandwidth string Maximum IO bandwidth limit for the system drive (Windows only)
(Windows only). The format is `<number><unit>`.
Unit is optional and can be `b` (bytes per second),
`k` (kilobytes per second), `m` (megabytes per second),
or `g` (gigabytes per second). If you omit the unit,
the system uses bytes per second.
--io-maxbandwidth and --io-maxiops are mutually exclusive options.
--io-maxiops uint Maximum IOps limit for the system drive (Windows only)
--ip string IPv4 address (e.g., 172.30.100.104)
--ip6 string IPv6 address (e.g., 2001:db8::33)
--ipc string IPC namespace to use
--isolation string Container isolation technology
--kernel-memory string Kernel memory limit
-l, --label value Set meta data on a container (default [])
--label-file value Read in a line delimited file of labels (default [])
--link value Add link to another container (default [])
--link-local-ip value Container IPv4/IPv6 link-local addresses (default [])
--log-driver string Logging driver for the container
--log-opt value Log driver options (default [])
--mac-address string Container MAC address (e.g., 92:d0:c6:0a:29:33)
-m, --memory string Memory limit
--memory-reservation string Memory soft limit
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
--memory-swappiness int Tune container memory swappiness (0 to 100) (default -1)
--mount value Attach a filesystem mount to the container (default [])
--name string Assign a name to the container
--network-alias value Add network-scoped alias for the container (default [])
--network string Connect a container to a network
'bridge': create a network stack on the default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
--no-healthcheck Disable any container-specified HEALTHCHECK
--oom-kill-disable Disable OOM Killer
--oom-score-adj int Tune host's OOM preferences (-1000 to 1000)
--pid string PID namespace to use
--pids-limit int Tune container pids limit (set -1 for unlimited)
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are : no, on-failure[:max-retry], always, unless-stopped
--rm Automatically remove the container when it exits
--runtime string Runtime to use for this container
--security-opt value Security Options (default [])
--shm-size bytes Size of /dev/shm
The format is `<number><unit>`. `number` must be greater than `0`.
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
or `g` (gigabytes). If you omit the unit, the system uses bytes.
--sig-proxy Proxy received signals to the process (default true)
--stop-signal string Signal to stop a container (default "SIGTERM")
--stop-timeout=10 Timeout (in seconds) to stop a container
--storage-opt value Storage driver options for the container (default [])
--sysctl value Sysctl options (default map[])
--tmpfs value Mount a tmpfs directory (default [])
-t, --tty Allocate a pseudo-TTY
--ulimit value Ulimit options (default [])
-u, --user string Username or UID (format: <name|uid>[:<group|gid>])
--userns string User namespace to use
'host': Use the Docker host user namespace
'': Use the Docker daemon user namespace specified by `--userns-remap` option.
--uts string UTS namespace to use
-v, --volume value Bind mount a volume (default []). The format
is `[host-src:]container-dest[:<options>]`.
The comma-delimited `options` are [rw|ro],
[z|Z], [[r]shared|[r]slave|[r]private],
[delegated|cached|consistent], and
[nocopy]. The 'host-src' is an absolute path
or a name value.
--volume-driver string Optional volume driver for the container
--volumes-from value Mount volumes from the specified container(s) (default [])
-w, --workdir string Working directory inside the container
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
-a, --attach value Attach to STDIN, STDOUT or STDERR (default [])
--blkio-weight value Block IO (relative weight), between 10 and 1000
--blkio-weight-device value Block IO weight (relative device weight) (default [])
--cap-add value Add Linux capabilities (default [])
--cap-drop value Drop Linux capabilities (default [])
--cgroup-parent string Optional parent cgroup for the container
--cidfile string Write the container ID to the file
--cpu-count int The number of CPUs available for execution by the container.
Windows daemon only. On Windows Server containers, this is
approximated as a percentage of total CPU usage.
--cpu-percent int Limit percentage of CPU available for execution
by the container. Windows daemon only.
The processor resource controls are mutually
exclusive, the order of precedence is CPUCount
first, then CPUShares, and CPUPercent last.
--cpu-period int Limit CPU CFS (Completely Fair Scheduler) period
--cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota
-c, --cpu-shares int CPU shares (relative weight)
--cpus NanoCPUs Number of CPUs (default 0.000)
--cpu-rt-period int Limit the CPU real-time period in microseconds
--cpu-rt-runtime int Limit the CPU real-time runtime in microseconds
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
-d, --detach Run container in background and print container ID
--detach-keys string Override the key sequence for detaching a container
--device value Add a host device to the container (default [])
--device-cgroup-rule value Add a rule to the cgroup allowed devices list
--device-read-bps value Limit read rate (bytes per second) from a device (default [])
--device-read-iops value Limit read rate (IO per second) from a device (default [])
--device-write-bps value Limit write rate (bytes per second) to a device (default [])
--device-write-iops value Limit write rate (IO per second) to a device (default [])
--disable-content-trust Skip image verification (default true)
--dns value Set custom DNS servers (default [])
--dns-option value Set DNS options (default [])
--dns-search value Set custom DNS search domains (default [])
--entrypoint string Overwrite the default ENTRYPOINT of the image
-e, --env value Set environment variables (default [])
--env-file value Read in a file of environment variables (default [])
--expose value Expose a port or a range of ports (default [])
--group-add value Add additional groups to join (default [])
--health-cmd string Command to run to check health
--health-interval duration Time between running the check (ns|us|ms|s|m|h) (default 0s)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s)
--health-start-period duration Start period for the container to initialize before counting retries towards unstable (ns|us|ms|s|m|h) (default 0s)
--help Print usage
-h, --hostname string Container host name
--init Run an init inside the container that forwards signals and reaps processes
--init-path string Path to the docker-init binary
-i, --interactive Keep STDIN open even if not attached
--io-maxbandwidth string Maximum IO bandwidth limit for the system drive (Windows only)
(Windows only). The format is `<number><unit>`.
Unit is optional and can be `b` (bytes per second),
`k` (kilobytes per second), `m` (megabytes per second),
or `g` (gigabytes per second). If you omit the unit,
the system uses bytes per second.
--io-maxbandwidth and --io-maxiops are mutually exclusive options.
--io-maxiops uint Maximum IOps limit for the system drive (Windows only)
--ip string IPv4 address (e.g., 172.30.100.104)
--ip6 string IPv6 address (e.g., 2001:db8::33)
--ipc string IPC namespace to use
--isolation string Container isolation technology
--kernel-memory string Kernel memory limit
-l, --label value Set meta data on a container (default [])
--label-file value Read in a line delimited file of labels (default [])
--link value Add link to another container (default [])
--link-local-ip value Container IPv4/IPv6 link-local addresses (default [])
--log-driver string Logging driver for the container
--log-opt value Log driver options (default [])
--mac-address string Container MAC address (e.g., 92:d0:c6:0a:29:33)
-m, --memory string Memory limit
--memory-reservation string Memory soft limit
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
--memory-swappiness int Tune container memory swappiness (0 to 100) (default -1)
--mount value Attach a filesystem mount to the container (default [])
--name string Assign a name to the container
--network-alias value Add network-scoped alias for the container (default [])
--network string Connect a container to a network
'bridge': create a network stack on the default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
--no-healthcheck Disable any container-specified HEALTHCHECK
--oom-kill-disable Disable OOM Killer
--oom-score-adj int Tune host's OOM preferences (-1000 to 1000)
--pid string PID namespace to use
--pids-limit int Tune container pids limit (set -1 for unlimited)
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are : no, on-failure[:max-retry], always, unless-stopped
--rm Automatically remove the container when it exits
--runtime string Runtime to use for this container
--security-opt value Security Options (default [])
--shm-size bytes Size of /dev/shm
The format is `<number><unit>`. `number` must be greater than `0`.
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
or `g` (gigabytes). If you omit the unit, the system uses bytes.
--sig-proxy Proxy received signals to the process (default true)
--stop-signal string Signal to stop a container (default "SIGTERM")
--stop-timeout=10 Timeout (in seconds) to stop a container
--storage-opt value Storage driver options for the container (default [])
--sysctl value Sysctl options (default map[])
--tmpfs value Mount a tmpfs directory (default [])
-t, --tty Allocate a pseudo-TTY
--ulimit value Ulimit options (default [])
-u, --user string Username or UID (format: <name|uid>[:<group|gid>])
--userns string User namespace to use
'host': Use the Docker host user namespace
'': Use the Docker daemon user namespace specified by `--userns-remap` option.
--uts string UTS namespace to use
-v, --volume value Bind mount a volume (default []). The format
is `[host-src:]container-dest[:<options>]`.
The comma-delimited `options` are [rw|ro],
[z|Z], [[r]shared|[r]slave|[r]private],
[delegated|cached|consistent], and
[nocopy]. The 'host-src' is an absolute path
or a name value.
--volume-driver string Optional volume driver for the container
--volumes-from value Mount volumes from the specified container(s) (default [])
-w, --workdir string Working directory inside the container
```
## Description

1
docs/reference/commandline/service_create.md
View file

@ -36,6 +36,7 @@ Options:
--health-interval duration Time between running the check (ns|us|ms|s|m|h)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h)
--health-start-period duration Start period for the container to initialize before counting retries towards unstable (ns|us|ms|s|m|h) (default 0s)
--help Print usage
--host list Set one or more custom host-to-IP mappings (host:ip) (default [])
--hostname string Container hostname

1
docs/reference/commandline/service_update.md
View file

@ -44,6 +44,7 @@ Options:
--health-interval duration Time between running the check (ns|us|ms|s|m|h)
--health-retries int Consecutive failures needed to report unhealthy
--health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h)
--health-start-period duration Start period for the container to initialize before counting retries towards unstable (ns|us|ms|s|m|h) (default 0s)
--help Print usage
--host-add list Add or update a custom host-to-IP mapping (host:ip) (default [])
--host-rm list Remove a custom host-to-IP mapping (host:ip) (default [])

1
docs/reference/run.md
View file

@ -1462,6 +1462,7 @@ Similarly the operator can set the **HOSTNAME** (Linux) or **COMPUTERNAME** (Win
--health-interval Time between running the check
--health-retries Consecutive failures needed to report unhealthy
--health-timeout Maximum time to allow one check to run
--health-start-period Start period for the container to initialize before starting health-retries countdown
--no-healthcheck Disable any container-specified HEALTHCHECK
```