Skip to content

Commit c0cf9e5

Browse files
kyledong-susekyledong-suse
authored
Merge pull request #526 from kyledong-suse/feature
docs: extend kubectl plugin docs with cobra's doc generator
2 parents 040ccf4 + 0e00ab4 commit c0cf9e5

34 files changed

Lines changed: 670 additions & 142 deletions

‎Makefile‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ TARGET=controller agent debugger
6161
$(foreach T,$(TARGET),$(eval $(call BUILD_template,$(T))))
6262

6363
.PHONY: generate
64-
generate: manifests generate-ebpf generate-proto generate-api generate-crd-docs generate-chart
64+
generate: manifests generate-ebpf generate-proto generate-api generate-crd-docs generate-chart generate-kubectl-plugin-docs
6565
$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
6666

6767
.PHONY: fmt
@@ -80,6 +80,10 @@ generate-ebpf: ## Generate eBPF artifacts.
8080
generate-crd-docs: ## Generate CRD documentation.
8181
make -C docs/crds asciidoc
8282

83+
.PHONY: generate-kubectl-plugin-docs
84+
generate-kubectl-plugin-docs: ## Generate kubectl plugin docs.
85+
go run ./internal/tools/docgen -out docs/kubectl-plugin
86+
8387
.PHONY: test
8488
test: generate-ebpf vet setup-envtest ## Run tests.
8589
KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path)" go test $$(go list ./... | grep -v /e2e | grep -v /internal/bpf) -race -test.v -coverprofile coverage/cover.out -covermode=atomic
@@ -131,7 +135,7 @@ PLUGIN_PLATFORMS ?= linux/amd64 linux/arm64 darwin/amd64 darwin/arm64
131135

132136
.PHONY: kubectl-plugin
133137
kubectl-plugin: ## Build kubectl plugin for the current platform.
134-
go build -ldflags "-X main.version=$(KUBECTL_PLUGIN_VERSION)" -o ./bin/kubectl-runtime_enforcer ./cmd/kubectl-plugin
138+
go build -ldflags "-X github.com/rancher-sandbox/runtime-enforcer/internal/kubectlplugin.version=$(KUBECTL_PLUGIN_VERSION)" -o ./bin/kubectl-runtime_enforcer ./cmd/kubectl-plugin
135139

136140
.PHONY: kubectl-plugin-cross
137141
kubectl-plugin-cross: ## Build kubectl plugin for all target platforms.
@@ -142,7 +146,7 @@ kubectl-plugin-cross: ## Build kubectl plugin for all target platforms.
142146
out=bin/kubectl-plugin/kubectl-runtime_enforcer-$$os-$$arch; \
143147
echo "Building $$out ..."; \
144148
CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch go build \
145-
-ldflags "-X main.version=$(KUBECTL_PLUGIN_VERSION)" \
149+
-ldflags "-X github.com/rancher-sandbox/runtime-enforcer/internal/kubectlplugin.version=$(KUBECTL_PLUGIN_VERSION)" \
146150
-o $$out \
147151
./cmd/kubectl-plugin; \
148152
done

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ See [docs/compatibility.adoc](docs/compatibility.adoc) for complete details.
2020

2121
- [Phases: Learn, Monitor, Protect](docs/phases.adoc)
2222
- [Learning Mode Configuration](docs/learning_mode_configuration.adoc)
23+
- [kubectl plugin](docs/kubectl_plugin.adoc)
2324
- [Troubleshooting](docs/troubleshooting.adoc)
2425

2526
### Reference

‎cmd/kubectl-plugin/README.md‎

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎cmd/kubectl-plugin/main.go‎

Lines changed: 2 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -3,81 +3,12 @@ package main
33
import (
44
"os"
55

6-
"github.com/spf13/cobra"
7-
"k8s.io/cli-runtime/pkg/genericclioptions"
8-
"k8s.io/cli-runtime/pkg/genericiooptions"
6+
"github.com/rancher-sandbox/runtime-enforcer/internal/kubectlplugin"
97
_ "k8s.io/client-go/plugin/pkg/client/auth"
10-
cmdutil "k8s.io/kubectl/pkg/cmd/util"
11-
utilcomp "k8s.io/kubectl/pkg/util/completion"
128
)
139

