Merge pull request #28696 from jlhawn/deprecate_graph_flag

Deprecate --graph flag; Replace with --data-root

cmd/dockerd/config.go

@@ -21,7 +21,14 @@ func installCommonConfigFlags(conf *config.Config, flags *pflag.FlagSet) {
 	flags.Var(opts.NewNamedListOptsRef("authorization-plugins", &conf.AuthorizationPlugins, nil), "authorization-plugin", "Authorization plugins to load")
 	flags.Var(opts.NewNamedListOptsRef("exec-opts", &conf.ExecOptions, nil), "exec-opt", "Runtime execution options")
 	flags.StringVarP(&conf.Pidfile, "pidfile", "p", defaultPidFile, "Path to use for daemon PID file")
-	flags.StringVarP(&conf.Root, "graph", "g", defaultGraph, "Root of the Docker runtime")
+	flags.StringVarP(&conf.Root, "graph", "g", defaultDataRoot, "Root of the Docker runtime")
+
+	// "--graph" is "soft-deprecated" in favor of "data-root". This flag was added
+	// before Docker 1.0, so won't be removed, only hidden, to discourage its usage.
+	flags.MarkHidden("graph")
+
+	flags.StringVar(&conf.Root, "data-root", defaultDataRoot, "Root directory of persistent Docker state")
+
 	flags.BoolVarP(&conf.AutoRestart, "restart", "r", true, "--restart on the daemon has been deprecated in favor of --restart policies on docker run")
 	flags.MarkDeprecated("restart", "Please use a restart policy on docker run")
 	flags.StringVarP(&conf.GraphDriver, "storage-driver", "s", "", "Storage driver to use")

cmd/dockerd/config_common_unix.go

@@ -11,7 +11,7 @@ import (
 
 var (
 	defaultPidFile  = "/var/run/docker.pid"
-	defaultGraph    = "/var/lib/docker"
+	defaultDataRoot = "/var/lib/docker"
 	defaultExecRoot = "/var/run/docker"
 )
 

cmd/dockerd/config_windows.go

@@ -9,8 +9,8 @@ import (
 )
 
 var (
-	defaultPidFile string
-	defaultGraph   = filepath.Join(os.Getenv("programdata"), "docker")
+	defaultPidFile  string
+	defaultDataRoot = filepath.Join(os.Getenv("programdata"), "docker")
 )
 
 // installConfigFlags adds flags to the pflag.FlagSet to configure the daemon

cmd/dockerd/daemon.go

@@ -419,6 +419,10 @@ func loadDaemonCliConfig(opts daemonOptions) (*config.Config, error) {
 		conf.CommonTLSOptions.KeyFile = opts.common.TLSOptions.KeyFile
 	}
 
+	if flags.Changed("graph") && flags.Changed("data-root") {
+		return nil, fmt.Errorf(`cannot specify both "--graph" and "--data-root" option`)
+	}
+
 	if opts.configFile != "" {
 		c, err := config.MergeDaemonConfigurations(conf, flags, opts.configFile)
 		if err != nil {
@@ -437,6 +441,10 @@ func loadDaemonCliConfig(opts daemonOptions) (*config.Config, error) {
 		return nil, err
 	}
 
+	if flags.Changed("graph") {
+		logrus.Warnf(`the "-g / --graph" flag is deprecated. Please use "--data-root" instead`)
+	}
+
 	// Labels of the docker engine used to allow multiple values associated with the same key.
 	// This is deprecated in 1.13, and, be removed after 3 release cycles.
 	// The following will check the conflict of labels, and report a warning for deprecation.

contrib/completion/bash/docker

@@ -1936,6 +1936,7 @@ _docker_daemon() {
 		--cluster-store-opt
 		--config-file
 		--containerd
+		--data-root
 		--default-gateway
 		--default-gateway-v6
 		--default-shm-size
@@ -1947,7 +1948,6 @@ _docker_daemon() {
 		--exec-root
 		--fixed-cidr
 		--fixed-cidr-v6
-		--graph -g
 		--group -G
 		--init-path
 		--insecure-registry
@@ -2016,7 +2016,7 @@ _docker_daemon() {
 			_filedir
 			return
 			;;
-		--exec-root|--graph|-g)
+		--exec-root|--data-root)
 			_filedir -d
 			return
 			;;

contrib/completion/zsh/_docker

@@ -2605,6 +2605,7 @@ __docker_subcommand() {
                 "($help)*--cluster-store-opt=[Cluster store options]:Cluster options:->cluster-store-options" \
                 "($help)--config-file=[Path to daemon configuration file]:Config File:_files" \
                 "($help)--containerd=[Path to containerd socket]:socket:_files -g \"*.sock\"" \
+                "($help)--data-root=[Root directory of persisted Docker data]:path:_directories" \
                 "($help -D --debug)"{-D,--debug}"[Enable debug mode]" \
                 "($help)--default-gateway[Container default gateway IPv4 address]:IPv4 address: " \
                 "($help)--default-gateway-v6[Container default gateway IPv6 address]:IPv6 address: " \
@@ -2620,7 +2621,6 @@ __docker_subcommand() {
                 "($help)--fixed-cidr=[IPv4 subnet for fixed IPs]:IPv4 subnet: " \
                 "($help)--fixed-cidr-v6=[IPv6 subnet for fixed IPs]:IPv6 subnet: " \
                 "($help -G --group)"{-G=,--group=}"[Group for the unix socket]:group:_groups" \
-                "($help -g --graph)"{-g=,--graph=}"[Root of the Docker runtime]:path:_directories" \
                 "($help -H --host)"{-H=,--host=}"[tcp://host:port to bind/connect to]:host: " \
                 "($help)--icc[Enable inter-container communication]" \
                 "($help)--init[Run an init inside containers to forward signals and reap processes]" \

daemon/config/config.go

@@ -98,7 +98,8 @@ type CommonConfig struct {
 	Mtu                  int                       `json:"mtu,omitempty"`
 	Pidfile              string                    `json:"pidfile,omitempty"`
 	RawLogs              bool                      `json:"raw-logs,omitempty"`
-	Root                 string                    `json:"graph,omitempty"`
+	RootDeprecated       string                    `json:"graph,omitempty"`
+	Root                 string                    `json:"data-root,omitempty"`
 	SocketGroup          string                    `json:"group,omitempty"`
 	TrustKeyPath         string                    `json:"-"`
 	CorsHeaders          string                    `json:"api-cors-header,omitempty"`
@@ -353,8 +354,21 @@ func getConflictFreeConfiguration(configFile string, flags *pflag.FlagSet) (*Con
 	}
 
 	reader = bytes.NewReader(b)
-	err = json.NewDecoder(reader).Decode(&config)
-	return &config, err
+	if err := json.NewDecoder(reader).Decode(&config); err != nil {
+		return nil, err
+	}
+
+	if config.RootDeprecated != "" {
+		logrus.Warn(`The "graph" config file option is deprecated. Please use "data-root" instead.`)
+
+		if config.Root != "" {
+			return nil, fmt.Errorf(`cannot specify both "graph" and "data-root" config file options`)
+		}
+
+		config.Root = config.RootDeprecated
+	}
+
+	return &config, nil
 }
 
 // configValuesSet returns the configuration values explicitly set in the file.

daemon/config/config_solaris.go

@@ -4,12 +4,6 @@ import (
 	"github.com/spf13/pflag"
 )
 
-var (
-	defaultPidFile = "/system/volatile/docker/docker.pid"
-	defaultGraph   = "/var/lib/docker"
-	defaultExec    = "zones"
-)
-
 // Config defines the configuration of a docker daemon.
 // These are the configuration settings that you pass
 // to the docker daemon when you launch it with say: `docker -d -e lxc`

docs/deprecated.md

@@ -20,6 +20,17 @@ The following list of features are deprecated in Engine.
 To learn more about Docker Engine's deprecation policy,
 see [Feature Deprecation Policy](https://docs.docker.com/engine/#feature-deprecation-policy).
 
+### `-g` and `--graph` flags on `dockerd`
+
+**Deprecated In Release: v17.05.0**
+
+The `-g` or `--graph` flag for the `dockerd` or `docker daemon` command was
+used to indicate the directory in which to store persistent data and resource
+configuration and has been replaced with the more descriptive `--data-root`
+flag.
+
+These flags were added before Docker 1.0, so will not be _removed_, only
+_hidden_, to discourage their use.
 
 ### Top-level network properties in NetworkSettings
 

docs/reference/commandline/dockerd.md

@@ -35,6 +35,7 @@ Options:
       --containerd string                     Path to containerd socket
       --cpu-rt-period int                     Limit the CPU real-time period in microseconds
       --cpu-rt-runtime int                    Limit the CPU real-time runtime in microseconds
+      --data-root string                      Root directory of persistent Docker state (default "/var/lib/docker")
   -D, --debug                                 Enable debug mode
       --default-gateway ip                    Container default gateway IPv4 address
       --default-gateway-v6 ip                 Container default gateway IPv6 address
@@ -49,7 +50,6 @@ Options:
       --experimental                          Enable experimental features
       --fixed-cidr string                     IPv4 subnet for fixed IPs
       --fixed-cidr-v6 string                  IPv6 subnet for fixed IPs
-  -g, --graph string                          Root of the Docker runtime (default "/var/lib/docker")
   -G, --group string                          Group for the unix socket (default "docker")
       --help                                  Print usage
   -H, --host list                             Daemon socket(s) to connect to (default [])
@@ -1139,6 +1139,7 @@ This is a full example of the allowed configuration options on Linux:
 ```json
 {
 	"authorization-plugins": [],
+	"data-root": "",
 	"dns": [],
 	"dns-opts": [],
 	"dns-search": [],
@@ -1153,7 +1154,6 @@ This is a full example of the allowed configuration options on Linux:
 	"log-opts": {},
 	"mtu": 0,
 	"pidfile": "",
-	"graph": "",
 	"cluster-store": "",
 	"cluster-store-opts": {},
 	"cluster-advertise": "",
@@ -1232,6 +1232,7 @@ This is a full example of the allowed configuration options on Windows:
 ```json
 {
     "authorization-plugins": [],
+    "data-root": "",
     "dns": [],
     "dns-opts": [],
     "dns-search": [],
@@ -1243,7 +1244,6 @@ This is a full example of the allowed configuration options on Windows:
     "log-driver": "",
     "mtu": 0,
     "pidfile": "",
-    "graph": "",
     "cluster-store": "",
     "cluster-advertise": "",
     "max-concurrent-downloads": 3,
@@ -1321,7 +1321,7 @@ The following daemon options must be configured for each daemon:
 ```none
 -b, --bridge=                          Attach containers to a network bridge
 --exec-root=/var/run/docker            Root of the Docker execdriver
--g, --graph=/var/lib/docker            Root of the Docker runtime
+--data-root=/var/lib/docker            Root of persisted Docker data
 -p, --pidfile=/var/run/docker.pid      Path to use for daemon PID file
 -H, --host=[]                          Daemon socket(s) to connect to
 --iptables=true                        Enable addition of iptables rules
@@ -1338,8 +1338,9 @@ It is very important to properly understand the meaning of those options and to
 If you are not using the default, you must create and configure the bridge manually or just set it to 'none': `--bridge=none`
 - `--exec-root` is the path where the container state is stored. The default value is `/var/run/docker`. Specify the path for
 your running daemon here.
-- `--graph` is the path where images are stored. The default value is `/var/lib/docker`. To avoid any conflict with other daemons
-set this parameter separately for each daemon.
+- `--data-root` is the path where persisted data such as images, volumes, and
+cluster state are stored. The default value is `/var/lib/docker`. To avoid any
+conflict with other daemons, set this parameter separately for each daemon.
 - `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored. Specify the path for your
 pid file here.
 - `--host=[]` specifies where the Docker daemon will listen for client connections. If unspecified, it defaults to `/var/run/docker.sock`.
@@ -1365,6 +1366,6 @@ $ sudo dockerd \
         --iptables=false \
         --ip-masq=false \
         --bridge=none \
-        --graph=/var/lib/docker-bootstrap \
+        --data-root=/var/lib/docker-bootstrap \
         --exec-root=/var/run/docker-bootstrap
 ```

integration-cli/daemon/daemon.go

@@ -218,7 +218,7 @@ func (d *Daemon) StartWithLogFile(out *os.File, providedArgs ...string) error {
 	}
 	args := append(d.GlobalFlags,
 		"--containerd", "/var/run/docker/libcontainerd/docker-containerd.sock",
-		"--graph", d.Root,
+		"--data-root", d.Root,
 		"--exec-root", d.execRoot,
 		"--pidfile", fmt.Sprintf("%s/docker.pid", d.Folder),
 		fmt.Sprintf("--userland-proxy=%t", d.userlandProxy),

integration-cli/docker_cli_daemon_test.go

@@ -1778,7 +1778,7 @@ func (s *DockerDaemonSuite) TestDaemonNoSpaceLeftOnDeviceError(c *check.C) {
 	dockerCmd(c, "run", "--privileged", "--rm", "-v", testDir+":/test:shared", "busybox", "sh", "-c", fmt.Sprintf("mkdir -p /test/test-mount && mount -t ext4 -no loop,rw %v /test/test-mount", loopname))
 	defer mount.Unmount(filepath.Join(testDir, "test-mount"))
 
-	s.d.Start(c, "--graph", filepath.Join(testDir, "test-mount"))
+	s.d.Start(c, "--data-root", filepath.Join(testDir, "test-mount"))
 	defer s.d.Stop(c)
 
 	// pull a repository large enough to fill the mount point

man/dockerd.8.md

@@ -17,6 +17,7 @@ dockerd - Enable daemon mode
 [**--cluster-store-opt**[=*map[]*]]
 [**--config-file**[=*/etc/docker/daemon.json*]]
 [**--containerd**[=*SOCKET-PATH*]]
+[**--data-root**[=*/var/lib/docker*]]
 [**-D**|**--debug**]
 [**--default-gateway**[=*DEFAULT-GATEWAY*]]
 [**--default-gateway-v6**[=*DEFAULT-GATEWAY-V6*]]
@@ -33,7 +34,6 @@ dockerd - Enable daemon mode
 [**--fixed-cidr**[=*FIXED-CIDR*]]
 [**--fixed-cidr-v6**[=*FIXED-CIDR-V6*]]
 [**-G**|**--group**[=*docker*]]
-[**-g**|**--graph**[=*/var/lib/docker*]]
 [**-H**|**--host**[=*[]*]]
 [**--help**]
 [**--icc**[=*true*]]
@@ -152,6 +152,11 @@ $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-ru
 **--containerd**=""
   Path to containerd socket.
 
+**--data-root**=""
+  Path to the directory used to store persisted Docker data such as
+  configuration for resources, swarm cluster state, and filesystem data for
+  images, containers, and local volumes. Default is `/var/lib/docker`.
+
 **-D**, **--debug**=*true*|*false*
   Enable debug mode. Default is false.
 
@@ -204,9 +209,6 @@ $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-ru
   Group to assign the unix socket specified by -H when running in daemon mode.
   use '' (the empty string) to disable setting of a group. Default is `docker`.
 
-**-g**, **--graph**=""
-  Path to use as the root of the Docker runtime. Default is `/var/lib/docker`.
-
 **-H**, **--host**=[*unix:///var/run/docker.sock*]: tcp://[host:port] to bind or
 unix://[/path/to/socket] to use.
   The socket(s) to bind to in daemon mode specified using one or more