docs: fix the documentation for credentials (#398)

cmd/duffle/credentials.go

@@ -8,6 +8,32 @@ import (
 
 const credentialDesc = `
 Manages credential sets.
+
+A credential set (credentialset) is a collection of credentialing information. It assigns a
+name to place where a credential can be found. Credential sets are used to inject credentials
+into an invocation image during operations such as 'duffle install' or 'duffle upgrade'.
+
+Credential sets work by associating a local named credential with a credential requested by
+a CNAB bundle. For example, if a CNAB bundle requires a credential named 'user_token',
+a credential set can declare that 'user_token' is  fulfilled by loading the value
+from the environment variable 'USER_TOKEN'.
+
+Various command, such as 'duffle install', provide the '--credentials'/'-c' flag for pointing
+to a credential set.
+
+Duffle provides local credential set storage in the Duffle configuration directory. On a
+UNIX-like system, these are stored in '$HOME/.duffle/credentials'. But credential sets are
+just text files that map credential names to local sources.
+
+A credential set can retrieve actual credentials from the following four sources:
+
+	- a hard-coded value
+	- an environment variable in the local environment
+	- a file on the local file system
+	- a command executed on the local system
+
+Note that in all of these cases, the local system (the system running Duffle) is used as
+the source of the credential.
 `
 
 func newCredentialsCmd(w io.Writer) *cobra.Command {

cmd/duffle/install.go

@@ -150,7 +150,7 @@ Verifying and --insecure:
 	flags.StringVarP(&installDriver, "driver", "d", "docker", "Specify a driver name")
 	flags.StringVarP(&valuesFile, "parameters", "p", "", "Specify file containing parameters. Formats: toml, MORE SOON")
 	flags.StringVarP(&bundleFile, "file", "f", "", "Bundle file to install")
-	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify a set of credentials to use inside the CNAB bundle")
+	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify credentials to use inside the CNAB bundle. This can be a credentialset name or a path to a file.")
 	flags.StringArrayVarP(&setParams, "set", "s", []string{}, "Set individual parameters as NAME=VALUE pairs")
 	flags.StringArrayVarP(&setFiles, "set-file", "i", []string{}, "Set individual parameters from file content as NAME=SOURCE-PATH pairs")
 	return cmd

cmd/duffle/status.go

@@ -74,7 +74,7 @@ reason, it may need the same credentials used to install.
 		},
 	}
 	cmd.Flags().StringVarP(&statusDriver, "driver", "d", "docker", "Specify a driver name")
-	cmd.Flags().StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify a set of credentials to use inside the CNAB bundle")
+	cmd.Flags().StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify credentials to use inside the CNAB bundle. This can be a credentialset name or a path to a file.")
 
 	return cmd
 }

cmd/duffle/uninstall.go

@@ -57,7 +57,7 @@ func newUninstallCmd() *cobra.Command {
 
 	flags := cmd.Flags()
 	flags.StringVarP(&uninstallDriver, "driver", "d", "docker", "Specify a driver name")
-	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify a set of credentials to use inside the CNAB bundle")
+	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify credentials to use inside the CNAB bundle. This can be a credentialset name or a path to a file.")
 	flags.StringVarP(&bundleFile, "file", "f", "", "bundle file to install")
 	flags.StringVarP(&uc.valuesFile, "parameters", "p", "", "Specify file containing parameters. Formats: toml, MORE SOON")
 	flags.StringArrayVarP(&uc.setParams, "set", "s", []string{}, "set individual parameters as NAME=VALUE pairs")

cmd/duffle/upgrade.go

@@ -66,7 +66,7 @@ func newUpgradeCmd() *cobra.Command {
 	flags := cmd.Flags()
 	flags.StringVarP(&bundleFile, "file", "f", "", "Set the bundle file to use for upgrading")
 	flags.StringVarP(&upgradeDriver, "driver", "d", "docker", "Specify a driver name")
-	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify a set of credentials to use inside the CNAB bundle")
+	flags.StringArrayVarP(&credentialsFiles, "credentials", "c", []string{}, "Specify credentials to use inside the CNAB bundle. This can be a credentialset name or a path to a file.")
 	flags.StringVarP(&uc.valuesFile, "parameters", "p", "", "Specify file containing parameters. Formats: toml, MORE SOON")
 	flags.StringArrayVarP(&uc.setParams, "set", "s", []string{}, "Set individual parameters as NAME=VALUE pairs")
 	flags.BoolVarP(&uc.insecure, "insecure", "k", false, "Do not verify the bundle (INSECURE)")