From 2c63d357df9858d9a094e2f371d08251458f0983 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 12:24:30 -0400 Subject: [PATCH 1/9] add more docs for the 'agent' command --- src/cmd/agent.go | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/cmd/agent.go b/src/cmd/agent.go index 2a505d5e18..b5adae4daf 100644 --- a/src/cmd/agent.go +++ b/src/cmd/agent.go @@ -8,6 +8,9 @@ import ( var agentCmd = &cobra.Command{ Use: "agent", Short: "Runs the zarf agent", + Long: "NOTE: This command is a hidden command and generally shouldn't be run by a human.\n" + + "This command starts up a http webhook that Zarf deployments use to mutate pods to conform " + + "with the Zarf container registry and Gitea server URLs.", // this command should not be advertised on the cli as it has no value outside the k8s env Hidden: true, Run: func(cmd *cobra.Command, args []string) { From d93b0cbfa04358c7e83b281396cdf8067f5018ea Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 12:25:31 -0400 Subject: [PATCH 2/9] add more docs for the 'connect' command --- src/cmd/connect.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/cmd/connect.go b/src/cmd/connect.go index ef3f0e421e..e677a1e449 100644 --- a/src/cmd/connect.go +++ b/src/cmd/connect.go @@ -17,6 +17,16 @@ var ( Use: "connect ", Aliases: []string{"c"}, Short: "Access services or pods deployed in the cluster.", + Long: "Uses a k8s port-forward to connect to resources within the cluster referenced by your kube-context.\n" + + "Three default options for this command are . These will connect to the Zarf created resources " + + "(assuming they were selected when performing the `zarf init` command).\n\n" + + "Packages can provide service manifests that define their own shortcut connection options. These options will be " + + "printed to the terminal when the package finishes deploying.\n If you don't remember what connection shortcuts your deployed " + + "package offers, you can search your cluster for services that have the 'zarf.dev/connect-name' label. The value of that label is " + + "the name you will pass into the 'zarf connect' command. \n\n" + + "Even if the packages you deploy don't define their own shortcut connection options, you can use the command flags " + + "to connect into specific resources. You can read the command flag descriptions below to get a better idea how to connect " + + "to whatever resource you are trying to connect to.", Run: func(cmd *cobra.Command, args []string) { var target string if len(args) > 0 { From 7135519b73c18287dca8efba0fbaf0f9f376def7 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 12:29:25 -0400 Subject: [PATCH 3/9] add more docs for the 'destroy' command --- src/cmd/destroy.go | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/cmd/destroy.go b/src/cmd/destroy.go index a68e427265..71ab549b50 100644 --- a/src/cmd/destroy.go +++ b/src/cmd/destroy.go @@ -23,6 +23,16 @@ var destroyCmd = &cobra.Command{ Use: "destroy", Aliases: []string{"d"}, Short: "Tear it all down, we'll miss you Zarf...", + Long: "Tear down Zarf.\n\n" + + "Deletes everything in the 'zarf' namespace within your connected k8s cluster.\n\n" + + "If Zarf deployed your k8s cluster, this command will also tear your cluster down by" + + "searching through /opt/zarf for any scripts that start with 'zarf-clean-' and executing them. " + + "Since this is a cleanup operation, Zarf will not stop the teardown if one of the scripts produce " + + "an error.\n\n" + + "If Zarf did not deploy your k8s cluster, this command will delete the Zarf namespace, delete secrets " + + "and labels that only Zarf cares about, and optionally uninstall components that Zarf deployed onto " + + "the cluster. Since this is a cleanup operation, Zarf will not stop the uninstalls if one of the " + + "resources produce an error while being deleted.", Run: func(cmd *cobra.Command, args []string) { // NOTE: If 'zarf init' failed to deploy the k3s component (or if we're looking at the wrong kubeconfig) // there will be no zarf-state to load and the struct will be empty. In these cases, if we can find @@ -41,7 +51,7 @@ var destroyCmd = &cobra.Command{ // Run all the scripts! pattern := regexp.MustCompile(`(?mi)zarf-clean-.+\.sh$`) scripts := utils.RecursiveFileList(config.ZarfCleanupScriptsPath, pattern) - // Iterate over al matching zarf-clean scripts and exec them + // Iterate over all matching zarf-clean scripts and exec them for _, script := range scripts { // Run the matched script _, _, err := utils.ExecCommandWithContext(context.TODO(), true, script) @@ -50,6 +60,8 @@ var destroyCmd = &cobra.Command{ // Don't remove scripts we can't execute so the user can try to manually run continue + } else if err != nil { + message.Debugf("Received error when trying to execute the script (%v): %v", script, err) } // Try to remove the script, but ignore any errors @@ -75,7 +87,7 @@ var destroyCmd = &cobra.Command{ func init() { rootCmd.AddCommand(destroyCmd) - destroyCmd.Flags().BoolVar(&confirmDestroy, "confirm", false, "Confirm the destroy action") + destroyCmd.Flags().BoolVar(&confirmDestroy, "confirm", false, "REQUIRED. Confirm the destroy action to prevent accidental deletions") destroyCmd.Flags().BoolVar(&removeComponents, "remove-components", false, "Also remove any installed components outside the zarf namespace") _ = destroyCmd.MarkFlagRequired("confirm") } From 01ef90229d775b88b9d225bc279cad1fcdfb7332 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 13:01:58 -0400 Subject: [PATCH 4/9] add more docs for the 'init' command --- src/cmd/initialize.go | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/cmd/initialize.go b/src/cmd/initialize.go index 702bfcb5b3..eaed5a50e5 100644 --- a/src/cmd/initialize.go +++ b/src/cmd/initialize.go @@ -18,8 +18,14 @@ import ( var initCmd = &cobra.Command{ Use: "init", Aliases: []string{"i"}, - Short: "Deploys the gitops service or appliance cluster on a clean linux box", - Long: "Flags are only required if running via automation, otherwise the init command will prompt you for your configuration choices", + Short: "Prepares a k8s cluster for the deployment of Zarf packages", + Long: "Uses a local 'zarf-init' package found either in the directory you executed " + + "the command from or the directory that the Zarf binaries exists. " + + "Injects a docker registry as well as other optional useful things (such as a git server " + + "and a logging stack) into a k8s cluster under the 'zarf' namespace " + + "to support future application deployments. \n" + + "If you do not have a k8s cluster already configured, this command will give you " + + "the ability to install a cluster locally.\n", Run: func(cmd *cobra.Command, args []string) { zarfLogo := message.GetLogo() _, _ = fmt.Fprintln(os.Stderr, zarfLogo) @@ -46,8 +52,7 @@ var initCmd = &cobra.Command{ func init() { rootCmd.AddCommand(initCmd) initCmd.Flags().BoolVar(&config.DeployOptions.Confirm, "confirm", false, "Confirm the install without prompting") - initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to install. Adding this flag will skip the init prompts for which components to install") - + initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to instal.") initCmd.Flags().StringVar(&config.DeployOptions.StorageClass, "storage-class", "", "Describe the StorageClass to be used") initCmd.Flags().StringVar(&config.DeployOptions.Secret, "secret", "", "Root secret value that is used to 'seed' other secrets") initCmd.Flags().StringVar(&config.DeployOptions.NodePort, "nodeport", "", "Nodeport to access the Zarf container registry. Between [30000-32767]") From ae187ea1a429b76579460a01bc22267f9ec67002 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 13:12:22 -0400 Subject: [PATCH 5/9] add more docs for the 'package' command --- src/cmd/package.go | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/cmd/package.go b/src/cmd/package.go index 1af1d75843..acafd56cc7 100644 --- a/src/cmd/package.go +++ b/src/cmd/package.go @@ -2,10 +2,11 @@ package cmd import ( "fmt" - "github.com/defenseunicorns/zarf/src/internal/message" "path/filepath" "regexp" + "github.com/defenseunicorns/zarf/src/internal/message" + "github.com/AlecAivazis/survey/v2" "github.com/defenseunicorns/zarf/src/config" "github.com/defenseunicorns/zarf/src/internal/packager" @@ -26,6 +27,9 @@ var packageCreateCmd = &cobra.Command{ Use: "create", Aliases: []string{"c"}, Short: "Create an update package to push to the gitops server (runs online)", + Long: "Builds a tarball of resources and dependencies defined by the 'zarf.yaml' located in the working directory.\n" + + "Private registries and repositories are accessed via credentials in your local '~/.docker/config.json' " + + "and '~/.git-credentials'.\n", Run: func(cmd *cobra.Command, args []string) { if cmd.Flag("zarf-cache").Changed && cachePathClean(zarfImageCache) { config.SetImageCachePath(zarfImageCache) @@ -38,6 +42,7 @@ var packageDeployCmd = &cobra.Command{ Use: "deploy [PACKAGE]", Aliases: []string{"d"}, Short: "Deploys an update package from a local file or URL (runs offline)", + Long: "Uses current kubecontext to deploy the packaged tarball onto a k8s cluster.", Args: cobra.MaximumNArgs(1), Run: func(cmd *cobra.Command, args []string) { var done func() @@ -51,8 +56,12 @@ var packageDeployCmd = &cobra.Command{ var packageInspectCmd = &cobra.Command{ Use: "inspect [PACKAGE]", Aliases: []string{"i"}, - Short: "lists the payload of an update package file (runs offline)", - Args: cobra.MaximumNArgs(1), + Short: "Lists the payload of a compiled package file (runs offline)", + Long: "Lists the payload of a compiled package file (runs offline)\n" + + "Unpacks the package tarball into a temp directory and displays the " + + "contents of the zarf.yaml package definition as well as the version " + + "of the Zarf CLI that was used to build the package.", + Args: cobra.MaximumNArgs(1), Run: func(cmd *cobra.Command, args []string) { packageName := choosePackage(args) packager.Inspect(packageName) From 101e7d3e82281ceedc0d01973233a42f5cf82f90 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 13:20:08 -0400 Subject: [PATCH 6/9] add more docs for the 'prepare' command --- src/cmd/prepare.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/cmd/prepare.go b/src/cmd/prepare.go index 6696311067..a8e75459f4 100644 --- a/src/cmd/prepare.go +++ b/src/cmd/prepare.go @@ -72,7 +72,8 @@ var prepareComputeFileSha256sum = &cobra.Command{ var prepareFindImages = &cobra.Command{ Use: "find-images", Aliases: []string{"prep"}, - Short: "evaluates components in a zarf file to identify images specified in their helm charts and manifests", + Short: "Evaluates components in a zarf file to identify images specified in their helm charts and manifests.\n" + + "Requires the `--repo-chart-path` flag to be provided.", Run: func(cmd *cobra.Command, args []string) { packager.FindImages(repoHelmChartPath) }, From 2e6ac45d076e47d8677e22b241b7113b34fecde8 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 13:30:53 -0400 Subject: [PATCH 7/9] add more docs for the 'tools' command --- src/cmd/tools.go | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/cmd/tools.go b/src/cmd/tools.go index 0ff642f7ef..0aa3a13315 100644 --- a/src/cmd/tools.go +++ b/src/cmd/tools.go @@ -30,7 +30,7 @@ var toolsCmd = &cobra.Command{ var archiverCmd = &cobra.Command{ Use: "archiver", Aliases: []string{"a"}, - Short: "Compress/Decompress tools", + Short: "Compress/Decompress tools for Zarf packages", } var archiverCompressCmd = &cobra.Command{ @@ -50,7 +50,7 @@ var archiverCompressCmd = &cobra.Command{ var archiverDecompressCmd = &cobra.Command{ Use: "decompress [ARCHIVE] [DESTINATION]", Aliases: []string{"d"}, - Short: "Decompress an archive to a specified location.", + Short: "Decompress an archive (package) to a specified location.", Args: cobra.ExactArgs(2), Run: func(cmd *cobra.Command, args []string) { sourceArchive, destinationPath := args[0], args[1] @@ -112,6 +112,9 @@ var k9sCmd = &cobra.Command{ var createReadOnlyGiteaUser = &cobra.Command{ Use: "create-read-only-gitea-user", Hidden: true, + Short: "Creates a read-only user in Gitea", + Long: "Creates a read-only user in Gitea by using the Gitea API. " + + "This is called internally by the supported Gitea package component.", Run: func(cmd *cobra.Command, args []string) { // Load the state so we can get the credentials for the admin git user state := k8s.LoadZarfState() @@ -127,6 +130,7 @@ var createReadOnlyGiteaUser = &cobra.Command{ var generateCLIDocs = &cobra.Command{ Use: "generate-cli-docs", + Short: "Creates auto-generated markdown of all the commands for the CLI", Hidden: true, Run: func(cmd *cobra.Command, args []string) { utils.CreateDirectory("clidocs", 0700) From 7175e1814774bd6dcd92074b585e26c22a2a1bdf Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Mon, 6 Jun 2022 13:33:40 -0400 Subject: [PATCH 8/9] add more docs for the 'version' command --- src/cmd/version.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/cmd/version.go b/src/cmd/version.go index cbe6e10352..4cfda7ad5c 100644 --- a/src/cmd/version.go +++ b/src/cmd/version.go @@ -10,7 +10,8 @@ import ( var versionCmd = &cobra.Command{ Use: "version", Aliases: []string{"v"}, - Short: "Displays the version the zarf binary was built from", + Short: "Displays the version of the Zarf binary", + Long: "Displays the version of the Zarf release that the Zarf binary was built from.", Run: func(cmd *cobra.Command, args []string) { fmt.Println(config.CLIVersion) }, From 0dba6a8c8eb03e54f20cf99863ad4bd33ead3400 Mon Sep 17 00:00:00 2001 From: Jon Perry Date: Wed, 8 Jun 2022 11:47:34 -0400 Subject: [PATCH 9/9] improve initialize and prepare help messages --- src/cmd/initialize.go | 15 ++++++++++----- src/cmd/prepare.go | 5 +++-- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/src/cmd/initialize.go b/src/cmd/initialize.go index eaed5a50e5..cfb3b7c875 100644 --- a/src/cmd/initialize.go +++ b/src/cmd/initialize.go @@ -19,13 +19,18 @@ var initCmd = &cobra.Command{ Use: "init", Aliases: []string{"i"}, Short: "Prepares a k8s cluster for the deployment of Zarf packages", - Long: "Uses a local 'zarf-init' package found either in the directory you executed " + - "the command from or the directory that the Zarf binaries exists. " + - "Injects a docker registry as well as other optional useful things (such as a git server " + + Long: "Injects a docker registry as well as other optional useful things (such as a git server " + "and a logging stack) into a k8s cluster under the 'zarf' namespace " + "to support future application deployments. \n" + + "If you do not have a k8s cluster already configured, this command will give you " + - "the ability to install a cluster locally.\n", + "the ability to install a cluster locally.\n\n" + + + "This command looks for a zarf-init package in the local directory that the command was executed " + + "from. If no package is found in the local directory and the Zarf CLI exists somewhere outside of " + + "the current directory, Zarf will failover and attempt to find a zarf-init package in the directory " + + "that the Zarf binary is located in.\n", + Run: func(cmd *cobra.Command, args []string) { zarfLogo := message.GetLogo() _, _ = fmt.Fprintln(os.Stderr, zarfLogo) @@ -52,7 +57,7 @@ var initCmd = &cobra.Command{ func init() { rootCmd.AddCommand(initCmd) initCmd.Flags().BoolVar(&config.DeployOptions.Confirm, "confirm", false, "Confirm the install without prompting") - initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to instal.") + initCmd.Flags().StringVar(&config.DeployOptions.Components, "components", "", "Comma-separated list of components to install.") initCmd.Flags().StringVar(&config.DeployOptions.StorageClass, "storage-class", "", "Describe the StorageClass to be used") initCmd.Flags().StringVar(&config.DeployOptions.Secret, "secret", "", "Root secret value that is used to 'seed' other secrets") initCmd.Flags().StringVar(&config.DeployOptions.NodePort, "nodeport", "", "Nodeport to access the Zarf container registry. Between [30000-32767]") diff --git a/src/cmd/prepare.go b/src/cmd/prepare.go index a8e75459f4..6385553fbb 100644 --- a/src/cmd/prepare.go +++ b/src/cmd/prepare.go @@ -72,8 +72,9 @@ var prepareComputeFileSha256sum = &cobra.Command{ var prepareFindImages = &cobra.Command{ Use: "find-images", Aliases: []string{"prep"}, - Short: "Evaluates components in a zarf file to identify images specified in their helm charts and manifests.\n" + - "Requires the `--repo-chart-path` flag to be provided.", + Short: "Evaluates components in a zarf file to identify images specified in their helm charts and manifests", + Long: "Evaluates components in a zarf file to identify images specified in their helm charts and manifests.\n\n" + + "Components that have repos that host helm charts can be processed by providing the --repo-chart-path.", Run: func(cmd *cobra.Command, args []string) { packager.FindImages(repoHelmChartPath) },