From 12720a7b08ffcdeb3c1aa1836e47d14027bfcaf1 Mon Sep 17 00:00:00 2001 From: jpgouin Date: Wed, 26 Feb 2025 19:56:24 +0000 Subject: [PATCH] generate automatically the k3k cli doc, update readme and advanced-usage doc --- README.md | 2 +- docs/advanced-usage.md | 34 +++++++- docs/cli.md | 184 ----------------------------------------- docs/cli/Makefile | 4 + docs/cli/cli-docs.md | 98 ++++++++++++++++++++++ docs/cli/genclidoc.go | 40 +++++++++ 6 files changed, 176 insertions(+), 186 deletions(-) delete mode 100644 docs/cli.md create mode 100644 docs/cli/Makefile create mode 100644 docs/cli/cli-docs.md create mode 100644 docs/cli/genclidoc.go diff --git a/README.md b/README.md index 5811b68e..7f38d0e6 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ This section provides instructions on how to install K3k and the `k3kcli`. * An existing [RKE2](https://docs.rke2.io/install/quickstart) Kubernetes cluster (recommended). * A configured storage provider with a default storage class. -**Note:** If you do not have a storage provider, you can configure the cluster to use ephemeral or static storage. Please consult the [CLI documentation](./docs/cli.md#examples-for-no-storage-provider) for instructions on using these options. +**Note:** If you do not have a storage provider, you can configure the cluster to use ephemeral or static storage. Please consult the [k3kcli advance usage](./docs/advanced-usage.md#using-the-cli) for instructions on using these options. ### Install the K3k controller diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index dfd220eb..6d30e6ab 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -6,7 +6,7 @@ This document provides advanced usage information for k3k, including detailed us The `Cluster` resource provides a variety of fields for customizing the behavior of your virtual clusters. You can check the [CRD documentation](./crds/crd-docs.md) for the full specs. -**Note:** Most of these customization options can also be configured using the `k3kcli` tool. Refer to the `k3kcli` documentation for more details. +**Note:** Most of these customization options can also be configured using the `k3kcli` tool. Refer to the [k3kcli](./cli/cli-docs.md) documentation for more details. @@ -112,3 +112,35 @@ The `clusterDNS` field specifies the IP address for the CoreDNS service. It need ### `serverArgs` The `serverArgs` field allows you to specify additional arguments to be passed to the K3s server pods. + +## Using the cli + +You can check the [k3kcli documentation](./cli/cli-docs.md) for the full specs. + +### Examples for no storage provider: + +* Ephemeral Storage: + + ```bash + + k3kcli cluster create my-cluster --persistence-type ephemeral + + ``` + +* Static Storage (Requires pre-provisioned PVs): + + ```bash + + k3kcli cluster create my-cluster --persistence-type static + + ``` + + (You will need to ensure that persistent volumes that match the requirements of your k3k cluster exist before creation) + +*Important Notes:* + +* When using `--persistence-type static`, you must manually create PersistentVolumes (PVs) that match the storage requirements of your K3K cluster. + +* Using `--persistence-type ephemeral` will result in data loss if the nodes are restarted. + +* It is highly recommended to use `--persistence-type dynamic` with a configured storage class. \ No newline at end of file diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index 9f1a6277..00000000 --- a/docs/cli.md +++ /dev/null @@ -1,184 +0,0 @@ -# K3K CLI Documentation - -The k3kcli command-line interface is used to manage K3K clusters. - -```bash - -k3kcli [global options] command [command options] - -``` - -*Version:* - -```bash - -v0.3.0 - -``` - -*Commands:* - -* cluster: Cluster management commands. - -* kubeconfig: Manage kubeconfig files for clusters. - -* help, h: Display help information. - - -*Global Options:* - -* --debug: Enable debug logging. (Default: false) ($K3K_DEBUG) - -* --help, -h: Display help information. - -* --version, -v: Display the version. - -## Cluster Command: - -```bash - -k3kcli cluster command [command options] - -``` - -*Cluster Subcommands:* - -* create: Create a new cluster. - -* delete: Delete an existing cluster. - -* help, h: Display help information. - -*Cluster Create Command:* - -```bash - -k3kcli cluster create [command options] NAME - -``` - -*Cluster Create Options:* - -* --kubeconfig value: Path to the kubeconfig file. (Default: "/home/jpgouin/.kube/config") ($KUBECONFIG) - -* --namespace value: Namespace to create the K3K cluster in. - -* --servers value: Number of server nodes. (Default: 1) - -* --agents value: Number of agent nodes. (Default: 0) - -* --token value: Cluster token. - -* --cluster-cidr value: Cluster CIDR. - -* --service-cidr value: Service CIDR. - -* --persistence-type value: Persistence mode for nodes: ephemeral, static, or dynamic. (Default: "dynamic") - - * ephemeral: Nodes will lose data upon restart. - - * static: Requires pre-provisioned persistent volumes. - - * dynamic: Uses a storage class to dynamically provision persistent volumes. - -* --storage-class-name value: Storage class name for dynamic persistence. - -* --server-args value [ --server-args value ]: Extra arguments for server nodes. - -* --agent-args value [ --agent-args value ]: Extra arguments for agent nodes. - -* --version value: K3s version. - -* --mode value: K3K mode: shared or isolated. (Default: "shared") - -* --kubeconfig-server value: Override the kubeconfig server host. - -* --help, -h: Display help information. - -*Cluster Delete Command:* - -```bash - -k3kcli cluster delete [command options] NAME - -``` - -*Cluster Delete Options:* - -* --kubeconfig value: Path to the kubeconfig file. (Default: "/home/jpgouin/.kube/config") ($KUBECONFIG) - -* --namespace value: Namespace of the K3K cluster. - -* --help, -h: Display help information. - -## Kubeconfig Command: - -```bash - -k3kcli kubeconfig command [command options] - -``` - -*Kubeconfig Subcommands:* - -* generate: Generate kubeconfig for clusters. - -* help, h: Display help information. - -*Kubeconfig Generate Command:* - -```bash - -k3kcli kubeconfig generate [command options] - -``` - -*Kubeconfig Generate Options:* - -* --kubeconfig value: Path to the kubeconfig file. (Default: "/home/jpgouin/.kube/config") ($KUBECONFIG) - -* --namespace value: Namespace of the K3K cluster. - -* --name value: Cluster name. - -* --config-name value: The name of the generated kubeconfig file. - -* --cn value: Common name (CN) of the generated certificates for the kubeconfig. (Default: "system:admin") - -* --org value [ --org value ]: Organization name (ORG) of the generated certificates for the kubeconfig. - -* --altNames value [ --altNames value ]: altNames of the generated certificates for the kubeconfig. - -* --expiration-days value: Expiration date of the certificates used for the kubeconfig. (Default: 356) - -* --kubeconfig-server value: Override the kubeconfig server host. - -* --help, -h: Display help information. - -## Examples for no storage provider: - -* Ephemeral Storage: - - ```bash - - k3kcli cluster create my-cluster --persistence-type ephemeral - - ``` - -* Static Storage (Requires pre-provisioned PVs): - - ```bash - - k3kcli cluster create my-cluster --persistence-type static - - ``` - - (You will need to ensure that persistent volumes that match the requirements of your k3k cluster exist before creation) - -*Important Notes:* - -* When using `--persistence-type static`, you must manually create PersistentVolumes (PVs) that match the storage requirements of your K3K cluster. - -* Using `--persistence-type ephemeral` will result in data loss if the nodes are restarted. - -* It is highly recommended to use `--persistence-type dynamic` with a configured storage class. diff --git a/docs/cli/Makefile b/docs/cli/Makefile new file mode 100644 index 00000000..08d092cc --- /dev/null +++ b/docs/cli/Makefile @@ -0,0 +1,4 @@ +.PHONY: gendoc + +gendoc: + @go run ./genclidoc.go diff --git a/docs/cli/cli-docs.md b/docs/cli/cli-docs.md new file mode 100644 index 00000000..1d3a75b2 --- /dev/null +++ b/docs/cli/cli-docs.md @@ -0,0 +1,98 @@ +# NAME + +k3kcli - CLI for K3K + +# SYNOPSIS + +k3kcli + +``` +[--debug] +``` + +**Usage**: + +``` +k3kcli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] +``` + +# GLOBAL OPTIONS + +**--debug**: Turn on debug logs + + +# COMMANDS + +## cluster + +cluster command + +### create + +Create new cluster + +>k3kcli cluster create [command options] NAME + +**--agent-args**="": agents extra arguments + +**--agents**="": number of agents (default: 0) + +**--cluster-cidr**="": cluster CIDR + +**--kubeconfig**="": kubeconfig path (default: "/home/jpgouin/.kube/config") + +**--kubeconfig-server**="": override the kubeconfig server host + +**--mode**="": k3k mode type (shared, virtual) (default: "shared") + +**--namespace**="": namespace to create the k3k cluster in + +**--persistence-type**="": persistence mode for the nodes (ephemeral, static, dynamic) (default: "dynamic") + +**--server-args**="": servers extra arguments + +**--servers**="": number of servers (default: 1) + +**--service-cidr**="": service CIDR + +**--storage-class-name**="": storage class name for dynamic persistence type + +**--token**="": token of the cluster + +**--version**="": k3s version + +### delete + +Delete an existing cluster + +>k3kcli cluster delete [command options] NAME + +**--kubeconfig**="": kubeconfig path (default: "/home/jpgouin/.kube/config") + +**--namespace**="": namespace to create the k3k cluster in + +## kubeconfig + +Manage kubeconfig for clusters + +### generate + +Generate kubeconfig for clusters + +**--altNames**="": altNames of the generated certificates for the kubeconfig + +**--cn**="": Common name (CN) of the generated certificates for the kubeconfig (default: "system:admin") + +**--config-name**="": the name of the generated kubeconfig file + +**--expiration-days**="": Expiration date of the certificates used for the kubeconfig (default: 356) + +**--kubeconfig**="": kubeconfig path (default: "/home/jpgouin/.kube/config") + +**--kubeconfig-server**="": override the kubeconfig server host + +**--name**="": cluster name + +**--namespace**="": namespace to create the k3k cluster in + +**--org**="": Organization name (ORG) of the generated certificates for the kubeconfig diff --git a/docs/cli/genclidoc.go b/docs/cli/genclidoc.go new file mode 100644 index 00000000..e7ea8271 --- /dev/null +++ b/docs/cli/genclidoc.go @@ -0,0 +1,40 @@ +package main + +import ( + "fmt" + "os" + + "github.com/rancher/k3k/cli/cmds" + "github.com/rancher/k3k/cli/cmds/cluster" + "github.com/rancher/k3k/cli/cmds/kubeconfig" + "github.com/rancher/k3k/pkg/buildinfo" + "github.com/urfave/cli/v2" +) + +func main() { + // Instantiate the CLI application + app := cmds.NewApp() + app.Version = buildinfo.Version + cli.VersionPrinter = func(cCtx *cli.Context) { + fmt.Println("k3kcli Version: " + buildinfo.Version) + } + + app.Commands = []*cli.Command{ + cluster.NewCommand(), + kubeconfig.NewCommand(), + } + + // Generate the Markdown documentation + md, err := app.ToMarkdown() + if err != nil { + fmt.Println("Error generating documentation:", err) + os.Exit(1) + } + err = os.WriteFile("./cli-docs.md", []byte(md), 0644) + if err != nil { + fmt.Println("Error generating documentation:", err) + os.Exit(1) + } + + fmt.Println("Documentation generated at docs/cli/cli-docs.md") +} \ No newline at end of file