diff --git a/api/swagger.yaml b/api/swagger.yaml
index 29c9941efb..51d7f24068 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -2265,6 +2265,32 @@ definitions:
description: "The fraction of tasks that may fail during an update before the failure action is invoked, specified as a floating point number between 0 and 1."
type: "number"
default: 0
+ RollbackConfig:
+ description: "Specification for the rollback strategy of the service."
+ type: "object"
+ properties:
+ Parallelism:
+ description: "Maximum number of tasks to be rolled back in one iteration (0 means unlimited parallelism)."
+ type: "integer"
+ format: "int64"
+ Delay:
+ description: "Amount of time between rollback iterations, in nanoseconds."
+ type: "integer"
+ format: "int64"
+ FailureAction:
+ description: "Action to take if an rolled back task fails to run, or stops running during the rollback."
+ type: "string"
+ enum:
+ - "continue"
+ - "pause"
+ Monitor:
+ description: "Amount of time to monitor each rolled back task for failures, in nanoseconds."
+ type: "integer"
+ format: "int64"
+ MaxFailureRatio:
+ description: "The fraction of tasks that may fail during a rollback before the failure action is invoked, specified as a floating point number between 0 and 1."
+ type: "number"
+ default: 0
Networks:
description: "Array of network names or IDs to attach the service to."
type: "array"
@@ -2387,6 +2413,13 @@ definitions:
Replicas: 1
UpdateConfig:
Parallelism: 1
+ Delay: 1000000000
+ FailureAction: "pause"
+ Monitor: 15000000000
+ MaxFailureRatio: 0.15
+ RollbackConfig:
+ Parallelism: 1
+ Delay: 1000000000
FailureAction: "pause"
Monitor: 15000000000
MaxFailureRatio: 0.15
@@ -7436,9 +7469,17 @@ paths:
Replicated:
Replicas: 4
UpdateConfig:
- Delay: 30000000000
Parallelism: 2
+ Delay: 1000000000
FailureAction: "pause"
+ Monitor: 15000000000
+ MaxFailureRatio: 0.15
+ RollbackConfig:
+ Parallelism: 1
+ Delay: 1000000000
+ FailureAction: "pause"
+ Monitor: 15000000000
+ MaxFailureRatio: 0.15
EndpointSpec:
Ports:
-
@@ -7564,7 +7605,15 @@ paths:
Replicated:
Replicas: 1
UpdateConfig:
+ Parallelism: 2
+ Delay: 1000000000
+ FailureAction: "pause"
+ Monitor: 15000000000
+ MaxFailureRatio: 0.15
+ RollbackConfig:
Parallelism: 1
+ Delay: 1000000000
+ FailureAction: "pause"
Monitor: 15000000000
MaxFailureRatio: 0.15
EndpointSpec:
diff --git a/api/types/swarm/service.go b/api/types/swarm/service.go
index 0a909c38b7..d34fb7ef4c 100644
--- a/api/types/swarm/service.go
+++ b/api/types/swarm/service.go
@@ -18,9 +18,10 @@ type ServiceSpec struct {
// TaskTemplate defines how the service should construct new tasks when
// orchestrating this service.
- TaskTemplate TaskSpec `json:",omitempty"`
- Mode ServiceMode `json:",omitempty"`
- UpdateConfig *UpdateConfig `json:",omitempty"`
+ TaskTemplate TaskSpec `json:",omitempty"`
+ Mode ServiceMode `json:",omitempty"`
+ UpdateConfig *UpdateConfig `json:",omitempty"`
+ RollbackConfig *UpdateConfig `json:",omitempty"`
// Networks field in ServiceSpec is deprecated. The
// same field in TaskSpec should be used instead.
diff --git a/cli/command/formatter/service.go b/cli/command/formatter/service.go
index 421728976f..98c760ed7f 100644
--- a/cli/command/formatter/service.go
+++ b/cli/command/formatter/service.go
@@ -57,6 +57,18 @@ UpdateConfig:
{{- end }}
Max failure ratio: {{ .UpdateMaxFailureRatio }}
{{- end }}
+{{- if .HasRollbackConfig }}
+RollbackConfig:
+ Parallelism: {{ .RollbackParallelism }}
+{{- if .HasRollbackDelay}}
+ Delay: {{ .RollbackDelay }}
+{{- end }}
+ On failure: {{ .RollbackOnFailure }}
+{{- if .HasRollbackMonitor}}
+ Monitoring Period: {{ .RollbackMonitor }}
+{{- end }}
+ Max failure ratio: {{ .RollbackMaxFailureRatio }}
+{{- end }}
ContainerSpec:
Image: {{ .ContainerImage }}
{{- if .ContainerArgs }}
@@ -259,6 +271,38 @@ func (ctx *serviceInspectContext) UpdateMaxFailureRatio() float32 {
return ctx.Service.Spec.UpdateConfig.MaxFailureRatio
}
+func (ctx *serviceInspectContext) HasRollbackConfig() bool {
+ return ctx.Service.Spec.RollbackConfig != nil
+}
+
+func (ctx *serviceInspectContext) RollbackParallelism() uint64 {
+ return ctx.Service.Spec.RollbackConfig.Parallelism
+}
+
+func (ctx *serviceInspectContext) HasRollbackDelay() bool {
+ return ctx.Service.Spec.RollbackConfig.Delay.Nanoseconds() > 0
+}
+
+func (ctx *serviceInspectContext) RollbackDelay() time.Duration {
+ return ctx.Service.Spec.RollbackConfig.Delay
+}
+
+func (ctx *serviceInspectContext) RollbackOnFailure() string {
+ return ctx.Service.Spec.RollbackConfig.FailureAction
+}
+
+func (ctx *serviceInspectContext) HasRollbackMonitor() bool {
+ return ctx.Service.Spec.RollbackConfig.Monitor.Nanoseconds() > 0
+}
+
+func (ctx *serviceInspectContext) RollbackMonitor() time.Duration {
+ return ctx.Service.Spec.RollbackConfig.Monitor
+}
+
+func (ctx *serviceInspectContext) RollbackMaxFailureRatio() float32 {
+ return ctx.Service.Spec.RollbackConfig.MaxFailureRatio
+}
+
func (ctx *serviceInspectContext) ContainerImage() string {
return ctx.Service.Spec.TaskTemplate.ContainerSpec.Image
}
diff --git a/cli/command/service/inspect_test.go b/cli/command/service/inspect_test.go
index 34c41ee78a..94c96cc164 100644
--- a/cli/command/service/inspect_test.go
+++ b/cli/command/service/inspect_test.go
@@ -49,7 +49,6 @@ func formatServiceInspect(t *testing.T, format formatter.Format, now time.Time)
Replicas: &two,
},
},
- UpdateConfig: nil,
Networks: []swarm.NetworkAttachmentConfig{
{
Target: "5vpyomhb6ievnk0i0o60gcnei",
diff --git a/cli/command/service/opts.go b/cli/command/service/opts.go
index b9ae89ad0c..baaa58e1f0 100644
--- a/cli/command/service/opts.go
+++ b/cli/command/service/opts.go
@@ -165,6 +165,16 @@ type updateOptions struct {
maxFailureRatio floatValue
}
+func (opts updateOptions) config() *swarm.UpdateConfig {
+ return &swarm.UpdateConfig{
+ Parallelism: opts.parallelism,
+ Delay: opts.delay,
+ Monitor: opts.monitor,
+ FailureAction: opts.onFailure,
+ MaxFailureRatio: opts.maxFailureRatio.Value(),
+ }
+}
+
type resourceOptions struct {
limitCPU opts.NanoCPUs
limitMemBytes opts.MemBytes
@@ -328,6 +338,7 @@ type serviceOptions struct {
constraints opts.ListOpts
placementPrefs placementPrefOpts
update updateOptions
+ rollback updateOptions
networks opts.ListOpts
endpoint endpointOptions
@@ -445,16 +456,11 @@ func (opts *serviceOptions) ToService() (swarm.ServiceSpec, error) {
},
LogDriver: opts.logDriver.toLogDriver(),
},
- Networks: convertNetworks(opts.networks.GetAll()),
- Mode: serviceMode,
- UpdateConfig: &swarm.UpdateConfig{
- Parallelism: opts.update.parallelism,
- Delay: opts.update.delay,
- Monitor: opts.update.monitor,
- FailureAction: opts.update.onFailure,
- MaxFailureRatio: opts.update.maxFailureRatio.Value(),
- },
- EndpointSpec: opts.endpoint.ToEndpointSpec(),
+ Networks: convertNetworks(opts.networks.GetAll()),
+ Mode: serviceMode,
+ UpdateConfig: opts.update.config(),
+ RollbackConfig: opts.rollback.config(),
+ EndpointSpec: opts.endpoint.ToEndpointSpec(),
}
return service, nil
@@ -491,6 +497,17 @@ func addServiceFlags(cmd *cobra.Command, opts *serviceOptions) {
flags.Var(&opts.update.maxFailureRatio, flagUpdateMaxFailureRatio, "Failure rate to tolerate during an update")
flags.SetAnnotation(flagUpdateMaxFailureRatio, "version", []string{"1.25"})
+ flags.Uint64Var(&opts.rollback.parallelism, flagRollbackParallelism, 1, "Maximum number of tasks rolled back simultaneously (0 to roll back all at once)")
+ flags.SetAnnotation(flagRollbackParallelism, "version", []string{"1.27"})
+ flags.DurationVar(&opts.rollback.delay, flagRollbackDelay, time.Duration(0), "Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s)")
+ flags.SetAnnotation(flagRollbackDelay, "version", []string{"1.27"})
+ flags.DurationVar(&opts.rollback.monitor, flagRollbackMonitor, time.Duration(0), "Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 0s)")
+ flags.SetAnnotation(flagRollbackMonitor, "version", []string{"1.27"})
+ flags.StringVar(&opts.rollback.onFailure, flagRollbackFailureAction, "pause", `Action on rollback failure ("pause"|"continue")`)
+ flags.SetAnnotation(flagRollbackFailureAction, "version", []string{"1.27"})
+ flags.Var(&opts.rollback.maxFailureRatio, flagRollbackMaxFailureRatio, "Failure rate to tolerate during a rollback")
+ flags.SetAnnotation(flagRollbackMaxFailureRatio, "version", []string{"1.27"})
+
flags.StringVar(&opts.endpoint.mode, flagEndpointMode, "vip", "Endpoint mode (vip or dnsrr)")
flags.BoolVar(&opts.registryAuth, flagRegistryAuth, false, "Send registry authentication details to swarm agents")
@@ -520,77 +537,82 @@ func addServiceFlags(cmd *cobra.Command, opts *serviceOptions) {
}
const (
- flagPlacementPref = "placement-pref"
- flagPlacementPrefAdd = "placement-pref-add"
- flagPlacementPrefRemove = "placement-pref-rm"
- flagConstraint = "constraint"
- flagConstraintRemove = "constraint-rm"
- flagConstraintAdd = "constraint-add"
- flagContainerLabel = "container-label"
- flagContainerLabelRemove = "container-label-rm"
- flagContainerLabelAdd = "container-label-add"
- flagDNS = "dns"
- flagDNSRemove = "dns-rm"
- flagDNSAdd = "dns-add"
- flagDNSOption = "dns-option"
- flagDNSOptionRemove = "dns-option-rm"
- flagDNSOptionAdd = "dns-option-add"
- flagDNSSearch = "dns-search"
- flagDNSSearchRemove = "dns-search-rm"
- flagDNSSearchAdd = "dns-search-add"
- flagEndpointMode = "endpoint-mode"
- flagHost = "host"
- flagHostAdd = "host-add"
- flagHostRemove = "host-rm"
- flagHostname = "hostname"
- flagEnv = "env"
- flagEnvFile = "env-file"
- flagEnvRemove = "env-rm"
- flagEnvAdd = "env-add"
- flagGroup = "group"
- flagGroupAdd = "group-add"
- flagGroupRemove = "group-rm"
- flagLabel = "label"
- flagLabelRemove = "label-rm"
- flagLabelAdd = "label-add"
- flagLimitCPU = "limit-cpu"
- flagLimitMemory = "limit-memory"
- flagMode = "mode"
- flagMount = "mount"
- flagMountRemove = "mount-rm"
- flagMountAdd = "mount-add"
- flagName = "name"
- flagNetwork = "network"
- flagPublish = "publish"
- flagPublishRemove = "publish-rm"
- flagPublishAdd = "publish-add"
- flagReadOnly = "read-only"
- flagReplicas = "replicas"
- flagReserveCPU = "reserve-cpu"
- flagReserveMemory = "reserve-memory"
- flagRestartCondition = "restart-condition"
- flagRestartDelay = "restart-delay"
- flagRestartMaxAttempts = "restart-max-attempts"
- flagRestartWindow = "restart-window"
- flagStopGracePeriod = "stop-grace-period"
- flagStopSignal = "stop-signal"
- flagTTY = "tty"
- flagUpdateDelay = "update-delay"
- flagUpdateFailureAction = "update-failure-action"
- flagUpdateMaxFailureRatio = "update-max-failure-ratio"
- flagUpdateMonitor = "update-monitor"
- flagUpdateParallelism = "update-parallelism"
- flagUser = "user"
- flagWorkdir = "workdir"
- flagRegistryAuth = "with-registry-auth"
- flagLogDriver = "log-driver"
- flagLogOpt = "log-opt"
- flagHealthCmd = "health-cmd"
- flagHealthInterval = "health-interval"
- flagHealthRetries = "health-retries"
- flagHealthTimeout = "health-timeout"
- flagNoHealthcheck = "no-healthcheck"
- flagSecret = "secret"
- flagSecretAdd = "secret-add"
- flagSecretRemove = "secret-rm"
+ flagPlacementPref = "placement-pref"
+ flagPlacementPrefAdd = "placement-pref-add"
+ flagPlacementPrefRemove = "placement-pref-rm"
+ flagConstraint = "constraint"
+ flagConstraintRemove = "constraint-rm"
+ flagConstraintAdd = "constraint-add"
+ flagContainerLabel = "container-label"
+ flagContainerLabelRemove = "container-label-rm"
+ flagContainerLabelAdd = "container-label-add"
+ flagDNS = "dns"
+ flagDNSRemove = "dns-rm"
+ flagDNSAdd = "dns-add"
+ flagDNSOption = "dns-option"
+ flagDNSOptionRemove = "dns-option-rm"
+ flagDNSOptionAdd = "dns-option-add"
+ flagDNSSearch = "dns-search"
+ flagDNSSearchRemove = "dns-search-rm"
+ flagDNSSearchAdd = "dns-search-add"
+ flagEndpointMode = "endpoint-mode"
+ flagHost = "host"
+ flagHostAdd = "host-add"
+ flagHostRemove = "host-rm"
+ flagHostname = "hostname"
+ flagEnv = "env"
+ flagEnvFile = "env-file"
+ flagEnvRemove = "env-rm"
+ flagEnvAdd = "env-add"
+ flagGroup = "group"
+ flagGroupAdd = "group-add"
+ flagGroupRemove = "group-rm"
+ flagLabel = "label"
+ flagLabelRemove = "label-rm"
+ flagLabelAdd = "label-add"
+ flagLimitCPU = "limit-cpu"
+ flagLimitMemory = "limit-memory"
+ flagMode = "mode"
+ flagMount = "mount"
+ flagMountRemove = "mount-rm"
+ flagMountAdd = "mount-add"
+ flagName = "name"
+ flagNetwork = "network"
+ flagPublish = "publish"
+ flagPublishRemove = "publish-rm"
+ flagPublishAdd = "publish-add"
+ flagReadOnly = "read-only"
+ flagReplicas = "replicas"
+ flagReserveCPU = "reserve-cpu"
+ flagReserveMemory = "reserve-memory"
+ flagRestartCondition = "restart-condition"
+ flagRestartDelay = "restart-delay"
+ flagRestartMaxAttempts = "restart-max-attempts"
+ flagRestartWindow = "restart-window"
+ flagRollbackDelay = "rollback-delay"
+ flagRollbackFailureAction = "rollback-failure-action"
+ flagRollbackMaxFailureRatio = "rollback-max-failure-ratio"
+ flagRollbackMonitor = "rollback-monitor"
+ flagRollbackParallelism = "rollback-parallelism"
+ flagStopGracePeriod = "stop-grace-period"
+ flagStopSignal = "stop-signal"
+ flagTTY = "tty"
+ flagUpdateDelay = "update-delay"
+ flagUpdateFailureAction = "update-failure-action"
+ flagUpdateMaxFailureRatio = "update-max-failure-ratio"
+ flagUpdateMonitor = "update-monitor"
+ flagUpdateParallelism = "update-parallelism"
+ flagUser = "user"
+ flagWorkdir = "workdir"
+ flagRegistryAuth = "with-registry-auth"
+ flagLogDriver = "log-driver"
+ flagLogOpt = "log-opt"
+ flagHealthCmd = "health-cmd"
+ flagHealthInterval = "health-interval"
+ flagHealthRetries = "health-retries"
+ flagHealthTimeout = "health-timeout"
+ flagNoHealthcheck = "no-healthcheck"
+ flagSecret = "secret"
+ flagSecretAdd = "secret-add"
+ flagSecretRemove = "secret-rm"
)
diff --git a/cli/command/service/update.go b/cli/command/service/update.go
index 0c19c0713e..b529331500 100644
--- a/cli/command/service/update.go
+++ b/cli/command/service/update.go
@@ -289,6 +289,17 @@ func updateService(flags *pflag.FlagSet, spec *swarm.ServiceSpec) error {
updateFloatValue(flagUpdateMaxFailureRatio, &spec.UpdateConfig.MaxFailureRatio)
}
+ if anyChanged(flags, flagRollbackParallelism, flagRollbackDelay, flagRollbackMonitor, flagRollbackFailureAction, flagRollbackMaxFailureRatio) {
+ if spec.RollbackConfig == nil {
+ spec.RollbackConfig = &swarm.UpdateConfig{}
+ }
+ updateUint64(flagRollbackParallelism, &spec.RollbackConfig.Parallelism)
+ updateDuration(flagRollbackDelay, &spec.RollbackConfig.Delay)
+ updateDuration(flagRollbackMonitor, &spec.RollbackConfig.Monitor)
+ updateString(flagRollbackFailureAction, &spec.RollbackConfig.FailureAction)
+ updateFloatValue(flagRollbackMaxFailureRatio, &spec.RollbackConfig.MaxFailureRatio)
+ }
+
if flags.Changed(flagEndpointMode) {
value, _ := flags.GetString(flagEndpointMode)
if spec.EndpointSpec == nil {
diff --git a/daemon/cluster/convert/service.go b/daemon/cluster/convert/service.go
index 91c96eec73..779f102084 100644
--- a/daemon/cluster/convert/service.go
+++ b/daemon/cluster/convert/service.go
@@ -92,26 +92,8 @@ func serviceSpecFromGRPC(spec *swarmapi.ServiceSpec) *types.ServiceSpec {
}
// UpdateConfig
- if spec.Update != nil {
- convertedSpec.UpdateConfig = &types.UpdateConfig{
- Parallelism: spec.Update.Parallelism,
- MaxFailureRatio: spec.Update.MaxFailureRatio,
- }
-
- convertedSpec.UpdateConfig.Delay = spec.Update.Delay
- if spec.Update.Monitor != nil {
- convertedSpec.UpdateConfig.Monitor, _ = gogotypes.DurationFromProto(spec.Update.Monitor)
- }
-
- switch spec.Update.FailureAction {
- case swarmapi.UpdateConfig_PAUSE:
- convertedSpec.UpdateConfig.FailureAction = types.UpdateFailureActionPause
- case swarmapi.UpdateConfig_CONTINUE:
- convertedSpec.UpdateConfig.FailureAction = types.UpdateFailureActionContinue
- case swarmapi.UpdateConfig_ROLLBACK:
- convertedSpec.UpdateConfig.FailureAction = types.UpdateFailureActionRollback
- }
- }
+ convertedSpec.UpdateConfig = updateConfigFromGRPC(spec.Update)
+ convertedSpec.RollbackConfig = updateConfigFromGRPC(spec.Rollback)
// Mode
switch t := spec.GetMode().(type) {
@@ -188,27 +170,13 @@ func ServiceSpecToGRPC(s types.ServiceSpec) (swarmapi.ServiceSpec, error) {
}
}
- if s.UpdateConfig != nil {
- var failureAction swarmapi.UpdateConfig_FailureAction
- switch s.UpdateConfig.FailureAction {
- case types.UpdateFailureActionPause, "":
- failureAction = swarmapi.UpdateConfig_PAUSE
- case types.UpdateFailureActionContinue:
- failureAction = swarmapi.UpdateConfig_CONTINUE
- case types.UpdateFailureActionRollback:
- failureAction = swarmapi.UpdateConfig_ROLLBACK
- default:
- return swarmapi.ServiceSpec{}, fmt.Errorf("unrecognized update failure action %s", s.UpdateConfig.FailureAction)
- }
- spec.Update = &swarmapi.UpdateConfig{
- Parallelism: s.UpdateConfig.Parallelism,
- Delay: s.UpdateConfig.Delay,
- FailureAction: failureAction,
- MaxFailureRatio: s.UpdateConfig.MaxFailureRatio,
- }
- if s.UpdateConfig.Monitor != 0 {
- spec.Update.Monitor = gogotypes.DurationProto(s.UpdateConfig.Monitor)
- }
+ spec.Update, err = updateConfigToGRPC(s.UpdateConfig)
+ if err != nil {
+ return swarmapi.ServiceSpec{}, err
+ }
+ spec.Rollback, err = updateConfigToGRPC(s.RollbackConfig)
+ if err != nil {
+ return swarmapi.Servicepec{}, err
}
if s.EndpointSpec != nil {
@@ -415,3 +383,58 @@ func driverToGRPC(p *types.Driver) *swarmapi.Driver {
Options: p.Options,
}
}
+
+func updateConfigFromGRPC(updateConfig *swarmapi.UpdateConfig) *types.UpdateConfig {
+ if updateConfig == nil {
+ return nil
+ }
+
+ converted := &types.UpdateConfig{
+ Parallelism: updateConfig.Parallelism,
+ MaxFailureRatio: updateConfig.MaxFailureRatio,
+ }
+
+ converted.Delay = updateConfig.Delay
+ if updateConfig.Monitor != nil {
+ converted.Monitor, _ = gogotypes.DurationFromProto(updateConfig.Monitor)
+ }
+
+ switch updateConfig.FailureAction {
+ case swarmapi.UpdateConfig_PAUSE:
+ converted.FailureAction = types.UpdateFailureActionPause
+ case swarmapi.UpdateConfig_CONTINUE:
+ converted.FailureAction = types.UpdateFailureActionContinue
+ case swarmapi.UpdateConfig_ROLLBACK:
+ converted.FailureAction = types.UpdateFailureActionRollback
+ }
+
+ return converted
+}
+
+func updateConfigToGRPC(updateConfig *types.UpdateConfig) (*swarmapi.UpdateConfig, error) {
+ if updateConfig == nil {
+ return nil, nil
+ }
+
+ converted := &swarmapi.UpdateConfig{
+ Parallelism: updateConfig.Parallelism,
+ Delay: updateConfig.Delay,
+ MaxFailureRatio: updateConfig.MaxFailureRatio,
+ }
+
+ switch updateConfig.FailureAction {
+ case types.UpdateFailureActionPause, "":
+ converted.FailureAction = swarmapi.UpdateConfig_PAUSE
+ case types.UpdateFailureActionContinue:
+ converted.FailureAction = swarmapi.UpdateConfig_CONTINUE
+ case types.UpdateFailureActionRollback:
+ converted.FailureAction = swarmapi.UpdateConfig_ROLLBACK
+ default:
+ return nil, fmt.Errorf("unrecongized update failure action %s", updateConfig.FailureAction)
+ }
+ if updateConfig.Monitor != 0 {
+ converted.Monitor = gogotypes.DurationProto(updateConfig.Monitor)
+ }
+
+ return converted, nil
+}
diff --git a/docs/api/version-history.md b/docs/api/version-history.md
index a802170b68..541111c14a 100644
--- a/docs/api/version-history.md
+++ b/docs/api/version-history.md
@@ -23,6 +23,7 @@ keywords: "API, Docker, rcli, REST, documentation"
* `POST /services/create` and `POST /services/(id or name)/update` now accept the `ReadOnly` parameter, which mounts the container's root filesystem as read only.
* `POST /build` now accepts `extrahosts` parameter to specify a host to ip mapping to use during the build.
* `POST /services/create` and `POST /services/(id or name)/update` now accept a `rollback` value for `FailureAction`.
+* `POST /services/create` and `POST /services/(id or name)/update` now accept an optional `RollbackConfig` object which specifies rollback options.
## v1.26 API changes
diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md
index ba06b3f33e..6f8fcb134a 100644
--- a/docs/reference/commandline/service_create.md
+++ b/docs/reference/commandline/service_create.md
@@ -21,54 +21,61 @@ Usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]
Create a new service
Options:
- --constraint list Placement constraints (default [])
- --container-label list Container labels (default [])
- --dns list Set custom DNS servers (default [])
- --dns-option list Set DNS options (default [])
- --dns-search list Set custom DNS search domains (default [])
- --endpoint-mode string Endpoint mode ("vip"|"dnsrr") (default "vip")
- -e, --env list Set environment variables (default [])
- --env-file list Read in a file of environment variables (default [])
- --group list Set one or more supplementary user groups for the container (default [])
- --health-cmd string Command to run to check health
- --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)
- --help Print usage
- --host list Set one or more custom host-to-IP mappings (host:ip) (default [])
- --hostname string Container hostname
- -l, --label list Service labels (default [])
- --limit-cpu decimal Limit CPUs (default 0.000)
- --limit-memory bytes Limit Memory
- --log-driver string Logging driver for service
- --log-opt list Logging driver options (default [])
- --mode string Service mode (replicated or global) (default "replicated")
- --mount mount Attach a filesystem mount to the service
- --name string Service name
- --network list Network attachments (default [])
- --no-healthcheck Disable any container-specified HEALTHCHECK
- --placement-pref pref Add a placement preference
- -p, --publish port Publish a port as a node port
- --read-only Mount the container's root filesystem as read only
- --replicas uint Number of tasks
- --reserve-cpu decimal Reserve CPUs (default 0.000)
- --reserve-memory bytes Reserve Memory
- --restart-condition string Restart when condition is met ("none"|"on-failure"|"any")
- --restart-delay duration Delay between restart attempts (ns|us|ms|s|m|h)
- --restart-max-attempts uint Maximum number of restarts before giving up
- --restart-window duration Window used to evaluate the restart policy (ns|us|ms|s|m|h)
- --secret secret Specify secrets to expose to the service
- --stop-grace-period duration Time to wait before force killing a container (ns|us|ms|s|m|h)
- --stop-signal string Signal to stop the container
- -t, --tty Allocate a pseudo-TTY
- --update-delay duration Delay between updates (ns|us|ms|s|m|h) (default 0s)
- --update-failure-action string Action on update failure ("pause"|"continue"|"rollback") (default "pause")
- --update-max-failure-ratio float Failure rate to tolerate during an update
- --update-monitor duration Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s)
- --update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1)
- -u, --user string Username or UID (format: <name|uid>[:<group|gid>])
- --with-registry-auth Send registry authentication details to swarm agents
- -w, --workdir string Working directory inside the container
+ --constraint list Placement constraints (default [])
+ --container-label list Container labels (default [])
+ --dns list Set custom DNS servers (default [])
+ --dns-option list Set DNS options (default [])
+ --dns-search list Set custom DNS search domains (default [])
+ --endpoint-mode string Endpoint mode ("vip"|"dnsrr") (default "vip")
+ -e, --env list Set environment variables (default [])
+ --env-file list Read in a file of environment variables (default [])
+ --group list Set one or more supplementary user groups for the container (default [])
+ --health-cmd string Command to run to check health
+ --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)
+ --help Print usage
+ --host list Set one or more custom host-to-IP mappings (host:ip) (default [])
+ --hostname string Container hostname
+ -l, --label list Service labels (default [])
+ --limit-cpu decimal Limit CPUs (default 0.000)
+ --limit-memory bytes Limit Memory
+ --log-driver string Logging driver for service
+ --log-opt list Logging driver options (default [])
+ --mode string Service mode (replicated or global) (default "replicated")
+ --mount mount Attach a filesystem mount to the service
+ --name string Service name
+ --network list Network attachments (default [])
+ --no-healthcheck Disable any container-specified HEALTHCHECK
+ --placement-pref pref Add a placement preference
+ -p, --publish port Publish a port as a node port
+ --read-only Mount the container's root filesystem as read only
+ --replicas uint Number of tasks
+ --reserve-cpu decimal Reserve CPUs (default 0.000)
+ --reserve-memory bytes Reserve Memory
+ --restart-condition string Restart when condition is met ("none"|"on-failure"|"any")
+ --restart-delay duration Delay between restart attempts (ns|us|ms|s|m|h)
+ --restart-max-attempts uint Maximum number of restarts before giving up
+ --restart-window duration Window used to evaluate the restart policy (ns|us|ms|s|m|h)
+ --rollback-delay duration Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s)
+ --rollback-failure-action string Action on rollback failure ("pause"|"continue") (default "pause")
+ --rollback-max-failure-ratio float Failure rate to tolerate during a rollback
+ --rollback-monitor duration Duration after each task rollback to monitor for failure
+ (ns|us|ms|s|m|h) (default 0s)
+ --rollback-parallelism uint Maximum number of tasks rolled back simultaneously (0 to roll
+ back all at once) (default 1)
+ --secret secret Specify secrets to expose to the service
+ --stop-grace-period duration Time to wait before force killing a container (ns|us|ms|s|m|h)
+ --stop-signal string Signal to stop the container
+ -t, --tty Allocate a pseudo-TTY
+ --update-delay duration Delay between updates (ns|us|ms|s|m|h) (default 0s)
+ --update-failure-action string Action on update failure ("pause"|"continue"|"rollback") (default "pause")
+ --update-max-failure-ratio float Failure rate to tolerate during an update
+ --update-monitor duration Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s)
+ --update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1)
+ -u, --user string Username or UID (format: <name|uid>[:<group|gid>])
+ --with-registry-auth Send registry authentication details to swarm agents
+ -w, --workdir string Working directory inside the container
```
## Description
diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md
index 6a6a589a5d..1f418a250a 100644
--- a/docs/reference/commandline/service_update.md
+++ b/docs/reference/commandline/service_update.md
@@ -21,67 +21,74 @@ Usage: docker service update [OPTIONS] SERVICE
Update a service
Options:
- --args string Service command args
- --constraint-add list Add or update a placement constraint (default [])
- --constraint-rm list Remove a constraint (default [])
- --container-label-add list Add or update a container label (default [])
- --container-label-rm list Remove a container label by its key (default [])
- --dns-add list Add or update a custom DNS server (default [])
- --dns-option-add list Add or update a DNS option (default [])
- --dns-option-rm list Remove a DNS option (default [])
- --dns-rm list Remove a custom DNS server (default [])
- --dns-search-add list Add or update a custom DNS search domain (default [])
- --dns-search-rm list Remove a DNS search domain (default [])
- --endpoint-mode string Endpoint mode ("vip"|"dnsrr") (default "vip")
- --env-add list Add or update an environment variable (default [])
- --env-rm list Remove an environment variable (default [])
- --force Force update even if no changes require it
- --group-add list Add an additional supplementary user group to the container (default [])
- --group-rm list Remove a previously added supplementary user group from the container (default [])
- --health-cmd string Command to run to check health
- --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)
- --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 [])
- --hostname string Container hostname
- --image string Service image tag
- --label-add list Add or update a service label (default [])
- --label-rm list Remove a label by its key (default [])
- --limit-cpu decimal Limit CPUs (default 0.000)
- --limit-memory bytes Limit Memory
- --log-driver string Logging driver for service
- --log-opt list Logging driver options (default [])
- --mount-add mount Add or update a mount on a service
- --mount-rm list Remove a mount by its target path (default [])
- --no-healthcheck Disable any container-specified HEALTHCHECK
- --placement-pref-add pref Add a placement preference
- --placement-pref-rm pref Remove a placement preference
- --publish-add port Add or update a published port
- --publish-rm port Remove a published port by its target port
- --read-only Mount the container's root filesystem as read only
- --replicas uint Number of tasks
- --reserve-cpu decimal Reserve CPUs (default 0.000)
- --reserve-memory bytes Reserve Memory
- --restart-condition string Restart when condition is met ("none"|"on-failure"|"any")
- --restart-delay duration Delay between restart attempts (ns|us|ms|s|m|h)
- --restart-max-attempts uint Maximum number of restarts before giving up
- --restart-window duration Window used to evaluate the restart policy (ns|us|ms|s|m|h)
- --rollback Rollback to previous specification
- --secret-add secret Add or update a secret on a service
- --secret-rm list Remove a secret (default [])
- --stop-grace-period duration Time to wait before force killing a container (ns|us|ms|s|m|h)
- --stop-signal string Signal to stop the container
- -t, --tty Allocate a pseudo-TTY
- --update-delay duration Delay between updates (ns|us|ms|s|m|h) (default 0s)
- --update-failure-action string Action on update failure ("pause"|"continue"|"rollback") (default "pause")
- --update-max-failure-ratio float Failure rate to tolerate during an update
- --update-monitor duration Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s)
- --update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1)
- -u, --user string Username or UID (format: <name|uid>[:<group|gid>])
- --with-registry-auth Send registry authentication details to swarm agents
- -w, --workdir string Working directory inside the container
+ --args string Service command args
+ --constraint-add list Add or update a placement constraint (default [])
+ --constraint-rm list Remove a constraint (default [])
+ --container-label-add list Add or update a container label (default [])
+ --container-label-rm list Remove a container label by its key (default [])
+ --dns-add list Add or update a custom DNS server (default [])
+ --dns-option-add list Add or update a DNS option (default [])
+ --dns-option-rm list Remove a DNS option (default [])
+ --dns-rm list Remove a custom DNS server (default [])
+ --dns-search-add list Add or update a custom DNS search domain (default [])
+ --dns-search-rm list Remove a DNS search domain (default [])
+ --endpoint-mode string Endpoint mode ("vip"|"dnsrr") (default "vip")
+ --env-add list Add or update an environment variable (default [])
+ --env-rm list Remove an environment variable (default [])
+ --force Force update even if no changes require it
+ --group-add list Add an additional supplementary user group to the container (default [])
+ --group-rm list Remove a previously added supplementary user group from the container (default [])
+ --health-cmd string Command to run to check health
+ --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)
+ --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 [])
+ --hostname string Container hostname
+ --image string Service image tag
+ --label-add list Add or update a service label (default [])
+ --label-rm list Remove a label by its key (default [])
+ --limit-cpu decimal Limit CPUs (default 0.000)
+ --limit-memory bytes Limit Memory
+ --log-driver string Logging driver for service
+ --log-opt list Logging driver options (default [])
+ --mount-add mount Add or update a mount on a service
+ --mount-rm list Remove a mount by its target path (default [])
+ --no-healthcheck Disable any container-specified HEALTHCHECK
+ --placement-pref-add pref Add a placement preference
+ --placement-pref-rm pref Remove a placement preference
+ --publish-add port Add or update a published port
+ --publish-rm port Remove a published port by its target port
+ --read-only Mount the container's root filesystem as read only
+ --replicas uint Number of tasks
+ --reserve-cpu decimal Reserve CPUs (default 0.000)
+ --reserve-memory bytes Reserve Memory
+ --restart-condition string Restart when condition is met ("none"|"on-failure"|"any")
+ --restart-delay duration Delay between restart attempts (ns|us|ms|s|m|h)
+ --restart-max-attempts uint Maximum number of restarts before giving up
+ --restart-window duration Window used to evaluate the restart policy (ns|us|ms|s|m|h)
+ --rollback Rollback to previous specification
+ --rollback-delay duration Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s)
+ --rollback-failure-action string Action on rollback failure ("pause"|"continue") (default "pause")
+ --rollback-max-failure-ratio float Failure rate to tolerate during a rollback
+ --rollback-monitor duration Duration after each task rollback to monitor for failure
+ (ns|us|ms|s|m|h) (default 0s)
+ --rollback-parallelism uint Maximum number of tasks rolled back simultaneously (0 to roll
+ back all at once) (default 1)
+ --secret-add secret Add or update a secret on a service
+ --secret-rm list Remove a secret (default [])
+ --stop-grace-period duration Time to wait before force killing a container (ns|us|ms|s|m|h)
+ --stop-signal string Signal to stop the container
+ -t, --tty Allocate a pseudo-TTY
+ --update-delay duration Delay between updates (ns|us|ms|s|m|h) (default 0s)
+ --update-failure-action string Action on update failure ("pause"|"continue"|"rollback") (default "pause")
+ --update-max-failure-ratio float Failure rate to tolerate during an update
+ --update-monitor duration Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s)
+ --update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1)
+ -u, --user string Username or UID (format: <name|uid>[:<group|gid>])
+ --with-registry-auth Send registry authentication details to swarm agents
+ -w, --workdir string Working directory inside the container
```
## Description
@@ -202,6 +209,26 @@ web
```
+Services can also be set up to roll back to the previous version automatically
+when an update fails. To set up a service for automatic rollback, use
+`--update-failure-action=rollback`. A rollback will be triggered if the fraction
+of the tasks which failed to update successfully exceeds the value given with
+`--update-max-failure-ratio`.
+
+The rate, parallelism, and other parameters of a rollback operation are
+determined by the values passed with the following flags:
+
+- `--rollback-delay`
+- `--rollback-failure-action`
+- `--rollback-max-failure-ratio`
+- `--rollback-monitor`
+- `--rollback-parallelism`
+
+For example, a service set up with `--update-parallelism 1 --rollback-parallelism 3`
+will update one task at a time during a normal update, but during a rollback, 3
+tasks at a time will get rolled back. These rollback parameters are respected both
+during automatic rollbacks and for rollbacks initiated manually using `--rollback`.
+
### Add or remove secrets
Use the `--secret-add` or `--secret-rm` options add or remove a service's