adds config and switches to manage pull-image for create/run commands

cmd/crictl/config.go

@@ -28,20 +28,21 @@ import (
 	"github.com/kubernetes-sigs/cri-tools/pkg/common"
 )
 
-const configDesc = `Get and set crictl options.
-
-The options are as follows:
+var configCommand = &cli.Command{
+	Name:  "config",
+	Usage: "Get and set crictl client configuration options",
+	ArgsUsage: `[<crictl options>]
 
-- runtime-endpoint: Container runtime endpoint
-- image-endpoint: Image endpoint
-- timeout: Timeout of connecting to server
-- debug: Enable debug output
-`
+EXAMPLE:
+   crictl config --set debug=true
 
-var configCommand = &cli.Command{
-	Name:                   "config",
-	Usage:                  configDesc,
-	ArgsUsage:              "[<options>]",
+CRICTL OPTIONS:
+	 runtime-endpoint:	Container runtime endpoint
+	 image-endpoint:	Image endpoint
+	 timeout:	Timeout of connecting to server (default: 2s)
+	 debug:	Enable debug output (default: false)
+	 pull-image-on-create:	Enable pulling image on create requests (default: false)
+	 disable-pull-on-run:	Disable pulling image on run requests (default: false)`,
 	UseShortOptionHandling: true,
 	Flags: []cli.Flag{
 		&cli.StringFlag{
@@ -76,6 +77,10 @@ var configCommand = &cli.Command{
 				fmt.Println(config.Timeout)
 			case "debug":
 				fmt.Println(config.Debug)
+			case "pull-image-on-create":
+				fmt.Println(config.PullImageOnCreate)
+			case "disable-pull-on-run":
+				fmt.Println(config.DisablePullOnRun)
 			default:
 				return errors.Errorf("no configuration option named %s", get)
 			}
@@ -129,6 +134,18 @@ func setValue(key, value string, config *common.Config) error {
 			return errors.Wrapf(err, "parse debug value '%s'", value)
 		}
 		config.Debug = debug
+	case "pull-image-on-create":
+		pi, err := strconv.ParseBool(value)
+		if err != nil {
+			return errors.Wrapf(err, "parse pull-image-on-create value '%s'", value)
+		}
+		config.PullImageOnCreate = pi
+	case "disable-pull-on-run":
+		pi, err := strconv.ParseBool(value)
+		if err != nil {
+			return errors.Wrapf(err, "parse disable-pull-on-run value '%s'", value)
+		}
+		config.DisablePullOnRun = pi
 	default:
 		return errors.Errorf("no configuration option named %s", key)
 	}

cmd/crictl/container.go

@@ -30,6 +30,7 @@ import (
 	"github.com/sirupsen/logrus"
 	"github.com/urfave/cli/v2"
 	"golang.org/x/net/context"
+	"google.golang.org/grpc"
 	pb "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"
 )
 
@@ -61,8 +62,8 @@ type runOptions struct {
 }
 
 type pullOptions struct {
-	// do not pull the image on container creation
-	dontPull bool
+	// pull the image on container creation; overrides default
+	withPull bool
 
 	// creds is string in the format `USERNAME[:PASSWORD]` for accessing the
 	// registry during image pull
@@ -73,10 +74,35 @@ type pullOptions struct {
 	auth string
 }
 
-var pullFlags = []cli.Flag{
+var createPullFlags = []cli.Flag{
 	&cli.BoolFlag{
 		Name:  "no-pull",
-		Usage: "Do not pull the image on container creation",
+		Usage: "Do not pull the image on container creation (overrides pull-image-on-create=true in config)",
+	},
+	&cli.BoolFlag{
+		Name:  "with-pull",
+		Usage: "Pull the image on container creation (overrides pull-image-on-create=false in config)",
+	},
+	&cli.StringFlag{
+		Name:  "creds",
+		Value: "",
+		Usage: "Use `USERNAME[:PASSWORD]` for accessing the registry",
+	},
+	&cli.StringFlag{
+		Name:  "auth",
+		Value: "",
+		Usage: "Use `AUTH_STRING` for accessing the registry. AUTH_STRING is a base64 encoded 'USERNAME[:PASSWORD]'",
+	},
+}
+
+var runPullFlags = []cli.Flag{
+	&cli.BoolFlag{
+		Name:  "no-pull",
+		Usage: "Do not pull the image (overrides disable-pull-on-run=false in config)",
+	},
+	&cli.BoolFlag{
+		Name:  "with-pull",
+		Usage: "Pull the image (overrides disable-pull-on-run=true in config)",
 	},
 	&cli.StringFlag{
 		Name:  "creds",
@@ -94,32 +120,42 @@ var createContainerCommand = &cli.Command{
 	Name:      "create",
 	Usage:     "Create a new container",
 	ArgsUsage: "POD container-config.[json|yaml] pod-config.[json|yaml]",
-	Flags:     pullFlags,
+	Flags:     createPullFlags,
 
 	Action: func(context *cli.Context) error {
 		if context.Args().Len() != 3 {
 			return cli.ShowSubcommandHelp(context)
 		}
+		if context.Bool("no-pull") == true && context.Bool("with-pull") == true {
+			return errors.New("confict: no-pull and with-pull are both set")
+		}
 
 		runtimeClient, runtimeConn, err := getRuntimeClient(context)
 		if err != nil {
 			return err
 		}
 		defer closeConnection(context, runtimeConn)
 
-		imageClient, imageConn, err := getImageClient(context)
-		if err != nil {
-			return err
+		withPull := (!context.Bool("no-pull") && PullImageOnCreate) || context.Bool("with-pull")
+
+		var imageClient pb.ImageServiceClient
+		var imageConn *grpc.ClientConn
+
+		if withPull {
+			imageClient, imageConn, err = getImageClient(context)
+			if err != nil {
+				return err
+			}
+			defer closeConnection(context, imageConn)
 		}
-		defer closeConnection(context, imageConn)
 
 		opts := createOptions{
 			podID: context.Args().Get(0),
 			runOptions: &runOptions{
 				configPath: context.Args().Get(1),
 				podConfig:  context.Args().Get(2),
 				pullOptions: &pullOptions{
-					dontPull: context.Bool("no-pull"),
+					withPull: withPull,
 					creds:    context.String("creds"),
 					auth:     context.String("auth"),
 				},
@@ -490,7 +526,7 @@ var runContainerCommand = &cli.Command{
 	Name:      "run",
 	Usage:     "Run a new container inside a sandbox",
 	ArgsUsage: "container-config.[json|yaml] pod-config.[json|yaml]",
-	Flags: append(pullFlags, &cli.StringFlag{
+	Flags: append(runPullFlags, &cli.StringFlag{
 		Name:    "runtime",
 		Aliases: []string{"r"},
 		Usage:   "Runtime handler to use. Available options are defined by the container runtime.",
@@ -500,24 +536,36 @@ var runContainerCommand = &cli.Command{
 		if context.Args().Len() != 2 {
 			return cli.ShowSubcommandHelp(context)
 		}
+		if context.Bool("no-pull") == true && context.Bool("with-pull") == true {
+			return errors.New("confict: no-pull and with-pull are both set")
+		}
 
 		runtimeClient, runtimeConn, err := getRuntimeClient(context)
 		if err != nil {
 			return err
 		}
 		defer closeConnection(context, runtimeConn)
 
-		imageClient, imageConn, err := getImageClient(context)
-		if err != nil {
-			return err
+		withPull := (!DisablePullOnRun && !context.Bool("no-pull")) || context.Bool("with-pull")
+
+		var (
+			imageClient pb.ImageServiceClient
+			imageConn   *grpc.ClientConn
+		)
+
+		if withPull {
+			imageClient, imageConn, err = getImageClient(context)
+			if err != nil {
+				return err
+			}
+			defer closeConnection(context, imageConn)
 		}
-		defer closeConnection(context, imageConn)
 
 		opts := runOptions{
 			configPath: context.Args().Get(0),
 			podConfig:  context.Args().Get(1),
 			pullOptions: &pullOptions{
-				dontPull: context.Bool("no-pull"),
+				withPull: withPull,
 				creds:    context.String("creds"),
 				auth:     context.String("auth"),
 			},
@@ -583,7 +631,12 @@ func CreateContainer(
 		}
 	}
 
-	if !opts.dontPull {
+	// When there is a with-pull request or the image default mode is to
+	// pull-image-on-create(true) and no-pull was not set we pull the image when
+	// they ask for a create as a helper on the cli to reduce extra steps. As a
+	// reminder if the image is already in cache only the manifest will be pulled
+	// down to verify.
+	if opts.withPull {
 		auth, err := getAuth(opts.creds, opts.auth)
 		if err != nil {
 			return "", err

cmd/crictl/main.go

@@ -53,6 +53,10 @@ var (
 	Timeout time.Duration
 	// Debug enable debug output
 	Debug bool
+	// PullImageOnCreate enables pulling image on create requests
+	PullImageOnCreate bool
+	// DisablePullOnRun disable pulling image on run requests
+	DisablePullOnRun bool
 )
 
 func getRuntimeClientConnection(context *cli.Context) (*grpc.ClientConn, error) {
@@ -241,6 +245,7 @@ func main() {
 				Timeout = context.Duration("timeout")
 			}
 			Debug = context.Bool("debug")
+			DisablePullOnRun = false
 		} else {
 			// Command line flags overrides config file.
 			if context.IsSet("runtime-endpoint") {
@@ -273,6 +278,8 @@ func main() {
 			} else {
 				Debug = config.Debug
 			}
+			PullImageOnCreate = config.PullImageOnCreate
+			DisablePullOnRun = config.DisablePullOnRun
 		}
 
 		if Debug {

docs/crictl.md

@@ -29,10 +29,10 @@ rm -f crictl-$VERSION-linux-amd64.tar.gz
 ## Usage
 
 ```sh
-crictl SUBCOMMAND [FLAGS]
+crictl  [global options] command [command options] [arguments...]
 ```
 
-Subcommands includes:
+COMMANDS:
 
 - `attach`:             Attach to a running container
 - `create`:             Create a new container
@@ -58,20 +58,20 @@ Subcommands includes:
 - `stop`:               Stop one or more running containers
 - `stopp`:              Stop one or more running pods
 - `update`:             Update one or more running containers
-- `config`:             Get and set crictl options
+- `config`:             Get and set crictl client configuration options
 - `stats`:              List container(s) resource usage statistics
 - `completion`:         Output bash shell completion code
 - `help, h`:            Shows a list of commands or help for one command
 
 crictl by default connects to Unix: `unix:///var/run/dockershim.sock` or Windows: `tcp://localhost:3735`.  For other runtimes, use:
 
 * [containerd](https://containerd.io): `unix:///run/containerd/containerd.sock`
-* [cri-o](https://cri-o.io): `unix:///var/run/crio/crio.sock` 
+* [cri-o](https://cri-o.io): `unix:///var/run/crio/crio.sock`
 * [frakti](https://github.com/kubernetes/frakti): `unix:///var/run/frakti.sock`
 
 The endpoint can be set in three ways:
 
-- By setting flags `--runtime-endpoint` (`-r`) and `--image-endpoint` (`-i`)
+- By setting global option flags `--runtime-endpoint` (`-r`) and `--image-endpoint` (`-i`)
 - By setting environment variables `CONTAINER_RUNTIME_ENDPOINT` and `IMAGE_SERVICE_ENDPOINT`
 - By setting the endpoint in the config file `--config=/etc/crictl.yaml`
 
@@ -93,6 +93,7 @@ runtime-endpoint: unix:///var/run/dockershim.sock
 image-endpoint: unix:///var/run/dockershim.sock
 timeout: 2
 debug: true
+pull-image-on-create: false
 ```
 Windows:
 ```cmd
@@ -101,6 +102,7 @@ runtime-endpoint: tcp://localhost:3735
 image-endpoint: tcp://localhost:3735
 timeout: 2
 debug: true
+pull-image-on-create: false
 ```
 
 ### Connection troubleshooting
@@ -121,7 +123,42 @@ option for no timeout value set and the smallest supported timeout is `1s`
 - `--debug`, `-D`: Enable debug output
 - `--help`, `-h`: show help
 - `--version`, `-v`: print the version information of crictl
-- `--config`, `-c`: Config file in yaml format. Overrided by flags or environment variables
+- `--config`, `-c`: Location of the client config file. If not specified and the default does not exist, the program's directory is searched as well (default: "/etc/crictl.yaml") [$CRI_CONFIG_FILE]
+
+## Client Configuration Options
+Use the crictl config command to get and set the crictl client configuration
+options.
+```
+USAGE:
+   crictl config [command options] [<crictl options>]
+```
+For example `crictl config --set debug=true` will enable debug mode when giving subsequent crictl commands.
+
+CRICTL OPTIONS:
+```
+   runtime-endpoint:       Container runtime endpoint
+   image-endpoint:         Image endpoint
+   timeout:                Timeout of connecting to server (default: 2s)
+   debug:                  Enable debug output (default: false)
+   pull-image-on-create:   Enable pulling image on create requests (default: false)
+   disable-pull-on-run:    Disable pulling image on run requests (default: false)
+
+```
+OPTIONS:
+```
+   --get value  show the option value
+   --set value  set option (can specify multiple or separate values with commas: opt1=val1,opt2=val2)
+   --help, -h   show help (default: false)
+```
+> When enabled `pull-image-on-create` modifies the create container command to first pull the container's image.
+This feature is used as a helper to make creating containers easier and faster.
+Some users of `crictl` may desire to not pull the image necessary to create the container.
+For example, the image may have already been pulled or otherwise loaded into the container runtime, or the user may be running without a network. For this reason the default for `pull-image-on-create` is false.
+
+> By default the run command first pulls the container image, and `disable-pull-on-run` is false.
+Some users of `crictl` may desire to set `disable-pull-on-run` to true to not pull the image by default when using the run command.
+
+> To override these default pull configuration settings, `--no-pull` and `--with-pull` options are provided for the create and run commands.
 
 ## Examples
 

pkg/common/config.go

@@ -24,7 +24,7 @@ import (
 	"github.com/pkg/errors"
 )
 
-// ServerConfiguration is the config for connecting to a CRI server
+// ServerConfiguration is the config for connecting to and using a CRI server
 type ServerConfiguration struct {
 	// RuntimeEndpoint is CRI server runtime endpoint
 	RuntimeEndpoint string
@@ -34,6 +34,10 @@ type ServerConfiguration struct {
 	Timeout time.Duration
 	// Debug enable debug output
 	Debug bool
+	// PullImageOnCreate enables also pulling an image for create requests
+	PullImageOnCreate bool
+	// DisablePullOnRun disables pulling an image for run requests
+	DisablePullOnRun bool
 }
 
 // GetServerConfigFromFile returns the CRI server configuration from file
@@ -63,5 +67,7 @@ func GetServerConfigFromFile(configFileName, currentDir string) (*ServerConfigur
 	serverConfig.ImageEndpoint = config.ImageEndpoint
 	serverConfig.Timeout = time.Duration(config.Timeout) * time.Second
 	serverConfig.Debug = config.Debug
+	serverConfig.PullImageOnCreate = config.PullImageOnCreate
+	serverConfig.DisablePullOnRun = config.DisablePullOnRun
 	return &serverConfig, nil
 }