[GEP-28] Generate CLI reference for gardenadm (gardener#11040)

timebertt · web-flow · commit 52f6464a347f · 2024-12-16T10:56:23.000Z
* Add `cli-reference-generator` tool

* Generate `gardenadm` CLI reference
diff --git a/cmd/gardenadm/main.go b/cmd/gardenadm/main.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
+//go:generate go run ../../hack/tools/cli-reference-generator -O ../../docs/cli-reference/gardenadm gardenadm
+
 package main
 
 import (
diff --git a/docs/README.md b/docs/README.md
@@ -109,6 +109,10 @@
 * [`seedmanagement.gardener.cloud` API Group](api-reference/seedmanagement.md)
 * [`settings.gardener.cloud` API Group](api-reference/settings.md)
 
+## [CLI Reference](cli-reference/README.md)
+
+* [`gardenadm`](cli-reference/gardenadm/gardenadm.md)
+
 ## Gardener Enhancement Proposals
 
 * [GEP: Gardener Enhancement Proposal Description](proposals/README.md)
diff --git a/docs/cli-reference/README.md b/docs/cli-reference/README.md
@@ -0,0 +1,3 @@
+# Gardener CLI Reference
+
+* [`gardenadm`](gardenadm/gardenadm.md)
diff --git a/docs/cli-reference/gardenadm/gardenadm.md b/docs/cli-reference/gardenadm/gardenadm.md
@@ -0,0 +1,20 @@
+## gardenadm
+
+gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
+### Options
+
+```
+  -h, --help   help for gardenadm
+```
+
+### SEE ALSO
+
+* [gardenadm bootstrap](gardenadm_bootstrap.md)	 - Bootstrap the infrastructure for an Autonomous Shoot Cluster
+* [gardenadm connect](gardenadm_connect.md)	 - Deploy a gardenlet for further cluster management
+* [gardenadm discover](gardenadm_discover.md)	 - Conveniently download Gardener configuration resources from an existing garden cluster
+* [gardenadm init](gardenadm_init.md)	 - Bootstrap the first control plane node
+* [gardenadm join](gardenadm_join.md)	 - Bootstrap further control plane nodes or worker nodes and join them to the cluster
+* [gardenadm token](gardenadm_token.md)	 - Manage bootstrap and discovery tokens for gardenadm join
+* [gardenadm version](gardenadm_version.md)	 - Print the client version information
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_bootstrap.md b/docs/cli-reference/gardenadm/gardenadm_bootstrap.md
@@ -0,0 +1,30 @@
+## gardenadm bootstrap
+
+Bootstrap the infrastructure for an Autonomous Shoot Cluster
+
+### Synopsis
+
+Bootstrap the infrastructure for an Autonomous Shoot Cluster (networks, machines, etc.)
+
+```
+gardenadm bootstrap [flags]
+```
+
+### Examples
+
+```
+# Bootstrap the infrastructure
+gardenadm bootstrap --kubeconfig ~/.kube/config
+```
+
+### Options
+
+```
+  -h, --help                help for bootstrap
+  -k, --kubeconfig string   Path to the kubeconfig file pointing to the KinD cluster
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_connect.md b/docs/cli-reference/gardenadm/gardenadm_connect.md
@@ -0,0 +1,29 @@
+## gardenadm connect
+
+Deploy a gardenlet for further cluster management
+
+### Synopsis
+
+Deploy a gardenlet for further cluster management
+
+```
+gardenadm connect [flags]
+```
+
+### Examples
+
+```
+# Deploy a gardenlet
+gardenadm connect
+```
+
+### Options
+
+```
+  -h, --help   help for connect
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_discover.md b/docs/cli-reference/gardenadm/gardenadm_discover.md
@@ -0,0 +1,30 @@
+## gardenadm discover
+
+Conveniently download Gardener configuration resources from an existing garden cluster
+
+### Synopsis
+
+Conveniently download Gardener configuration resources from an existing garden cluster (CloudProfile, ControllerRegistrations, ControllerDeployments, etc.)
+
+```
+gardenadm discover [flags]
+```
+
+### Examples
+
+```
+# Download the configuration
+gardenadm discover --kubeconfig ~/.kube/config
+```
+
+### Options
+
+```
+  -h, --help                help for discover
+  -k, --kubeconfig string   Path to the kubeconfig file pointing to the garden cluster
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_init.md b/docs/cli-reference/gardenadm/gardenadm_init.md
@@ -0,0 +1,29 @@
+## gardenadm init
+
+Bootstrap the first control plane node
+
+### Synopsis
+
+Bootstrap the first control plane node
+
+```
+gardenadm init [flags]
+```
+
+### Examples
+
+```
+# Bootstrap the first control plane node
+gardenadm init
+```
+
+### Options
+
+```
+  -h, --help   help for init
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_join.md b/docs/cli-reference/gardenadm/gardenadm_join.md
@@ -0,0 +1,29 @@
+## gardenadm join
+
+Bootstrap further control plane nodes or worker nodes and join them to the cluster
+
+### Synopsis
+
+Bootstrap further control plane nodes or worker nodes and join them to the cluster
+
+```
+gardenadm join [flags]
+```
+
+### Examples
+
+```
+# Bootstrap a worker node and join it to the cluster
+gardenadm join
+```
+
+### Options
+
+```
+  -h, --help   help for join
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_token.md b/docs/cli-reference/gardenadm/gardenadm_token.md
@@ -0,0 +1,22 @@
+## gardenadm token
+
+Manage bootstrap and discovery tokens for gardenadm join
+
+### Synopsis
+
+Manage bootstrap and discovery tokens for gardenadm join
+
+### Options
+
+```
+  -h, --help   help for token
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+* [gardenadm token create](gardenadm_token_create.md)	 - Create a bootstrap token on the server
+* [gardenadm token delete](gardenadm_token_delete.md)	 - Delete a bootstrap token on the server
+* [gardenadm token generate](gardenadm_token_generate.md)	 - Generate a random bootstrap token
+* [gardenadm token list](gardenadm_token_list.md)	 - List all bootstrap tokens on the server
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_token_create.md b/docs/cli-reference/gardenadm/gardenadm_token_create.md
@@ -0,0 +1,32 @@
+## gardenadm token create
+
+Create a bootstrap token on the server
+
+### Synopsis
+
+The [token] is the actual token to write.This should be a securely generated random token of the form "[a-z0-9]{6}.[a-z0-9]{16}".If no [token] is given, gardenadm will generate a random token instead.
+
+```
+gardenadm token create [token] [flags]
+```
+
+### Examples
+
+```
+# Create a bootstrap token with id "foo123" on the server
+gardenadm token create foo123.bar4567890baz123
+
+# Create a bootstrap token generated randomly
+gardenadm token create
+```
+
+### Options
+
+```
+  -h, --help   help for create
+```
+
+### SEE ALSO
+
+* [gardenadm token](gardenadm_token.md)	 - Manage bootstrap and discovery tokens for gardenadm join
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_token_delete.md b/docs/cli-reference/gardenadm/gardenadm_token_delete.md
@@ -0,0 +1,29 @@
+## gardenadm token delete
+
+Delete a bootstrap token on the server
+
+### Synopsis
+
+This command will delete a bootstrap token for you.The [token-id] is the ID of the token of the form "[a-z0-9]{6}" to delete
+
+```
+gardenadm token delete [token-id] [flags]
+```
+
+### Examples
+
+```
+# Delete a bootstrap token with id "foo123" on the server
+gardenadm token delete foo123
+```
+
+### Options
+
+```
+  -h, --help   help for delete
+```
+
+### SEE ALSO
+
+* [gardenadm token](gardenadm_token.md)	 - Manage bootstrap and discovery tokens for gardenadm join
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_token_generate.md b/docs/cli-reference/gardenadm/gardenadm_token_generate.md
@@ -0,0 +1,29 @@
+## gardenadm token generate
+
+Generate a random bootstrap token
+
+### Synopsis
+
+Generate a random bootstrap token
+
+```
+gardenadm token generate [flags]
+```
+
+### Examples
+
+```
+# Generate a random bootstrap token
+gardenadm token generate
+```
+
+### Options
+
+```
+  -h, --help   help for generate
+```
+
+### SEE ALSO
+
+* [gardenadm token](gardenadm_token.md)	 - Manage bootstrap and discovery tokens for gardenadm join
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_token_list.md b/docs/cli-reference/gardenadm/gardenadm_token_list.md
@@ -0,0 +1,29 @@
+## gardenadm token list
+
+List all bootstrap tokens on the server
+
+### Synopsis
+
+List all bootstrap tokens on the server
+
+```
+gardenadm token list [flags]
+```
+
+### Examples
+
+```
+# List all bootstrap tokens on the server
+gardenadm token list
+```
+
+### Options
+
+```
+  -h, --help   help for list
+```
+
+### SEE ALSO
+
+* [gardenadm token](gardenadm_token.md)	 - Manage bootstrap and discovery tokens for gardenadm join
+
diff --git a/docs/cli-reference/gardenadm/gardenadm_version.md b/docs/cli-reference/gardenadm/gardenadm_version.md
@@ -0,0 +1,22 @@
+## gardenadm version
+
+Print the client version information
+
+### Synopsis
+
+Print the client version information
+
+```
+gardenadm version [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for version
+```
+
+### SEE ALSO
+
+* [gardenadm](gardenadm.md)	 - gardenadm bootstraps and manages autonomous shoot clusters in the Gardener project.
+
diff --git a/go.mod b/go.mod
@@ -112,6 +112,7 @@ require (
 	github.com/containerd/ttrpc v1.2.5 // indirect
 	github.com/containerd/typeurl/v2 v2.1.1 // indirect
 	github.com/coreos/go-semver v0.3.1 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/cyphar/filepath-securejoin v0.3.4 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dgryski/go-jump v0.0.0-20211018200510-ba001c3ffce0 // indirect
diff --git a/go.sum b/go.sum
@@ -115,6 +115,7 @@ github.com/coreos/go-semver v0.3.1/go.mod h1:irMmmIw/7yzSRPWryHsK7EYSg09caPQL03V
 github.com/coreos/go-systemd/v22 v22.5.0 h1:RrqgGjYQKalulkV8NGVIfkXQf6YYmOyiJKk8iXXhfZs=
 github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
 github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/cyphar/filepath-securejoin v0.3.4 h1:VBWugsJh2ZxJmLFSM06/0qzQyiQX2Qs0ViKrUAcqdZ8=
diff --git a/hack/clean.sh b/hack/clean.sh
@@ -22,3 +22,7 @@ done
 if [ -d "$PWD/docs/api-reference" ]; then
   find ./docs/api-reference/ -type f -name "*.md" ! -name "README.md" -exec rm '{}' \;
 fi
+
+if [ -d "$PWD/docs/cli-reference" ]; then
+  find ./docs/cli-reference/ -type f -name "*.md" ! -name "README.md" -exec rm '{}' \;
+fi
diff --git a/hack/tools/cli-reference-generator/main.go b/hack/tools/cli-reference-generator/main.go

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Gardener CLI Reference`
	`2`	`+`
	`3`	+* [`gardenadm`](gardenadm/gardenadm.md)