diff --git a/go.sum b/go.sum index abeaa2a..d54b958 100644 --- a/go.sum +++ b/go.sum @@ -74,6 +74,7 @@ github.com/coreos/go-semver v0.3.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3Ee github.com/coreos/go-systemd v0.0.0-20181031085051-9002847aa142/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4= github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA= github.com/coreos/prometheus-operator v0.29.0/go.mod h1:SO+r5yZUacDFPKHfPoUjI3hMsH+ZUdiuNNhuSq3WoSg= +github.com/cpuguy83/go-md2man v1.0.10 h1:BSKMNlYxDvnunlTymqtgONjNnaRV1sTpcovwwjF22jk= github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE= github.com/cyphar/filepath-securejoin v0.2.2/go.mod h1:FpkQEhXnPnOthhzymB7CGsFk2G9VLXONKD9G7QGMM+4= github.com/d4l3k/messagediff v1.2.1 h1:ZcAIMYsUg0EAp9X+tt8/enBE/Q8Yd5kzPynLyKptt9U= @@ -391,6 +392,7 @@ github.com/prometheus/prom2json v1.2.1/go.mod h1:yIcXOj/TLPdtZ12qRyhswPnu+02sfDo github.com/rcrowley/go-metrics v0.0.0-20181016184325-3113b8401b8a/go.mod h1:bCqnVzQkZxMG4s8nGwiZ5l3QUCyqpo9Y+/ZMZ9VjZe4= github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg= github.com/rogpeppe/go-charset v0.0.0-20180617210344-2471d30d28b4/go.mod h1:qgYeAmZ5ZIpBWTGllZSQnw97Dj+woV0toclVaRGI8pc= +github.com/russross/blackfriday v1.5.2 h1:HyvC0ARfnZBqnXwABFeSZHpKvJHJJfPz81GNueLj0oo= github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g= github.com/ryanuber/go-glob v0.0.0-20160226084822-572520ed46db/go.mod h1:807d1WSdnB0XRJzKNil9Om6lcp/3a0v4qIHxIXzX/Yc= github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0= diff --git a/pkg/cmd/doc.go b/pkg/cmd/doc.go new file mode 100644 index 0000000..9256dc7 --- /dev/null +++ b/pkg/cmd/doc.go @@ -0,0 +1,63 @@ +// Copyright 2019 Tetrate +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package cmd + +import ( + "fmt" + "path" + "path/filepath" + "strings" + + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +var ( + outputDir string + linkDir string +) + +// NewDocCmd returns command that generates documentation +func NewDocCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "doc", + Short: "Generates markdown documentation for the cli.", + Hidden: true, + RunE: func(cmd *cobra.Command, _ []string) error { + getenvoy := cmd.Parent() + return doc.GenMarkdownTreeCustom(getenvoy, outputDir, filePrepender, linkHandler) + }, + } + cmd.PersistentFlags().StringVarP(&outputDir, "output", "o", "", "directory to create generated docs") + cmd.PersistentFlags().StringVarP(&linkDir, "link", "l", "", "directory to prepend to filename in links") + return cmd +} + +func filePrepender(filename string) string { + name := filepath.Base(filename) + base := strings.TrimSuffix(name, path.Ext(name)) + return fmt.Sprintf(fmTemplate, strings.ReplaceAll(base, "_", " ")) +} + +const fmTemplate = `+++ +title = "%s" +type = "docs" ++++ +` + +func linkHandler(name string) string { + base := strings.TrimSuffix(name, path.Ext(name)) + return filepath.Join(linkDir, strings.ToLower(base)) +} diff --git a/pkg/cmd/fetch.go b/pkg/cmd/fetch.go index 969439f..0fc9504 100644 --- a/pkg/cmd/fetch.go +++ b/pkg/cmd/fetch.go @@ -25,16 +25,16 @@ import ( // NewFetchCmd create a command responsible for retrieving Envoy binaries func NewFetchCmd() *cobra.Command { return &cobra.Command{ - Use: "fetch [binary]", - Short: "Retreives the passed Envoy binary.", + Use: "fetch ", + Short: "Retrieve Envoy binaries from GetEnvoy.", Long: ` -Retreives the passed Envoy binary. -Location can be a full or partial manifest reference, use getenvoy list for a complete list of available builds.`, - Example: `# Fetch using a partial manifest reference to retrieve a build for your operating system. +Retrieves the referenced Envoy binary from GetEnvoy. The reference can be a full or partial reference. +A complete list of available builds can be retrieved using` + "`getenvoy list`" + `.`, + Example: `# Fetch using a partial manifest reference to retrieve a build suitable for your operating system. getenvoy fetch standard:1.11.1 -# Fetch using a full manifest reference to retrieve a specific build. -getenvoy fetch standard:1.11.1/debian`, +# Fetch using a full manifest reference to retrieve a specific build for Linux. +getenvoy fetch standard:1.11.1/linux-glibc`, Args: func(cmd *cobra.Command, args []string) error { if len(args) == 0 { return errors.New("missing binary parameter") diff --git a/pkg/cmd/list.go b/pkg/cmd/list.go index cb3edff..bb050df 100644 --- a/pkg/cmd/list.go +++ b/pkg/cmd/list.go @@ -25,7 +25,9 @@ import ( func NewListCmd() *cobra.Command { return &cobra.Command{ Use: "list", - Short: "Lists available Envoys from GetEnvoy.", + Short: "List available Envoys provided by GetEnvoy.", + Long: ` +Retrieves a list of Envoy builds provided by GetEnvoy.`, RunE: func(cmd *cobra.Command, _ []string) error { return manifest.Print(os.Stdout, manifestURL) }, diff --git a/pkg/cmd/root.go b/pkg/cmd/root.go index cae5198..5cfb93d 100644 --- a/pkg/cmd/root.go +++ b/pkg/cmd/root.go @@ -22,24 +22,22 @@ import ( // NewRoot create a new root command and sets the cliVersion to the passed variable // TODO: Add version support on the command func NewRoot() *cobra.Command { - runCmd := NewRunCmd() - rootCmd.AddCommand(runCmd) + rootCmd.AddCommand(NewRunCmd()) + rootCmd.AddCommand(NewListCmd()) + rootCmd.AddCommand(NewFetchCmd()) + rootCmd.AddCommand(NewDocCmd()) - listCmd := NewListCmd() - rootCmd.AddCommand(listCmd) - - fetchCmd := NewFetchCmd() - rootCmd.AddCommand(fetchCmd) - - rootCmd.PersistentFlags().StringVarP(&manifestURL, "url", "u", manifest.DefaultURL, "sets the manifest URL") + rootCmd.PersistentFlags().StringVar(&manifestURL, "manifest", manifest.DefaultURL, "sets the manifest URL") + rootCmd.PersistentFlags().MarkHidden("manifest") // nolint return rootCmd } var ( rootCmd = &cobra.Command{ Use: "getenvoy", - Short: "getenvoy", - Long: "getenvoy", + Short: "Fetch, deploy and debug Envoy", + Long: `Manage full lifecycle of Envoy including fetching binaries, +bootstrap generation and automated collection of access logs, Envoy state and machine state.`, } manifestURL string diff --git a/pkg/cmd/run.go b/pkg/cmd/run.go index 3cbe311..2bbc9dd 100644 --- a/pkg/cmd/run.go +++ b/pkg/cmd/run.go @@ -37,18 +37,21 @@ var ( // NewRunCmd create a command responsible for starting an Envoy process func NewRunCmd() *cobra.Command { cmd := &cobra.Command{ - Use: "run [manifest-reference|filepath] -- ", - Short: "Starts an Envoy process using the reference or path passed.", + Use: "run [flags] [-- ]", + Short: "Runs an instance of Envoy.", Long: ` -Starts an Envoy process using the location passed. -Location can be a manifest reference or path to an Envoy binary.`, - Example: `# Run using a manifest reference. Reference format is :. +Manages full lifecycle of Envoy including bootstrap generation and automated collection of access logs, +Envoy state and machine state into the ` + "`~/.getenvoy/debug`" + ` directory.`, + Example: `# Run using a manifest reference. getenvoy run standard:1.11.1 -- --config-path ./bootstrap.yaml -# Run using a filepath +# Run as a gateway using an Istio controlplane bootstrap. +getenvoy run standard:1.11.1 --mode router --bootstrap istio --controlplaneAddress istio-pilot.istio-system:15010 + +# Run using a filepath. getenvoy run ./envoy -- --config-path ./bootstrap.yaml -# List available Envoy flags +# List available Envoy flags. getenvoy run standard:1.11.1 -- --help `, Args: func(cmd *cobra.Command, args []string) error { @@ -103,13 +106,13 @@ getenvoy run standard:1.11.1 -- --help }, } cmd.Flags().StringVarP(&bootstrap, "bootstrap", "b", "", - fmt.Sprintf("which controlplane's bootstrap to generate and use (%v) [experimental]", strings.Join(supported, "|"))) + fmt.Sprintf("controlplane bootstrap to generate and use <%v> (experimental)", strings.Join(supported, "|"))) cmd.Flags().StringVar(&controlplaneAddress, "controlplaneAddress", "", - "location of Envoy's dynamic configuration server (:port) [requires bootstrap to be set]") + "location of Envoy's dynamic configuration server (requires bootstrap flag)") cmd.Flags().StringVar(&accessLogServerAddress, "accessLogServerAddress", "", - "location of Envoy's access log server(:port) [requires bootstrap to be set]") - cmd.Flags().StringVarP(&mode, "mode", "m", "", - fmt.Sprintf("mode to run Envoy in (%v) [requires bootstrap to be set]", strings.Join(envoy.SupportedModes, "|"))) + "location of Envoy's access log server (requires bootstrap flag)") + cmd.Flags().StringVar(&mode, "mode", "", + fmt.Sprintf("mode to run Envoy in <%v> (requires bootstrap flag)", strings.Join(envoy.SupportedModes, "|"))) return cmd }