20612: Document diagnostics image building / container options.

Arvados-DCO-1.1-Signed-off-by: Tom Clegg <tom@curii.com>

diff --git a/doc/admin/diagnostics.html.textile.liquid b/doc/admin/diagnostics.html.textile.liquid
index ec6a9bf9d5511340ba58a9c4f9db8cbc045fad0d..d5921f8324723ae3f091c1a088248aa448f2d19f 100644 (file)
--- a/doc/admin/diagnostics.html.textile.liquid
+++ b/doc/admin/diagnostics.html.textile.liquid
@@ -45,6 +45,22 @@ The diagnostics output indicates whether its client connection is categorized by
 ERROR     60: checking internal/external client detection (11 ms): expecting internal=true external=false, but found internal=false external=true
 </pre></notextile>
 
+h2(#container-options). Container-running options
+
+By default, the @diagnostics@ command builds a custom Docker image containing a copy of its own binary, and uses that image to run diagnostic checks from inside an Arvados container. This can help detect problems like lack of network connectivity between containers and Arvados cluster services.
+
+The default approach works well if the client host (i.e., the host where you invoke @arvados-client diagnostics@) meets certain conditions:
+* Docker is installed and working, so the diagnostics command can run @docker build@ and @docker save@.
+* Its hardware and kernel are similar to the cluster's compute instances (so the @arvados-client@ binary and the custom-built docker image are compatible with the compute instances).
+* Network bandwidth supports uploading the docker image (about 100 megabytes) in less than a minute.
+
+The following options provide flexibility in case the default approach is not suitable.
+* @-priority=0@ skips the container-running part of the diagnostics suite.
+* @-docker-image="hello-world"@ uses a tiny "hello world" image that is already embedded in the @arvados-client@ binary. This works even if the client host does not have any Docker tools installed, and it minimizes the data transferred during the diagnostics suite. It provides less test coverage than the default option, but it will at least check that it is possible to run a container on the cluster.
+* @-docker-image=X@ (where @X@ is a docker image name or a portable data hash) uses a Docker image that has already been uploaded to your Arvados cluster using @arv keep docker@. In this case the diagnostics tool will run a container with the command @echo {timestamp}@.
+* @-docker-image-from=NAME@ builds a custom docker image on the fly as described above, but using the specified image as a base instead of the default @debian:slim-stable@ image. Note that the build recipe runs commands like @apt-get install [...] libfuse2 ca-certificates@ so only Debian-based base images are supported. For more flexibility, use one of the above @-docker-image=...@ options.
+* @-timeout=2m@ extends the time limit for each HTTP request made by the diagnostics suite, including the process of uploading a custom-built docker image, to 2 minutes (the default HTTP request timeout is 10 seconds, and the default upload time limit is either the HTTP timeout or 1 minute, whichever is longer).
+
 h2. Example output
 
 <notextile><pre>

diff --git a/lib/diagnostics/cmd.go b/lib/diagnostics/cmd.go
index 1e3c42a08b946c3e664e486160b6c1b9f3894a7d..4c9a6e2d3dbfa505a9a97c0b8ae89f25c5ba788f 100644 (file)
--- a/lib/diagnostics/cmd.go
+++ b/lib/diagnostics/cmd.go
@@ -38,7 +38,7 @@ func (Command) RunCommand(prog string, args []string, stdin io.Reader, stdout, s
        f.StringVar(&diag.projectName, "project-name", "scratch area for diagnostics", "`name` of project to find/create in home project and use for temporary/test objects")
        f.StringVar(&diag.logLevel, "log-level", "info", "logging `level` (debug, info, warning, error)")
        f.StringVar(&diag.dockerImage, "docker-image", "", "`image` (tag or portable data hash) to use when running a test container, or \"hello-world\" to use embedded hello-world image (default: build a custom image containing this executable, and run diagnostics inside the container too)")
-       f.StringVar(&diag.dockerImageFrom, "docker-image-from", "debian:stable-slim", "`base` image to use when building a custom image (use a debian-based image similar this host's OS for best results)")
+       f.StringVar(&diag.dockerImageFrom, "docker-image-from", "debian:stable-slim", "`base` image to use when building a custom image (see https://doc.arvados.org/main/admin/diagnostics.html#container-options)")
        f.BoolVar(&diag.checkInternal, "internal-client", false, "check that this host is considered an \"internal\" client")
        f.BoolVar(&diag.checkExternal, "external-client", false, "check that this host is considered an \"external\" client")
        f.BoolVar(&diag.verbose, "v", false, "verbose: include more information in report")