Merge pull request #173 from srm09/docs/vbeta-0.3.0

Adds docs for vbeta-0.3.0 features

README.md

@@ -1,4 +1,5 @@
 ![](https://github.com/vmware-tanzu/crash-diagnostics/workflows/Crash%20Diagnostics%20Build/badge.svg)
+[![Go Report Card](https://goreportcard.com/badge/github.com/vmware-tanzu/crash-diagnostics)](https://goreportcard.com/report/github.com/vmware-tanzu/crash-diagnostics)
 
 # Crashd - Crash Diagnostics
 
@@ -121,10 +122,10 @@ kube_capture(what="logs", namespaces=[os.getenv("KUBE_DEFAULT_NS")])
 ```
 
 ### Command-line arguments
-Scripts can also access command-line arguments passed as key/value pairs using the `--args` flag. For instance, when the following command is used to start a script:
+Scripts can also access command-line arguments passed as key/value pairs using the `--args` or `--args-file` flags. For instance, when the following command is used to start a script:
 
-```
-  crashd run --args="kube_ns=kube-system, username=$(whoami)" diagnostics.crsh
+```bash
+$ crashd run --args="kube_ns=kube-system, username=$(whoami)" diagnostics.crsh
 ```
 
 Values from `--args` can be accessed as shown below:
@@ -216,7 +217,7 @@ The previous snippet interact with management cluster machines. The provider can
 # enumerates workload cluster nodes
 nodes = resources(
     provider=capv_provider(
-        workload_cluster=args.cluster_name
+        workload_cluster=args.cluster_name,
         ssh_config=ssh_config(username="capv", private_key_path=args.private_key),
         kube_config=kube_config(path=args.mc_config)
     )

docs/README.md

@@ -102,11 +102,12 @@ This function declares script-wide configuration information that is used to con
 #### Parameters
 
 | Param | Description | Required |
-| -------- | -------- | -------- |
-| `workdir`  | the working directory used by some functions to store files.| Yes |
-| `uid`| User ID used to run local commands|No, defaults to current ID|
-| `gid`| Group ID used to run local commands|No, defaults to current ID|
+|:--------|:--------|:--------|
+| `workdir` | the working directory used by some functions to store files.| Yes |
+| `uid` | User ID used to run local commands|No, defaults to current ID|
+| `gid` | Group ID used to run local commands|No, defaults to current ID|
 | `default_shell` |The default shell to use to execute commands |No, defaults to no shell|
+| `use_ssh_agent` | boolean indicator to start a ssh-agent instance or not |No, defaults to `False`|
 
 
 #### Output
@@ -125,6 +126,18 @@ crashd_config(
     workdir = "{}/crashd".format(os.home)
 )
 ```
+
+#### Internal Crashd ssh-agent
+If the crashd operator does not want to rely on the default ssh-agent process, the `crashd_config()` provides the option to start a new instance of the ssh-agent which will be used for all corresponding ssh/scp connections in the script.
+```python
+# this will force crashd to use a new ssh-agent instance alive for
+# the scope of script execution
+crashd_config(workdir="/tmp/foo", use_ssh_agent=True)
+```
+
+While leveraging the internal crashd agent, any **passphrase protected keys** will pause the script execution and prompt the script operator to enter the passphrase.
+
+
 ### `kube_config()`
 This configuration function declares and stores configuration needed to connect to a Kubernetes API server.
 
@@ -181,6 +194,8 @@ ssh=ssh_config(
 )
 ```
 
+**NOTE**: For passphrase protected keys, add the key to the default ssh-agent prior to running the diagnostics script, to ensure non-interactive execution of the script.
+
 ## Provider Functions
 A provider function implements the code to cofigure and to enumerate compute resources for a given infrastructure. The result of the provider functions are used by the `resources` function to generate/enumerate the compute resources needed.
 
@@ -732,4 +747,24 @@ ssh=ssh_config(
 )
 
 kube_config(path=args.kube_cfg)
+```
+
+### Arguments file
+In the case, when the script requires mutliple values to be provided by the user, the `--args` flag becomes difficult to use. The `run` command exposes the `--args-file` flag which takes a file path as input.
+
+The supplied args file should follow the format:
+* A line contains a single key-value pair separated by `=` sign (eg: foo=bar|foo =bar|foo= bar|foo = bar)
+* A line can either contain a key-value pair in the above format or a comment statement starting with #
+* Blank lines are allowed
+
+Any line not adhering to the said format will result in a warning message to appear on the screen, and would be ignored.
+
+```bash
+$ cat /tmp/script.args
+foo=bar
+bloop blah
+
+# this will result in a warning message with foo=bar as the only pair pairs to be passed to the .crsh file
+$ crash run diagnsotics.crsh --args-file /tmp/script.args
+WARN[0000] unknown entry in args file: blooop blah
 ```

ssh/scp_test.go

@@ -44,7 +44,7 @@ func TestCopy(t *testing.T) {
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
 			defer func() {
-				for file, _ := range test.remoteFiles {
+				for file := range test.remoteFiles {
 					RemoveTestSSHFile(t, test.sshArgs, file)
 				}
 			}()

starlark/copy_from_test.go

@@ -210,7 +210,7 @@ func testCopyFuncForHostResources(t *testing.T, port, privateKey, username strin
 				ssh.MakeTestSSHFile(t, sshArgs, file, content)
 			}
 			defer func() {
-				for file, _ := range test.remoteFiles {
+				for file := range test.remoteFiles {
 					ssh.RemoveTestSSHFile(t, sshArgs, file)
 				}
 			}()
@@ -360,7 +360,7 @@ result = cp(hosts)`, username, port, privateKey),
 			ssh.MakeTestSSHFile(t, sshArgs, file, content)
 		}
 		defer func() {
-			for file, _ := range test.remoteFiles {
+			for file := range test.remoteFiles {
 				ssh.RemoveTestSSHFile(t, sshArgs, file)
 			}
 		}()

starlark/doc.go

@@ -0,0 +1,5 @@
+// Copyright (c) 2019 VMware, Inc. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package starlark provides starlark builtins to be used in the diagnostics script.
+package starlark

starlark/govalue_test.go

@@ -77,7 +77,7 @@ func TestGoValue_ToStringDict(t *testing.T) {
 		},
 		{
 			name:  "map[string][]string",
-			goVal: NewGoValue(map[string][]string{"key0": []string{"hello", "goodbye"}, "key1": []string{"hi", "bye"}}),
+			goVal: NewGoValue(map[string][]string{"key0": {"hello", "goodbye"}, "key1": {"hi", "bye"}}),
 			eval: func(t *testing.T, goval *GoValue) {
 				actual := goval.Value().(map[string][]string)
 				starVal, err := goval.ToStringDict()
@@ -155,7 +155,7 @@ func TestGoValue_ToDict(t *testing.T) {
 		},
 		{
 			name:  "map[bool][]string",
-			goVal: NewGoValue(map[bool][]string{true: []string{"hello", "goodbye"}, false: []string{"hi", "bye"}}),
+			goVal: NewGoValue(map[bool][]string{true: {"hello", "goodbye"}, false: {"hi", "bye"}}),
 			eval: func(t *testing.T, goval *GoValue) {
 				actual := goval.Value().(map[bool][]string)
 				dict, err := goval.ToDict()