From 6c7680876de6de5b01dd199f5077d17371815467 Mon Sep 17 00:00:00 2001 From: Anuj Chaudhari Date: Fri, 4 Oct 2024 14:18:17 -0700 Subject: [PATCH] Add generate-docs and Update the command docs (#822) Signed-off-by: Anuj Chaudhari --- Makefile | 5 +- docs/cli/commands/tanzu.md | 4 +- docs/cli/commands/tanzu_completion.md | 36 +++++++++---- docs/cli/commands/tanzu_config.md | 2 +- docs/cli/commands/tanzu_context.md | 5 +- docs/cli/commands/tanzu_context_create.md | 23 +++++++-- docs/cli/commands/tanzu_context_current.md | 19 +++++++ docs/cli/commands/tanzu_context_list.md | 1 + docs/cli/commands/tanzu_context_unset.md | 2 +- docs/cli/commands/tanzu_login.md | 50 +++++++++++++++++++ docs/cli/commands/tanzu_plugin.md | 2 +- .../commands/tanzu_plugin_download-bundle.md | 19 +++++-- docs/cli/commands/tanzu_plugin_list.md | 2 +- docs/cli/commands/tanzu_plugin_source_init.md | 4 ++ .../commands/tanzu_plugin_source_update.md | 4 ++ docs/cli/commands/tanzu_version.md | 2 +- 16 files changed, 150 insertions(+), 30 deletions(-) create mode 100644 docs/cli/commands/tanzu_context_current.md create mode 100644 docs/cli/commands/tanzu_login.md diff --git a/Makefile b/Makefile index bcc11d41d..714a346bf 100644 --- a/Makefile +++ b/Makefile @@ -367,7 +367,10 @@ generate-controller-code: $(CONTROLLER_GEN) ## Generate code via controller-gen generate-manifests: ## Generate API manifests e.g. CRD $(MAKE) generate-controller-code GENERATOR=crd OPTIONS="output:crd:artifacts:config=$(ROOT_DIR)/apis/config/crd/bases" CONTROLLER_GEN_SRC=$(CONTROLLER_GEN_SRC) -generate: generate-controller-code generate-manifests ## Generate controller code and manifests e.g. CRD etc. +generate-docs: build + HOME=${TMPDIR}/tanzu-doc-gen TANZU_CLI_CEIP_OPT_IN_PROMPT_ANSWER=no TANZU_CLI_EULA_PROMPT_ANSWER=yes TANZU_CLI_ESSENTIALS_PLUGIN_GROUP_VERSION=unused ./bin/tanzu generate-all-docs; rm -rf ${TMPDIR}/tanzu-doc-gen + +generate: generate-controller-code generate-manifests generate-docs ## Generate controller code, manifests (e.g. CRD etc.) and CLI docs ## -------------------------------------- ## Tooling Binaries diff --git a/docs/cli/commands/tanzu.md b/docs/cli/commands/tanzu.md index ddf2d640e..77c9539d8 100644 --- a/docs/cli/commands/tanzu.md +++ b/docs/cli/commands/tanzu.md @@ -1,6 +1,6 @@ ## tanzu - +The Tanzu CLI ### Options @@ -13,7 +13,7 @@ * [tanzu completion](tanzu_completion.md) - Output shell completion code * [tanzu config](tanzu_config.md) - Configuration for the CLI * [tanzu context](tanzu_context.md) - Configure and manage contexts for the Tanzu CLI -* [tanzu init](tanzu_init.md) - Initialize the CLI +* [tanzu login](tanzu_login.md) - Login to Tanzu Platform for Kubernetes * [tanzu plugin](tanzu_plugin.md) - Manage CLI plugins * [tanzu version](tanzu_version.md) - Version information diff --git a/docs/cli/commands/tanzu_completion.md b/docs/cli/commands/tanzu_completion.md index 1a845f817..bfa2ad804 100644 --- a/docs/cli/commands/tanzu_completion.md +++ b/docs/cli/commands/tanzu_completion.md @@ -4,8 +4,7 @@ Output shell completion code ### Synopsis - -Output shell completion code for the specified shell [bash zsh fish powershell]. +Output shell completion code for the specified shell (bash, zsh, fish, powershell). The shell completion code must be evaluated to provide completion. See Examples for how to perform this for your given shell. @@ -13,7 +12,7 @@ for how to perform this for your given shell. Note for bash users: make sure the bash-completions package has been installed. ``` -tanzu completion [bash zsh fish powershell] +tanzu completion [bash|zsh|fish|powershell] ``` ### Examples @@ -26,29 +25,40 @@ tanzu completion [bash zsh fish powershell] source <(tanzu completion bash) ## Load for all new sessions: - tanzu completion bash > $HOME/.config/tanzu/completion.bash.inc - printf "\n# Tanzu shell completion\nsource '$HOME/.config/tanzu/completion.bash.inc'\n" >> $HOME/.bash_profile + tanzu completion bash > $HOME/.config/tanzu/completion.bash.inc + printf "\n# Tanzu shell completion\nsource '$HOME/.config/tanzu/completion.bash.inc'\n" >> $HOME/.bashrc + + ## NOTE: the bash-completion OS package must also be installed. - ## NOTE: the bash-completion package must be installed. + ## If you invoke the 'tanzu' command using a different name or an alias such as, + ## for example, 'tz', you must also include the following in your $HOME/.bashrc + complete -o default -F __start_tanzu tz # Zsh instructions: ## Load only for current session: autoload -U compinit; compinit source <(tanzu completion zsh) - compdef _tanzu tanzu ## Load for all new sessions: - echo "autoload -U compinit; compinit" >> ~/.zshrc + echo "autoload -U compinit; compinit" >> $HOME/.zshrc tanzu completion zsh > "${fpath[1]}/_tanzu" + ## Aliases are handled automatically, but if you have renamed the actual 'tanzu' binary to, + ## for example, 'tz', you must also include the following in your $HOME/.zshrc + compdef _tanzu tz + # Fish instructions: ## Load only for current session: tanzu completion fish | source ## Load for all new sessions: - tanzu completion fish > ~/.config/fish/completions/tanzu.fish + tanzu completion fish > $HOME/.config/fish/completions/tanzu.fish + + ## Aliases are handled automatically, but if you have renamed the actual 'tanzu' binary to, + ## for example, 'tz', you must also include the following in your $HOME/.config/fish/config.fish + complete --command tz --wraps tanzu # Powershell instructions: @@ -56,7 +66,11 @@ tanzu completion [bash zsh fish powershell] tanzu completion powershell | Out-String | Invoke-Expression ## Load for all new sessions: - Add the output of the above command to your powershell profile. + printf "\n# Tanzu shell completion\ntanzu completion powershell | Out-String | Invoke-Expression" >> $PROFILE + + ## If you invoke the 'tanzu' command using a different name or an alias such as, + ## for example, 'tz', you must also include the following in your powershell $PROFILE. + Register-ArgumentCompleter -CommandName 'tz' -ScriptBlock ${__tanzuCompleterBlock} ``` ### Options @@ -67,5 +81,5 @@ tanzu completion [bash zsh fish powershell] ### SEE ALSO -* [tanzu](tanzu.md) - +* [tanzu](tanzu.md) - The Tanzu CLI diff --git a/docs/cli/commands/tanzu_config.md b/docs/cli/commands/tanzu_config.md index fbf77b6ba..3895e1016 100644 --- a/docs/cli/commands/tanzu_config.md +++ b/docs/cli/commands/tanzu_config.md @@ -10,7 +10,7 @@ Configuration for the CLI ### SEE ALSO -* [tanzu](tanzu.md) - +* [tanzu](tanzu.md) - The Tanzu CLI * [tanzu config cert](tanzu_config_cert.md) - Manage certificate configuration of hosts * [tanzu config eula](tanzu_config_eula.md) - Manage EULA acceptance * [tanzu config get](tanzu_config_get.md) - Get the current configuration diff --git a/docs/cli/commands/tanzu_context.md b/docs/cli/commands/tanzu_context.md index 7bd82476b..de422f756 100644 --- a/docs/cli/commands/tanzu_context.md +++ b/docs/cli/commands/tanzu_context.md @@ -10,11 +10,12 @@ Configure and manage contexts for the Tanzu CLI ### SEE ALSO -* [tanzu](tanzu.md) - +* [tanzu](tanzu.md) - The Tanzu CLI * [tanzu context create](tanzu_context_create.md) - Create a Tanzu CLI context +* [tanzu context current](tanzu_context_current.md) - Display the current context * [tanzu context delete](tanzu_context_delete.md) - Delete a context from the config * [tanzu context get](tanzu_context_get.md) - Display a context from the config * [tanzu context list](tanzu_context_list.md) - List contexts -* [tanzu context unset](tanzu_context_unset.md) - Unset the active context so that it is not used by default. +* [tanzu context unset](tanzu_context_unset.md) - Unset the active context so that it is not used by default * [tanzu context use](tanzu_context_use.md) - Set the context to be used by default diff --git a/docs/cli/commands/tanzu_context_create.md b/docs/cli/commands/tanzu_context_create.md index 777439687..e306b62aa 100644 --- a/docs/cli/commands/tanzu_context_create.md +++ b/docs/cli/commands/tanzu_context_create.md @@ -28,18 +28,33 @@ tanzu context create CONTEXT_NAME [flags] # Create a TKG management cluster context using default kubeconfig path and a kubeconfig context tanzu context create mgmt-cluster --kubecontext kubecontext - # Create an Tanzu context with the default endpoint (--type is not necessary for the default endpoint) + # Create a TMC(mission-control) context using endpoint and type + tanzu context create mytmc --endpoint tmc.example.com:443 --type tmc + + # Create a Tanzu context with the default endpoint (--type is not necessary for the default endpoint) tanzu context create mytanzu --endpoint https://api.tanzu.cloud.vmware.com - # Create an Tanzu context (--type is needed for a non-default endpoint) + # Create a Tanzu context (--type is needed for a non-default endpoint) tanzu context create mytanzu --endpoint https://non-default.tanzu.endpoint.com --type tanzu - # Create an Tanzu context by using the provided CA Bundle for TLS verification: + # Create a Tanzu context by using the provided CA Bundle for TLS verification: tanzu context create mytanzu --endpoint https://api.tanzu.cloud.vmware.com --endpoint-ca-certificate /path/to/ca/ca-cert - # Create an Tanzu context but skipping TLS verification (this is insecure): + # Create a Tanzu context but skip TLS verification (this is insecure): tanzu context create mytanzu --endpoint https://api.tanzu.cloud.vmware.com --insecure-skip-tls-verify + Notes: + 1. TMC context: To create Mission Control (TMC) context an API Key is required. It can be provided using the + TANZU_API_TOKEN environment variable or entered during context creation. + 2. Tanzu context: To create Tanzu context an API Key is optional. If provided using the TANZU_API_TOKEN environment + variable, it will be used. Otherwise, the CLI will attempt to log in interactively to the user's default Cloud Services + organization. You can override or choose a custom organization by setting the TANZU_CLI_CLOUD_SERVICES_ORGANIZATION_ID + environment variable with the custom organization ID value. More information regarding organizations in Cloud Services + and how to obtain the organization ID can be found at + https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html + Also, more information on creating tanzu context and using interactive login in terminal based hosts (without browser) can be found at + https://github.com/vmware-tanzu/tanzu-cli/blob/main/docs/quickstart/quickstart.md#creating-and-connecting-to-a-new-context + [*] : Users have two options to create a kubernetes cluster context. They can choose the control plane option by providing 'endpoint', or use the kubeconfig for the cluster by providing 'kubeconfig' and 'context'. If only '--context' is set and '--kubeconfig' is not, the diff --git a/docs/cli/commands/tanzu_context_current.md b/docs/cli/commands/tanzu_context_current.md new file mode 100644 index 000000000..b016810a4 --- /dev/null +++ b/docs/cli/commands/tanzu_context_current.md @@ -0,0 +1,19 @@ +## tanzu context current + +Display the current context + +``` +tanzu context current [flags] +``` + +### Options + +``` + -h, --help help for current + --short prints the context in compact form +``` + +### SEE ALSO + +* [tanzu context](tanzu_context.md) - Configure and manage contexts for the Tanzu CLI + diff --git a/docs/cli/commands/tanzu_context_list.md b/docs/cli/commands/tanzu_context_list.md index b300fda45..7a420af66 100644 --- a/docs/cli/commands/tanzu_context_list.md +++ b/docs/cli/commands/tanzu_context_list.md @@ -13,6 +13,7 @@ tanzu context list [flags] -h, --help help for list -o, --output string output format: table|yaml|json (default "table") -t, --type string list only contexts associated with the specified context-type (kubernetes[k8s]/mission-control[tmc]/tanzu) + --wide display additional columns for the contexts ``` ### SEE ALSO diff --git a/docs/cli/commands/tanzu_context_unset.md b/docs/cli/commands/tanzu_context_unset.md index 15866e3da..5cc7b056b 100644 --- a/docs/cli/commands/tanzu_context_unset.md +++ b/docs/cli/commands/tanzu_context_unset.md @@ -1,6 +1,6 @@ ## tanzu context unset -Unset the active context so that it is not used by default. +Unset the active context so that it is not used by default ``` tanzu context unset CONTEXT_NAME [flags] diff --git a/docs/cli/commands/tanzu_login.md b/docs/cli/commands/tanzu_login.md new file mode 100644 index 000000000..ce41f6768 --- /dev/null +++ b/docs/cli/commands/tanzu_login.md @@ -0,0 +1,50 @@ +## tanzu login + +Login to Tanzu Platform for Kubernetes + +``` +tanzu login [flags] +``` + +### Examples + +``` + + # Login to Tanzu + tanzu login + + # Login to Tanzu using non-default endpoint + tanzu login --endpoint "https://login.example.com" + + # Login to Tanzu by using the provided CA Bundle for TLS verification + tanzu login --endpoint https://test.example.com[:port] --endpoint-ca-certificate /path/to/ca/ca-cert + + # Login to Tanzu by explicit request to skip TLS verification (this is insecure) + tanzu login --endpoint https://test.example.com[:port] --insecure-skip-tls-verify + + Note: + To login to Tanzu an API Key is optional. If provided using the TANZU_API_TOKEN environment + variable, it will be used. Otherwise, the CLI will attempt to log in interactively to the user's default Cloud Services + organization. You can override or choose a custom organization by setting the TANZU_CLI_CLOUD_SERVICES_ORGANIZATION_ID + environment variable with the custom organization ID value. More information regarding organizations in Cloud Services + and how to obtain the organization ID can be found at + https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html + Also, more information on logging into Tanzu Platform Platform for Kubernetes and using + interactive login in terminal based hosts (without browser) can be found at + https://github.com/vmware-tanzu/tanzu-cli/blob/main/docs/quickstart/quickstart.md#logging-into-tanzu-platform-for-kubernetes + +``` + +### Options + +``` + --endpoint string endpoint to login to (default "https://api.tanzu.cloud.vmware.com") + --endpoint-ca-certificate string path to the endpoint public certificate + -h, --help help for login + --insecure-skip-tls-verify skip endpoint's TLS certificate verification +``` + +### SEE ALSO + +* [tanzu](tanzu.md) - The Tanzu CLI + diff --git a/docs/cli/commands/tanzu_plugin.md b/docs/cli/commands/tanzu_plugin.md index e2b7214ad..755ba4dd6 100644 --- a/docs/cli/commands/tanzu_plugin.md +++ b/docs/cli/commands/tanzu_plugin.md @@ -14,7 +14,7 @@ Provides all lifecycle operations for plugins ### SEE ALSO -* [tanzu](tanzu.md) - +* [tanzu](tanzu.md) - The Tanzu CLI * [tanzu plugin clean](tanzu_plugin_clean.md) - Clean the plugins * [tanzu plugin describe](tanzu_plugin_describe.md) - Describe a plugin * [tanzu plugin download-bundle](tanzu_plugin_download-bundle.md) - Download plugin bundle to the local system diff --git a/docs/cli/commands/tanzu_plugin_download-bundle.md b/docs/cli/commands/tanzu_plugin_download-bundle.md index 4d56ac113..24d25ce38 100644 --- a/docs/cli/commands/tanzu_plugin_download-bundle.md +++ b/docs/cli/commands/tanzu_plugin_download-bundle.md @@ -16,7 +16,14 @@ tanzu plugin download-bundle [flags] ``` # Download a plugin bundle for a specific group version from the default discovery source - tanzu plugin download-bundle --to-tar /tmp/plugin_bundle_vmware_tkg_default_v1.0.0.tar.gz --group vmware-tkg/default:v1.0.0 + tanzu plugin download-bundle --group vmware-tkg/default:v1.0.0 --to-tar /tmp/plugin_bundle_vmware_tkg_default_v1.0.0.tar.gz + + # To download plugin bundle with a specific plugin from the default discovery source + # --plugin name : Downloads the latest available version of the plugin. (Returns an error if the specified plugin name is available across multiple targets) + # --plugin name:version : Downloads the specified version of the plugin. (Returns an error if the specified plugin name is available across multiple targets) + # --plugin name@target:version : Downloads the specified version of the plugin for the specified target. + # --plugin name@target : Downloads the latest available version of the plugin for the specified target. + tanzu plugin download-bundle --plugin cluster:v1.0.0 --to-tar /tmp/plugin_bundle_cluster.tar.gz # Download a plugin bundle with the entire plugin repository from a custom discovery source tanzu plugin download-bundle --image custom.registry.vmware.com/tkg/tanzu-plugins/plugin-inventory:latest --to-tar /tmp/plugin_bundle_complete.tar.gz @@ -25,10 +32,12 @@ tanzu plugin download-bundle [flags] ### Options ``` - --group strings only download the plugins specified in the plugin-group version (can specify multiple) - -h, --help help for download-bundle - --image string URI of the plugin discovery image providing the plugins (default "projects.packages.broadcom.com/tanzu_cli/plugins/plugin-inventory:latest") - --to-tar string local tar file path to store the plugin images + --group strings only download the plugins specified in the plugin-group version (can specify multiple) + -h, --help help for download-bundle + --image string URI of the plugin discovery image providing the plugins (default "projects.packages.broadcom.com/tanzu_cli/plugins/plugin-inventory:latest") + --plugin strings only download plugins matching specified pluginID. Format: name/name:version/name@target:version (can specify multiple) + --refresh-configuration-only only refresh the central configuration data + --to-tar string local tar file path to store the plugin images ``` ### SEE ALSO diff --git a/docs/cli/commands/tanzu_plugin_list.md b/docs/cli/commands/tanzu_plugin_list.md index 1a35b5949..170bdccd0 100644 --- a/docs/cli/commands/tanzu_plugin_list.md +++ b/docs/cli/commands/tanzu_plugin_list.md @@ -4,7 +4,7 @@ List installed plugins ### Synopsis -List installed standalone plugins or plugins recommended by the contexts being used +List installed plugins and plugins recommended by the active contexts ``` tanzu plugin list [flags] diff --git a/docs/cli/commands/tanzu_plugin_source_init.md b/docs/cli/commands/tanzu_plugin_source_init.md index 882338755..78bcc5653 100644 --- a/docs/cli/commands/tanzu_plugin_source_init.md +++ b/docs/cli/commands/tanzu_plugin_source_init.md @@ -2,6 +2,10 @@ Initialize the discovery source to its default value +### Synopsis + +Initialize the discovery source to its default value and refresh the plugin inventory local cache + ``` tanzu plugin source init ``` diff --git a/docs/cli/commands/tanzu_plugin_source_update.md b/docs/cli/commands/tanzu_plugin_source_update.md index 496ad69c7..a9c86872d 100644 --- a/docs/cli/commands/tanzu_plugin_source_update.md +++ b/docs/cli/commands/tanzu_plugin_source_update.md @@ -2,6 +2,10 @@ Update a discovery source configuration +### Synopsis + +Update a discovery source configuration and refresh the plugin inventory local cache + ``` tanzu plugin source update SOURCE_NAME --uri ``` diff --git a/docs/cli/commands/tanzu_version.md b/docs/cli/commands/tanzu_version.md index 3ba90dbfc..3eba33a94 100644 --- a/docs/cli/commands/tanzu_version.md +++ b/docs/cli/commands/tanzu_version.md @@ -14,5 +14,5 @@ tanzu version [flags] ### SEE ALSO -* [tanzu](tanzu.md) - +* [tanzu](tanzu.md) - The Tanzu CLI