From e411eea188364c4c3da33eb9eca64ad1b0cd48c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Mon, 4 Sep 2023 21:56:23 +0200 Subject: [PATCH] refactor: add a cobra utils package to build commands doc (#8255) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor: add a cobra utils package to build commands doc Signed-off-by: Charles-Edouard Brétéché * codegen Signed-off-by: Charles-Edouard Brétéché --------- Signed-off-by: Charles-Edouard Brétéché --- .../kubectl-kyverno/commands/test/command.go | 17 ++- cmd/cli/kubectl-kyverno/commands/test/doc.go | 28 ++++ cmd/cli/kubectl-kyverno/commands/test/help.go | 124 --------------- cmd/cli/kubectl-kyverno/utils/cobra/docs.go | 36 +++++ docs/user/cli/kyverno.md | 3 +- docs/user/cli/kyverno_test.md | 144 +++--------------- 6 files changed, 95 insertions(+), 257 deletions(-) create mode 100644 cmd/cli/kubectl-kyverno/commands/test/doc.go delete mode 100644 cmd/cli/kubectl-kyverno/commands/test/help.go create mode 100644 cmd/cli/kubectl-kyverno/utils/cobra/docs.go diff --git a/cmd/cli/kubectl-kyverno/commands/test/command.go b/cmd/cli/kubectl-kyverno/commands/test/command.go index da066537b1..a41712a061 100644 --- a/cmd/cli/kubectl-kyverno/commands/test/command.go +++ b/cmd/cli/kubectl-kyverno/commands/test/command.go @@ -8,6 +8,7 @@ import ( "github.com/go-git/go-billy/v5" policyreportv1alpha2 "github.com/kyverno/kyverno/api/policyreport/v1alpha2" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/commands/test/api" + cobrautils "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/utils/cobra" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/utils/color" filterutils "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/utils/filter" "github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/utils/output/table" @@ -26,11 +27,11 @@ func Command() *cobra.Command { var fileName, gitBranch string var registryAccess, failOnly, removeColor, detailedResults bool cmd = &cobra.Command{ - Use: "test [flags]\n kyverno test --git-branch \n kyverno test --manifest-mutate > kyverno-test.yaml\n kyverno test --manifest-validate > kyverno-test.yaml", - // Args: cobra.ExactArgs(1), - Short: "Run tests from directory.", - Long: longHelp, - Example: exampleHelp, + Use: "test [local folder or git repository]...", + Args: cobra.MinimumNArgs(1), + Short: cobrautils.FormatDescription(true, websiteUrl, description...), + Long: cobrautils.FormatDescription(false, websiteUrl, description...), + Example: cobrautils.FormatExamples(examples...), RunE: func(cmd *cobra.Command, dirPath []string) (err error) { color.InitColors(removeColor) defer func() { @@ -50,9 +51,9 @@ func Command() *cobra.Command { return nil }, } - cmd.Flags().StringVarP(&fileName, "file-name", "f", "kyverno-test.yaml", "test filename") - cmd.Flags().StringVarP(&gitBranch, "git-branch", "b", "", "test github repository branch") - cmd.Flags().StringVarP(&testCase, "test-case-selector", "t", "", `run some specific test cases by passing a string argument in double quotes to this flag like - "policy=, rule=, resource= - -Executing require-non-root-groups... -applying 1 policy to 2 resources... - -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ -│ 1 │ require-non-root-groups │ check-runasgroup │ default/Pod/fs-group0 │ Pass │ -│ 2 │ require-non-root-groups │ check-supplementalGroups │ default/Pod/fs-group0 │ Pass │ -│ 3 │ require-non-root-groups │ check-fsGroup │ default/Pod/fs-group0 │ Pass │ -│ 4 │ require-non-root-groups │ check-supplementalGroups │ default/Pod/supplemental-groups0 │ Pass │ -│ 5 │ require-non-root-groups │ check-fsGroup │ default/Pod/supplemental-groups0 │ Pass │ -│ 6 │ require-non-root-groups │ check-runasgroup │ default/Pod/supplemental-groups0 │ Pass │ -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ - - -# Test a local folder containing test cases. -kyverno test . - -Executing limit-containers-per-pod... -applying 1 policy to 4 resources... - -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ -│ 1 │ limit-containers-per-pod │ limit-containers-per-pod-bare │ default/Pod/myapp-pod-1 │ Pass │ -│ 2 │ limit-containers-per-pod │ limit-containers-per-pod-bare │ default/Pod/myapp-pod-2 │ Pass │ -│ 3 │ limit-containers-per-pod │ limit-containers-per-pod-controllers │ default/Deployment/mydeploy │ Pass │ -│ 4 │ limit-containers-per-pod │ limit-containers-per-pod-cronjob │ default/CronJob/mycronjob │ Pass │ -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ - -Test Summary: 4 tests passed and 0 tests failed - -# Test some specific test cases out of many test cases in a local folder. -kyverno test . --test-case-selector "policy=disallow-latest-tag, rule=require-image-tag, resource=test-require-image-tag-pass" - -Executing test-simple... -applying 1 policy to 1 resource... - -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ -│ 1 │ disallow-latest-tag │ require-image-tag │ default/Pod/test-require-image-tag-pass │ Pass │ -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ - -Test Summary: 1 tests passed and 0 tests failed - - - -**TEST FILE STRUCTURE**: - -The kyverno-test.yaml has four parts: - "policies" --> List of policies which are applied. - "resources" --> List of resources on which the policies are applied. - "variables" --> Variable file path containing variables referenced in the policy (OPTIONAL). - "results" --> List of results expected after applying the policies to the resources. - -** TEST FILE FORMAT**: - -name: -policies: -- -- -resources: -- -- -variables: (OPTIONAL) -results: -- policy: (For Namespaced [Policy] files, format is /) - rule: - resource: - namespace: (OPTIONAL) - kind: - patchedResource: (For mutate policies/rules only) - result: - -**VARIABLES FILE FORMAT**: - -policies: -- name: - rules: - - name: - # Global variable values - values: - foo: bar - resources: - - name: - # Resource-specific variable values - values: - foo: baz - - name: - values: - foo: bin -# If policy is matching on Kind/Subresource, then this is required -subresources: - - subresource: - name: - kind: - group: - version: - parentResource: - name: - kind: - group: - version: - -**RESULT DESCRIPTIONS**: - -pass --> The resource is either validated by the policy or, if a mutation, equals the state of the patched resource. -fail --> The resource fails validation or the patched resource generated by Kyverno is not equal to the input resource provided by the user. -skip --> The rule is not applied. - -For more information visit https://kyverno.io/docs/kyverno-cli/#test -` diff --git a/cmd/cli/kubectl-kyverno/utils/cobra/docs.go b/cmd/cli/kubectl-kyverno/utils/cobra/docs.go new file mode 100644 index 0000000000..54ee1b1c2d --- /dev/null +++ b/cmd/cli/kubectl-kyverno/utils/cobra/docs.go @@ -0,0 +1,36 @@ +package cobra + +func FormatDescription(short bool, url string, lines ...string) string { + if len(lines) == 0 { + return "" + } + description := lines[0] + description += "\n" + if short { + return description + } + for _, line := range lines[1:] { + description += " " + description += line + description += "\n" + } + if url != "" { + description += "\n" + description += " " + description += "For more information visit " + url + } + return description +} + +func FormatExamples(in ...[]string) string { + var examples string + for _, example := range in { + for _, line := range example { + examples += " " + examples += line + examples += "\n" + } + examples += "\n" + } + return examples +} diff --git a/docs/user/cli/kyverno.md b/docs/user/cli/kyverno.md index 1825c84214..b0bc6ff2ba 100644 --- a/docs/user/cli/kyverno.md +++ b/docs/user/cli/kyverno.md @@ -38,6 +38,7 @@ kyverno [flags] * [kyverno fix](kyverno_fix.md) - Provides a command-line interface to fix inconsistencies and deprecated usage of Kyverno resources. * [kyverno jp](kyverno_jp.md) - Provides a command-line interface to JMESPath, enhanced with Kyverno specific custom functions. * [kyverno oci](kyverno_oci.md) - Pulls/pushes images that include policie(s) from/to OCI registries. -* [kyverno test](kyverno_test.md) - Run tests from directory. +* [kyverno test](kyverno_test.md) - Run tests from a local filesystem or a remote git repository. + * [kyverno version](kyverno_version.md) - Shows current version of kyverno. diff --git a/docs/user/cli/kyverno_test.md b/docs/user/cli/kyverno_test.md index 6870b09106..bf4219ac40 100644 --- a/docs/user/cli/kyverno_test.md +++ b/docs/user/cli/kyverno_test.md @@ -1,140 +1,36 @@ ## kyverno test -Run tests from directory. +Run tests from a local filesystem or a remote git repository. + ### Synopsis +Run tests from a local filesystem or a remote git repository. + + The test command provides a facility to test resources against policies by comparing expected results, + declared ahead of time in a test manifest file, to actual results reported by Kyverno. + + Users provide the path to the folder containing a kyverno-test.yaml file where the location could be + on a local filesystem or a remote git repository. -The test command provides a facility to test resources against policies by comparing expected results, declared ahead of time in a test manifest file, to actual results reported by Kyverno. Users provide the path to the folder containing a kyverno-test.yaml file where the location could be on a local filesystem or a remote git repository. - + For more information visit https://kyverno.io/docs/kyverno-cli/#test ``` -kyverno test [flags] - kyverno test --git-branch - kyverno test --manifest-mutate > kyverno-test.yaml - kyverno test --manifest-validate > kyverno-test.yaml +kyverno test [local folder or git repository]... [flags] ``` ### Examples ``` + # Test a git repository containing Kyverno test cases + kyverno test https://github.com/kyverno/policies/pod-security --git-branch main -# Test a git repository containing Kyverno test cases. -kyverno test https://github.com/kyverno/policies/pod-security --git-branch main - + # Test a local folder containing test cases + kyverno test . -Executing require-non-root-groups... -applying 1 policy to 2 resources... + # Test some specific test cases out of many test cases in a local folder + kyverno test . --test-case-selector "policy=disallow-latest-tag, rule=require-image-tag, resource=test-require-image-tag-pass" -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ -│ 1 │ require-non-root-groups │ check-runasgroup │ default/Pod/fs-group0 │ Pass │ -│ 2 │ require-non-root-groups │ check-supplementalGroups │ default/Pod/fs-group0 │ Pass │ -│ 3 │ require-non-root-groups │ check-fsGroup │ default/Pod/fs-group0 │ Pass │ -│ 4 │ require-non-root-groups │ check-supplementalGroups │ default/Pod/supplemental-groups0 │ Pass │ -│ 5 │ require-non-root-groups │ check-fsGroup │ default/Pod/supplemental-groups0 │ Pass │ -│ 6 │ require-non-root-groups │ check-runasgroup │ default/Pod/supplemental-groups0 │ Pass │ -│───│─────────────────────────│──────────────────────────│──────────────────────────────────│────────│ - - -# Test a local folder containing test cases. -kyverno test . - -Executing limit-containers-per-pod... -applying 1 policy to 4 resources... - -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ -│ 1 │ limit-containers-per-pod │ limit-containers-per-pod-bare │ default/Pod/myapp-pod-1 │ Pass │ -│ 2 │ limit-containers-per-pod │ limit-containers-per-pod-bare │ default/Pod/myapp-pod-2 │ Pass │ -│ 3 │ limit-containers-per-pod │ limit-containers-per-pod-controllers │ default/Deployment/mydeploy │ Pass │ -│ 4 │ limit-containers-per-pod │ limit-containers-per-pod-cronjob │ default/CronJob/mycronjob │ Pass │ -│───│──────────────────────────│──────────────────────────────────────│─────────────────────────────│────────│ - -Test Summary: 4 tests passed and 0 tests failed - -# Test some specific test cases out of many test cases in a local folder. -kyverno test . --test-case-selector "policy=disallow-latest-tag, rule=require-image-tag, resource=test-require-image-tag-pass" - -Executing test-simple... -applying 1 policy to 1 resource... - -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ -│ # │ POLICY │ RULE │ RESOURCE │ RESULT │ -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ -│ 1 │ disallow-latest-tag │ require-image-tag │ default/Pod/test-require-image-tag-pass │ Pass │ -│───│─────────────────────│───────────────────│─────────────────────────────────────────│────────│ - -Test Summary: 1 tests passed and 0 tests failed - - - -**TEST FILE STRUCTURE**: - -The kyverno-test.yaml has four parts: - "policies" --> List of policies which are applied. - "resources" --> List of resources on which the policies are applied. - "variables" --> Variable file path containing variables referenced in the policy (OPTIONAL). - "results" --> List of results expected after applying the policies to the resources. - -** TEST FILE FORMAT**: - -name: -policies: -- -- -resources: -- -- -variables: (OPTIONAL) -results: -- policy: (For Namespaced [Policy] files, format is /) - rule: - resource: - namespace: (OPTIONAL) - kind: - patchedResource: (For mutate policies/rules only) - result: - -**VARIABLES FILE FORMAT**: - -policies: -- name: - rules: - - name: - # Global variable values - values: - foo: bar - resources: - - name: - # Resource-specific variable values - values: - foo: baz - - name: - values: - foo: bin -# If policy is matching on Kind/Subresource, then this is required -subresources: - - subresource: - name: - kind: - group: - version: - parentResource: - name: - kind: - group: - version: - -**RESULT DESCRIPTIONS**: - -pass --> The resource is either validated by the policy or, if a mutation, equals the state of the patched resource. -fail --> The resource fails validation or the patched resource generated by Kyverno is not equal to the input resource provided by the user. -skip --> The rule is not applied. - -For more information visit https://kyverno.io/docs/kyverno-cli/#test ``` @@ -143,12 +39,12 @@ For more information visit https://kyverno.io/docs/kyverno-cli/#test ``` --detailed-results If set to true, display detailed results --fail-only If set to true, display all the failing test only as output for the test command - -f, --file-name string test filename (default "kyverno-test.yaml") - -b, --git-branch string test github repository branch + -f, --file-name string Test filename (default "kyverno-test.yaml") + -b, --git-branch string Test github repository branch -h, --help help for test --registry If set to true, access the image registry using local docker credentials to populate external data --remove-color Remove any color from output - -t, --test-case-selector string run some specific test cases by passing a string argument in double quotes to this flag like - "policy=, rule=, resource=