14-
var version = "dev"
15-
16-
// Custom usage template: no "kubectl [command]" line.
17-
const (
18-
rootUsageTemplate = `Usage:
19-
{{.UseLine}}
20-
21-
Available Commands:
22-
{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}} {{rpad .Name .NamePadding}} {{.Short}}
23-
{{end}}{{end}}
24-
Flags:
25-
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}
26-
`
27-
)
28-
29-
func registerCompletionFuncForGlobalFlags(cmd *cobra.Command, f cmdutil.Factory) {
30-
registerFlagCompletion := func(flagName string, completionFunc func(string) []string) {
31-
cmdutil.CheckErr(cmd.RegisterFlagCompletionFunc(
32-
flagName,
33-
func(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective) {
34-
return completionFunc(toComplete), cobra.ShellCompDirectiveNoFileComp
35-
}))
36-
}
37-
38-
registerFlagCompletion("namespace", func(toComplete string) []string {
39-
return utilcomp.CompGetResource(f, "namespace", toComplete)
40-
})
41-
registerFlagCompletion("context", utilcomp.ListContextsInConfig)
42-
registerFlagCompletion("cluster", utilcomp.ListClustersInConfig)
43-
registerFlagCompletion("user", utilcomp.ListUsersInConfig)
44-
}
45-
46-
func newRootCmd() *cobra.Command {
47-
cmd := &cobra.Command{
48-
Use: "runtime-enforcer",
49-
Long: "Kubernetes plugin for SUSE Security Runtime Enforcer",
50-
Version: version,
51-
Args: cobra.ArbitraryArgs,
52-
RunE: func(cmd *cobra.Command, _ []string) error {
53-
return cmd.Help()
54-
},
55-
}
56-
57-
cmd.SetUsageTemplate(rootUsageTemplate)
58-
59-
// Create a shared iostream.
60-
streams := genericiooptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr}
61-
62-
// Add flags to persistent flags so they are inherited by all subcommands
63-
configFlags := genericclioptions.NewConfigFlags(true).WithWarningPrinter(streams)
64-
configFlags.AddFlags(cmd.PersistentFlags())
65-
66-
// Create cmdutil.Factory for use in completion functions
67-
f := cmdutil.NewFactory(configFlags)
68-
utilcomp.SetFactoryForCompletion(f)
69-
70-
// Register completion functions, so we can auto-complete global flags like --namespace, --context, etc.
71-
registerCompletionFuncForGlobalFlags(cmd, f)
72-
73-
cmd.AddCommand(newProposalCmd(commonCmdDeps{f: f, ioStreams: streams}))
74-
cmd.AddCommand(newPolicyCmd(commonCmdDeps{f: f, ioStreams: streams}))
75-
76-
return cmd
77-
}
78-
7910
func main() {
80-
cmd := newRootCmd()
11+
cmd := kubectlplugin.NewRootCmd()
8112
if err := cmd.Execute(); err != nil {
8213
os.Exit(1)
8314
}

‎docs/installation/quickstart.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,12 @@ To do that, we label the `WorkloadPolicyProposal` with the `security.rancher.io/
179179
kubectl label workloadpolicyproposals.security.rancher.io deploy-ubuntu-deployment security.rancher.io/policy-ready=true
180180
```
181181

182+
You can also use the kubectl plugin to perform the same step:
183+
184+
```bash
185+
kubectl runtime-enforcer proposal promote deploy-ubuntu-deployment
186+
```
187+
182188
After a few seconds, you should see a new Custom Resource called `WorkloadPolicy`.
183189

184190
```bash
@@ -303,6 +309,12 @@ From now on, every violation of the executable list will be blocked.
303309
kubectl patch workloadpolicy deploy-ubuntu-deployment -n default --type='json' -p='[{"op": "replace", "path": "/spec/mode", "value": "protect"}]'
304310
```
305311

312+
You can also use the kubectl plugin to perform the same step:
313+
314+
```bash
315+
kubectl runtime-enforcer policy protect deploy-ubuntu-deployment -n default
316+
```
317+
306318
Now we can try again an allowed binary, nothing should be reported.
307319

308320
```bash

‎docs/kubectl-plugin/runtime-enforcer.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## runtime-enforcer
2+
3+
4+
5+
### Synopsis
6+
7+
Kubernetes plugin for SUSE Security Runtime Enforcer
8+
9+
```
10+
runtime-enforcer [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
17+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
18+
--as-uid string UID to impersonate for the operation.
19+
--as-user-extra stringArray User extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
20+
--cache-dir string Default cache directory (default "$HOME/.kube/cache")
21+
--certificate-authority string Path to a cert file for the certificate authority
22+
--client-certificate string Path to a client certificate file for TLS
23+
--client-key string Path to a client key file for TLS
24+
--cluster string The name of the kubeconfig cluster to use
25+
--context string The name of the kubeconfig context to use
26+
--disable-compression If true, opt-out of response compression for all requests to the server
27+
-h, --help help for runtime-enforcer
28+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
29+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
30+
-n, --namespace string If present, the namespace scope for this CLI request
31+
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
32+
-s, --server string The address and port of the Kubernetes API server
33+
--tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
34+
--token string Bearer token for authentication to the API server
35+
--user string The name of the kubeconfig user to use
36+
```
37+
38+
### SEE ALSO
39+
40+
* [runtime-enforcer policy](runtime-enforcer_policy.md) - Manage WorkloadPolicy
41+
* [runtime-enforcer proposal](runtime-enforcer_proposal.md) - Manage WorkloadPolicyProposal
42+

‎docs/kubectl-plugin/runtime-enforcer_policy.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## runtime-enforcer policy
2+
3+
Manage WorkloadPolicy
4+
5+
### Options
6+
7+
```
8+
-h, --help help for policy
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
15+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
16+
--as-uid string UID to impersonate for the operation.
17+
--as-user-extra stringArray User extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
18+
--cache-dir string Default cache directory (default "$HOME/.kube/cache")
19+
--certificate-authority string Path to a cert file for the certificate authority
20+
--client-certificate string Path to a client certificate file for TLS
21+
--client-key string Path to a client key file for TLS
22+
--cluster string The name of the kubeconfig cluster to use
23+
--context string The name of the kubeconfig context to use
24+
--disable-compression If true, opt-out of response compression for all requests to the server
25+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
26+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
27+
-n, --namespace string If present, the namespace scope for this CLI request
28+
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
29+
-s, --server string The address and port of the Kubernetes API server
30+
--tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
31+
--token string Bearer token for authentication to the API server
32+
--user string The name of the kubeconfig user to use
33+
```
34+
35+
### SEE ALSO
36+
37+
* [runtime-enforcer](runtime-enforcer.md) -
38+
* [runtime-enforcer policy allow](runtime-enforcer_policy_allow.md) - allow executables for a WorkloadPolicy container
39+
* [runtime-enforcer policy deny](runtime-enforcer_policy_deny.md) - deny executables for a WorkloadPolicy container
40+
* [runtime-enforcer policy monitor](runtime-enforcer_policy_monitor.md) - Set WorkloadPolicy mode to monitor
41+
* [runtime-enforcer policy protect](runtime-enforcer_policy_protect.md) - Set WorkloadPolicy mode to protect
42+
* [runtime-enforcer policy show](runtime-enforcer_policy_show.md) - Show WorkloadPolicy information
43+

‎docs/kubectl-plugin/runtime-enforcer_policy_allow.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## runtime-enforcer policy allow
2+
3+
allow executables for a WorkloadPolicy container
4+
5+
```
6+
runtime-enforcer policy allow POLICY_NAME <container-name> <executable-name> [<executable-name>...] [flags]
7+
```
8+
9+
### Options
10+
11+
```
12+
--dry-run Show what would happen without making any changes
13+
-h, --help help for allow
14+
```
15+
16+
### Options inherited from parent commands
17+
18+
```
19+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
20+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
21+
--as-uid string UID to impersonate for the operation.
22+
--as-user-extra stringArray User extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
23+
--cache-dir string Default cache directory (default "$HOME/.kube/cache")
24+
--certificate-authority string Path to a cert file for the certificate authority
25+
--client-certificate string Path to a client certificate file for TLS
26+
--client-key string Path to a client key file for TLS
27+
--cluster string The name of the kubeconfig cluster to use
28+
--context string The name of the kubeconfig context to use
29+
--disable-compression If true, opt-out of response compression for all requests to the server
30+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
31+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
32+
-n, --namespace string If present, the namespace scope for this CLI request
33+
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
34+
-s, --server string The address and port of the Kubernetes API server
35+
--tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
36+
--token string Bearer token for authentication to the API server
37+
--user string The name of the kubeconfig user to use
38+
```
39+
40+
### SEE ALSO
41+
42+
* [runtime-enforcer policy](runtime-enforcer_policy.md) - Manage WorkloadPolicy
43+

‎docs/kubectl-plugin/runtime-enforcer_policy_deny.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## runtime-enforcer policy deny
2+
3+
deny executables for a WorkloadPolicy container
4+
5+
```
6+
runtime-enforcer policy deny POLICY_NAME <container-name> <executable-name> [<executable-name>...] [flags]
7+
```
8+
9+
### Options
10+
11+
```
12+
--dry-run Show what would happen without making any changes
13+
-h, --help help for deny
14+
```
15+
16+
### Options inherited from parent commands
17+
18+
```
19+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
20+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
21+
--as-uid string UID to impersonate for the operation.
22+
--as-user-extra stringArray User extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
23+
--cache-dir string Default cache directory (default "$HOME/.kube/cache")
24+
--certificate-authority string Path to a cert file for the certificate authority
25+
--client-certificate string Path to a client certificate file for TLS
26+
--client-key string Path to a client key file for TLS
27+
--cluster string The name of the kubeconfig cluster to use
28+
--context string The name of the kubeconfig context to use
29+
--disable-compression If true, opt-out of response compression for all requests to the server
30+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
31+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
32+
-n, --namespace string If present, the namespace scope for this CLI request
33+
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
34+
-s, --server string The address and port of the Kubernetes API server
35+
--tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
36+
--token string Bearer token for authentication to the API server
37+
--user string The name of the kubeconfig user to use
38+
```
39+
40+
### SEE ALSO
41+
42+
* [runtime-enforcer policy](runtime-enforcer_policy.md) - Manage WorkloadPolicy
43+

0 commit comments

Comments
 (0)