Skip to content

Commit 6530cb3

Browse files
authored
feat: Add docsgen command (#862)
* feat: Add docsgen command * docs: add CLI docs for support-bundle and preflight
1 parent c9b48aa commit 6530cb3

File tree

10 files changed

+247
-0
lines changed

10 files changed

+247
-0
lines changed

Makefile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,11 @@ schemas: fmt vet openapischema
100100
go build ${LDFLAGS} -o bin/schemagen github.com/replicatedhq/troubleshoot/cmd/schemagen
101101
./bin/schemagen --output-dir ./schemas
102102

103+
.PHONY: docs
104+
docs: fmt vet
105+
go build ${LDFLAGS} -o bin/docsgen github.com/replicatedhq/troubleshoot/cmd/docsgen
106+
./bin/docsgen
107+
103108
controller-gen:
104109
go install sigs.k8s.io/controller-tools/cmd/[email protected]
105110
CONTROLLER_GEN=$(shell which controller-gen)

cmd/docsgen/cli/root.go

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
package cli
2+
3+
import (
4+
"log"
5+
"os"
6+
7+
preflightcli "github.com/replicatedhq/troubleshoot/cmd/preflight/cli"
8+
troubleshootcli "github.com/replicatedhq/troubleshoot/cmd/troubleshoot/cli"
9+
"github.com/spf13/cobra"
10+
11+
"github.com/spf13/cobra/doc"
12+
)
13+
14+
func RootCmd() *cobra.Command {
15+
cmd := &cobra.Command{
16+
Use: "docsgen",
17+
Short: "Generate markdown docs for the commands in this project",
18+
}
19+
preflight := preflightcli.RootCmd()
20+
troubleshoot := troubleshootcli.RootCmd()
21+
commands := []*cobra.Command{preflight, troubleshoot}
22+
23+
for _, command := range commands {
24+
err := doc.GenMarkdownTree(command, "./docs")
25+
if err != nil {
26+
log.Fatal(err)
27+
}
28+
}
29+
30+
return cmd
31+
}
32+
33+
func InitAndExecute() {
34+
if err := RootCmd().Execute(); err != nil {
35+
os.Exit(1)
36+
}
37+
}

cmd/docsgen/main.go

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
package main
2+
3+
import (
4+
"github.com/replicatedhq/troubleshoot/cmd/docsgen/cli"
5+
_ "k8s.io/client-go/plugin/pkg/client/auth"
6+
)
7+
8+
func main() {
9+
cli.InitAndExecute()
10+
}

docs/preflight.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
## preflight
2+
3+
Run and retrieve preflight checks in a cluster
4+
5+
### Synopsis
6+
7+
A preflight check is a set of validations that can and should be run to ensure
8+
that a cluster meets the requirements to run an application.
9+
10+
```
11+
preflight [url] [flags]
12+
```
13+
14+
### Options
15+
16+
```
17+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
18+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
19+
--as-uid string UID to impersonate for the operation.
20+
--cache-dir string Default cache directory (default "/Users/xavpaice/.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+
--collect-without-permissions always run preflight checks even if some require permissions that preflight does not have (default true)
26+
--collector-image string the full name of the collector image to use
27+
--collector-pullpolicy string the pull policy of the collector image
28+
--context string The name of the kubeconfig context to use
29+
--debug enable debug logging
30+
--format string output format, one of human, json, yaml. only used when interactive is set to false (default "human")
31+
-h, --help help for preflight
32+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
33+
--interactive interactive preflights (default true)
34+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
35+
-n, --namespace string If present, the namespace scope for this CLI request
36+
-o, --output string specify the output file path for the preflight checks
37+
--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")
38+
--selector string selector (label query) to filter remote collection nodes on.
39+
-s, --server string The address and port of the Kubernetes API server
40+
--since string force pod logs collectors to return logs newer than a relative duration like 5s, 2m, or 3h.
41+
--since-time string force pod logs collectors to return logs after a specific date (RFC3339)
42+
--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
43+
--token string Bearer token for authentication to the API server
44+
--user string The name of the kubeconfig user to use
45+
```
46+
47+
### SEE ALSO
48+
49+
* [preflight version](preflight_version.md) - Print the current version and exit
50+
51+
###### Auto generated by spf13/cobra on 21-Nov-2022

docs/preflight_version.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## preflight version
2+
3+
Print the current version and exit
4+
5+
### Synopsis
6+
7+
Print the current version and exit
8+
9+
```
10+
preflight version [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
-h, --help help for version
17+
```
18+
19+
### Options inherited from parent commands
20+
21+
```
22+
--collect-without-permissions always run preflight checks even if some require permissions that preflight does not have (default true)
23+
--collector-image string the full name of the collector image to use
24+
--collector-pullpolicy string the pull policy of the collector image
25+
--debug enable debug logging
26+
--format string output format, one of human, json, yaml. only used when interactive is set to false (default "human")
27+
--interactive interactive preflights (default true)
28+
-o, --output string specify the output file path for the preflight checks
29+
--selector string selector (label query) to filter remote collection nodes on.
30+
--since string force pod logs collectors to return logs newer than a relative duration like 5s, 2m, or 3h.
31+
--since-time string force pod logs collectors to return logs after a specific date (RFC3339)
32+
```
33+
34+
### SEE ALSO
35+
36+
* [preflight](preflight.md) - Run and retrieve preflight checks in a cluster
37+
38+
###### Auto generated by spf13/cobra on 21-Nov-2022

docs/support-bundle.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## support-bundle
2+
3+
Generate a support bundle
4+
5+
### Synopsis
6+
7+
A support bundle is an archive of files, output, metrics and state
8+
from a server that can be used to assist when troubleshooting a Kubernetes cluster.
9+
10+
```
11+
support-bundle [url] [flags]
12+
```
13+
14+
### Options
15+
16+
```
17+
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
18+
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
19+
--as-uid string UID to impersonate for the operation.
20+
--cache-dir string Default cache directory (default "/Users/xavpaice/.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+
--collect-without-permissions always generate a support bundle, even if it some require additional permissions (default true)
26+
--context string The name of the kubeconfig context to use
27+
--debug enable debug logging
28+
-h, --help help for support-bundle
29+
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
30+
--interactive enable/disable interactive mode (default true)
31+
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
32+
--load-cluster-specs enable/disable loading additional troubleshoot specs found within the cluster. required when no specs are provided on the command line
33+
-n, --namespace string If present, the namespace scope for this CLI request
34+
--no-uri When this flag is used, Troubleshoot does not attempt to retrieve the bundle referenced by the uri: field in the spec.`
35+
-o, --output string specify the output file path for the support bundle
36+
--redact enable/disable default redactions (default true)
37+
--redactors strings names of the additional redactors to use
38+
--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")
39+
-l, --selector strings selector to filter on for loading additional support bundle specs found in secrets within the cluster (default [troubleshoot.io/kind=supportbundle-spec])
40+
-s, --server string The address and port of the Kubernetes API server
41+
--since string force pod logs collectors to return logs newer than a relative duration like 5s, 2m, or 3h.
42+
--since-time string force pod logs collectors to return logs after a specific date (RFC3339)
43+
--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
44+
--token string Bearer token for authentication to the API server
45+
--user string The name of the kubeconfig user to use
46+
```
47+
48+
### SEE ALSO
49+
50+
* [support-bundle analyze](support-bundle_analyze.md) - analyze a support bundle
51+
* [support-bundle version](support-bundle_version.md) - Print the current version and exit
52+
53+
###### Auto generated by spf13/cobra on 21-Nov-2022

docs/support-bundle_analyze.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## support-bundle analyze
2+
3+
analyze a support bundle
4+
5+
### Synopsis
6+
7+
Analyze a support bundle using the Analyzer definitions provided
8+
9+
```
10+
support-bundle analyze [url] [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
--bundle string filename of the support bundle to analyze
17+
-h, --help help for analyze
18+
--output string output format: json, yaml
19+
--quiet enable/disable error messaging and only show parseable output
20+
```
21+
22+
### SEE ALSO
23+
24+
* [support-bundle](support-bundle.md) - Generate a support bundle
25+
26+
###### Auto generated by spf13/cobra on 21-Nov-2022

docs/support-bundle_version.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## support-bundle version
2+
3+
Print the current version and exit
4+
5+
### Synopsis
6+
7+
Print the current version and exit
8+
9+
```
10+
support-bundle version [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
-h, --help help for version
17+
```
18+
19+
### SEE ALSO
20+
21+
* [support-bundle](support-bundle.md) - Generate a support bundle
22+
23+
###### Auto generated by spf13/cobra on 21-Nov-2022

go.mod

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,13 @@ require (
4949

5050
require (
5151
cloud.google.com/go/compute/metadata v0.2.1 // indirect
52+
github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
5253
github.com/emicklei/go-restful/v3 v3.8.0 // indirect
5354
github.com/evanphx/json-patch/v5 v5.6.0 // indirect
5455
github.com/googleapis/enterprise-certificate-proxy v0.2.0 // indirect
5556
github.com/googleapis/go-type-adapters v1.0.0 // indirect
5657
github.com/mistifyio/go-zfs/v3 v3.0.0 // indirect
58+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
5759
github.com/sylabs/sif/v2 v2.8.1 // indirect
5860
)
5961

go.sum

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,7 @@ github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfc
326326
github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
327327
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
328328
github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
329+
github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
329330
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
330331
github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
331332
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -938,6 +939,7 @@ github.com/rogpeppe/go-charset v0.0.0-20180617210344-2471d30d28b4/go.mod h1:qgYe
938939
github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
939940
github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k=
940941
github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
942+
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
941943
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
942944
github.com/safchain/ethtool v0.0.0-20190326074333-42ed695e3de8/go.mod h1:Z0q5wiBQGYcxhMZ6gUqHn6pYNLypFAvaL3UvgZLR0U4=
943945
github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0=

0 commit comments

Comments
 (0)