From e2487577987fce5592e0131b79ad230e994ddc7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Wed, 30 Aug 2023 13:26:26 +0200 Subject: [PATCH] feat: add cli docs command (#8179) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché --- cmd/cli/kubectl-kyverno/docs/docs.go | 69 +++++++ cmd/cli/kubectl-kyverno/main.go | 10 +- docs/user/cli/kyverno.md | 38 ++++ docs/user/cli/kyverno_apply.md | 139 ++++++++++++++ docs/user/cli/kyverno_completion.md | 43 +++++ docs/user/cli/kyverno_completion_bash.md | 62 ++++++ docs/user/cli/kyverno_completion_fish.md | 53 ++++++ .../user/cli/kyverno_completion_powershell.md | 50 +++++ docs/user/cli/kyverno_completion_zsh.md | 64 +++++++ docs/user/cli/kyverno_create.md | 41 ++++ .../user/cli/kyverno_create_metrics-config.md | 48 +++++ docs/user/cli/kyverno_create_test.md | 51 +++++ docs/user/cli/kyverno_create_user-info.md | 48 +++++ docs/user/cli/kyverno_create_values.md | 48 +++++ docs/user/cli/kyverno_docs.md | 39 ++++ docs/user/cli/kyverno_jp.md | 45 +++++ docs/user/cli/kyverno_jp_function.md | 52 ++++++ docs/user/cli/kyverno_jp_parse.md | 62 ++++++ docs/user/cli/kyverno_jp_query.md | 65 +++++++ docs/user/cli/kyverno_test.md | 176 ++++++++++++++++++ docs/user/cli/kyverno_version.md | 37 ++++ go.mod | 2 + go.sum | 2 + 23 files changed, 1243 insertions(+), 1 deletion(-) create mode 100644 cmd/cli/kubectl-kyverno/docs/docs.go create mode 100644 docs/user/cli/kyverno.md create mode 100644 docs/user/cli/kyverno_apply.md create mode 100644 docs/user/cli/kyverno_completion.md create mode 100644 docs/user/cli/kyverno_completion_bash.md create mode 100644 docs/user/cli/kyverno_completion_fish.md create mode 100644 docs/user/cli/kyverno_completion_powershell.md create mode 100644 docs/user/cli/kyverno_completion_zsh.md create mode 100644 docs/user/cli/kyverno_create.md create mode 100644 docs/user/cli/kyverno_create_metrics-config.md create mode 100644 docs/user/cli/kyverno_create_test.md create mode 100644 docs/user/cli/kyverno_create_user-info.md create mode 100644 docs/user/cli/kyverno_create_values.md create mode 100644 docs/user/cli/kyverno_docs.md create mode 100644 docs/user/cli/kyverno_jp.md create mode 100644 docs/user/cli/kyverno_jp_function.md create mode 100644 docs/user/cli/kyverno_jp_parse.md create mode 100644 docs/user/cli/kyverno_jp_query.md create mode 100644 docs/user/cli/kyverno_test.md create mode 100644 docs/user/cli/kyverno_version.md diff --git a/cmd/cli/kubectl-kyverno/docs/docs.go b/cmd/cli/kubectl-kyverno/docs/docs.go new file mode 100644 index 0000000000..320030df8e --- /dev/null +++ b/cmd/cli/kubectl-kyverno/docs/docs.go @@ -0,0 +1,69 @@ +package docs + +import ( + "errors" + "fmt" + "log" + "os" + "path" + "path/filepath" + "strings" + "time" + + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +const fmTemplate = `--- +date: %s +title: "%s" +weight: 35 +--- +` + +func websitePrepender(filename string) string { + now := time.Now().Format(time.RFC3339) + name := filepath.Base(filename) + base := strings.TrimSuffix(name, path.Ext(name)) + return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1)) +} + +func identity(s string) string { + return s +} + +func empty(s string) string { + return "" +} + +func Command(root *cobra.Command) *cobra.Command { + var path string + var website bool + cmd := &cobra.Command{ + Use: "docs", + Short: "Generates documentation.", + Example: "", + RunE: func(_ *cobra.Command, args []string) error { + prepender := empty + linkHandler := identity + if website { + prepender = websitePrepender + } + if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) { + if err := os.MkdirAll(path, os.ModeDir|os.ModePerm); err != nil { + return err + } + } + return doc.GenMarkdownTreeCustom(root, path, prepender, linkHandler) + }, + } + cmd.Flags().StringVarP(&path, "output", "o", ".", "Output path") + cmd.Flags().BoolVar(&website, "website", false, "Website version") + if err := cmd.MarkFlagDirname("output"); err != nil { + log.Println("WARNING", err) + } + if err := cmd.MarkFlagRequired("output"); err != nil { + log.Println("WARNING", err) + } + return cmd +} diff --git a/cmd/cli/kubectl-kyverno/main.go b/cmd/cli/kubectl-kyverno/main.go index 1c41b48477..c3a2fea280 100644 --- a/cmd/cli/kubectl-kyverno/main.go +++ b/cmd/cli/kubectl-kyverno/main.go @@ -8,6 +8,7 @@ import ( "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/apply" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/create" + "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/docs" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/jp" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/oci" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/test" @@ -48,7 +49,14 @@ func enableExperimental() bool { } func registerCommands(cli *cobra.Command) { - cli.AddCommand(version.Command(), create.Command(), apply.Command(), test.Command(), jp.Command()) + cli.AddCommand( + apply.Command(), + create.Command(), + docs.Command(cli), + jp.Command(), + test.Command(), + version.Command(), + ) if enableExperimental() { cli.AddCommand(oci.Command()) } diff --git a/docs/user/cli/kyverno.md b/docs/user/cli/kyverno.md new file mode 100644 index 0000000000..0210e4cdd6 --- /dev/null +++ b/docs/user/cli/kyverno.md @@ -0,0 +1,38 @@ +## kyverno + +Kubernetes Native Policy Management + +### Synopsis + +To enable experimental commands, KYVERNO_EXPERIMENTAL should be configured with true or 1. + +### Options + +``` + --add_dir_header If true, adds the file directory to the header of the log messages + --alsologtostderr log to standard error as well as files (no effect when -logtostderr=true) + -h, --help help for kyverno + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory (no effect when -logtostderr=true) + --log_file string If non-empty, use this log file (no effect when -logtostderr=true) + --log_file_max_size uint Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800) + --logtostderr log to standard error instead of files (default true) + --one_output If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when -logtostderr=true) + --skip_headers If true, avoid header prefixes in the log messages + --skip_log_headers If true, avoid headers when opening log files (no effect when -logtostderr=true) + --stderrthreshold severity logs at or above this threshold go to stderr when writing to files and stderr (no effect when -logtostderr=true or -alsologtostderr=false) (default 2) + -v, --v Level number for the log level verbosity + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [kyverno apply](kyverno_apply.md) - Applies policies on resources. +* [kyverno completion](kyverno_completion.md) - Generate the autocompletion script for the specified shell +* [kyverno create](kyverno_create.md) - Provides a command-line interface to help with the creation of various Kyverno resources. +* [kyverno docs](kyverno_docs.md) - Generates documentation. +* [kyverno jp](kyverno_jp.md) - Provides a command-line interface to JMESPath, enhanced with Kyverno specific custom functions. +* [kyverno test](kyverno_test.md) - Run tests from directory. +* [kyverno version](kyverno_version.md) - Shows current version of kyverno. + +###### Auto generated by spf13/cobra on 30-Aug-2023 diff --git a/docs/user/cli/kyverno_apply.md b/docs/user/cli/kyverno_apply.md new file mode 100644 index 0000000000..748ddc92ae --- /dev/null +++ b/docs/user/cli/kyverno_apply.md @@ -0,0 +1,139 @@ +## kyverno apply + +Applies policies on resources. + +``` +kyverno apply [flags] +``` + +### Examples + +``` + +To apply on a resource: + kyverno apply /path/to/policy.yaml /path/to/folderOfPolicies --resource=/path/to/resource1 --resource=/path/to/resource2 + +To apply on a folder of resources: + kyverno apply /path/to/policy.yaml /path/to/folderOfPolicies --resource=/path/to/resources/ + +To apply on a cluster: + kyverno apply /path/to/policy.yaml /path/to/folderOfPolicies --cluster + +To apply policies from a gitSourceURL on a cluster: + Example: Taking github.com as a gitSourceURL here. Some other standards gitSourceURL are: gitlab.com , bitbucket.org , etc. + kyverno apply https://github.com/kyverno/policies/openshift/ --git-branch main --cluster + +To apply policy with variables: + + 1. To apply single policy with variable on single resource use flag "set". + Example: + kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml --set =,= + + 2. To apply multiple policy with variable on multiple resource use flag "values_file". + Example: + kyverno apply /path/to/policy1.yaml /path/to/policy2.yaml --resource /path/to/resource1.yaml --resource /path/to/resource2.yaml -f /path/to/value.yaml + + Format of value.yaml: + + policies: + - name: + rules: + - name: + values: + : + : + - name: + values: + : + : + resources: + - name: + values: + : + : + - name: + values: + : + : + - name: + resources: + - name: + values: + : + : + - name: + values: + : + : + namespaceSelector: + - name: + labels: +