From 26fdd05b0fc11595213b8574b1df555828888154 Mon Sep 17 00:00:00 2001 From: Alexander Hughes Date: Fri, 6 Mar 2020 09:45:32 -0500 Subject: [PATCH] [#38] Add end-user documentation to project 1. Add end-user documentation of CLI commands 2. Minor refactor of several help messages 3. Update of golden test data to reflect help message changes Change-Id: I58b8ac3a7871efdb569887ab65191bfb1842c24e Signed-off-by: Alexander Hughes --- cmd/cluster/initinfra.go | 4 +- ...cluster-initinfra-cmd-with-defaults.golden | 4 +- cmd/completion/completion.go | 4 +- cmd/config/get_authinfo.go | 6 +- cmd/config/set_authinfo.go | 25 +- ...onfig-cmd-set-authinfo-too-few-args.golden | 6 +- ...nfig-cmd-set-authinfo-too-many-args.golden | 6 +- .../config-cmd-set-authinfo-with-help.golden | 17 +- .../missing.golden | 4 +- docs/source/cli/cli.rst | 545 ++++++++++++++++++ docs/source/index.rst | 3 +- 11 files changed, 572 insertions(+), 52 deletions(-) create mode 100644 docs/source/cli/cli.rst diff --git a/cmd/cluster/initinfra.go b/cmd/cluster/initinfra.go index 140a6c7f8..45c150294 100644 --- a/cmd/cluster/initinfra.go +++ b/cmd/cluster/initinfra.go @@ -53,7 +53,7 @@ func addInitinfraFlags(i *initinfra.Infra, cmd *cobra.Command) { &i.DryRun, "dry-run", false, - "Don't deliver documents to the cluster, see the changes instead") + "Don't deliver documents to the cluster, simulate the changes instead") flags.BoolVar( &i.Prune, @@ -66,6 +66,6 @@ func addInitinfraFlags(i *initinfra.Infra, cmd *cobra.Command) { &i.ClusterType, "cluster-type", "ephemeral", - `Select cluster type to be deploy initial infastructure to,`+ + `Select cluster type to deploy initial infastructure to;`+ ` currently only ephemeral is supported`) } diff --git a/cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden b/cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden index 6eb5446ce..1577e9cfd 100644 --- a/cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden +++ b/cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden @@ -8,7 +8,7 @@ Examples: airshipctl cluster initinfra Flags: - --cluster-type string Select cluster type to be deploy initial infastructure to, currently only ephemeral is supported (default "ephemeral") - --dry-run Don't deliver documents to the cluster, see the changes instead + --cluster-type string Select cluster type to deploy initial infastructure to; currently only ephemeral is supported (default "ephemeral") + --dry-run Don't deliver documents to the cluster, simulate the changes instead -h, --help help for initinfra --prune If set to true, command will delete all kubernetes resources that are not defined in airship documents and have airshipit.org/deployed=initinfra label diff --git a/cmd/completion/completion.go b/cmd/completion/completion.go index eaab16acb..87cb6d711 100644 --- a/cmd/completion/completion.go +++ b/cmd/completion/completion.go @@ -8,9 +8,9 @@ import ( ) const completionDesc = ` -Generate autocompletions script for airshipctl for the specified shell (bash or zsh). +Generate autocompletion script for airshipctl for the specified shell (bash or zsh). -This command can generate shell autocompletions. e.g. +This command can generate shell autocompletion. e.g. $ airshipctl completion bash diff --git a/cmd/config/get_authinfo.go b/cmd/config/get_authinfo.go index 48f345ebb..234d4c791 100644 --- a/cmd/config/get_authinfo.go +++ b/cmd/config/get_authinfo.go @@ -24,13 +24,13 @@ import ( ) var ( - getAuthInfoLong = `Display a specific user information, or all defined users if no name is provided` + getAuthInfoLong = `Display a specific user's information, or all defined users if no name is provided` getAuthInfoExample = `# List all the users airshipctl knows about -airshipctl config get-credential +airshipctl config get-credentials # Display a specific user information -airshipctl config get-credential e2e` +airshipctl config get-credentials e2e` ) // An AuthInfo refers to a particular user for a cluster diff --git a/cmd/config/set_authinfo.go b/cmd/config/set_authinfo.go index f852b382e..ef381d97e 100644 --- a/cmd/config/set_authinfo.go +++ b/cmd/config/set_authinfo.go @@ -27,23 +27,8 @@ import ( var ( setAuthInfoLong = fmt.Sprintf(`Sets a user entry in airshipctl config -Specifying a name that already exists will merge new fields on top of existing values. - -Client-certificate flags: ---%v=certfile --%v=keyfile - -Bearer token flags: ---%v=bearer_token - -Basic auth flags: ---%v=basic_user --%v=basic_password - -Bearer token and basic auth are mutually exclusive.`, - config.FlagCertFile, - config.FlagKeyFile, - config.FlagBearerToken, - config.FlagUsername, - config.FlagPassword) +Specifying a name that already exists will merge new fields on top of existing values.`, + ) setAuthInfoExample = fmt.Sprintf(` # Set only the "client-key" field on the "cluster-admin" @@ -112,19 +97,19 @@ func addSetAuthInfoFlags(o *config.AuthInfoOptions, cmd *cobra.Command) { &o.Token, config.FlagBearerToken, "", - config.FlagBearerToken+" for the user entry in airshipctl") + config.FlagBearerToken+" for the user entry in airshipctl. Mutually exclusive with username and password flags.") flags.StringVar( &o.Username, config.FlagUsername, "", - config.FlagUsername+" for the user entry in airshipctl") + config.FlagUsername+" for the user entry in airshipctl. Mutually exclusive with token flag.") flags.StringVar( &o.Password, config.FlagPassword, "", - config.FlagPassword+" for the user entry in airshipctl") + config.FlagPassword+" for the user entry in airshipctl. Mutually exclusive with token flag.") flags.BoolVar( &o.EmbedCertData, diff --git a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden index d5d12ad15..998a62aa5 100644 --- a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden +++ b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden @@ -19,7 +19,7 @@ Flags: --client-key string Path to client-key file for the user entry in airshipctl --embed-certs Embed client cert/key for the user entry in airshipctl -h, --help help for set-credentials - --password string password for the user entry in airshipctl - --token string token for the user entry in airshipctl - --username string username for the user entry in airshipctl + --password string password for the user entry in airshipctl. Mutually exclusive with token flag. + --token string token for the user entry in airshipctl. Mutually exclusive with username and password flags. + --username string username for the user entry in airshipctl. Mutually exclusive with token flag. diff --git a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden index 04bd1edb6..d35fefb10 100644 --- a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden +++ b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden @@ -19,7 +19,7 @@ Flags: --client-key string Path to client-key file for the user entry in airshipctl --embed-certs Embed client cert/key for the user entry in airshipctl -h, --help help for set-credentials - --password string password for the user entry in airshipctl - --token string token for the user entry in airshipctl - --username string username for the user entry in airshipctl + --password string password for the user entry in airshipctl. Mutually exclusive with token flag. + --token string token for the user entry in airshipctl. Mutually exclusive with username and password flags. + --username string username for the user entry in airshipctl. Mutually exclusive with token flag. diff --git a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden index 1fe9a1f65..dfa8a5623 100644 --- a/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden +++ b/cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden @@ -1,17 +1,6 @@ Sets a user entry in airshipctl config Specifying a name that already exists will merge new fields on top of existing values. -Client-certificate flags: ---client-certificate=certfile --client-key=keyfile - -Bearer token flags: ---token=bearer_token - -Basic auth flags: ---username=basic_user --password=basic_password - -Bearer token and basic auth are mutually exclusive. - Usage: set-credentials NAME [flags] @@ -32,6 +21,6 @@ Flags: --client-key string Path to client-key file for the user entry in airshipctl --embed-certs Embed client cert/key for the user entry in airshipctl -h, --help help for set-credentials - --password string password for the user entry in airshipctl - --token string token for the user entry in airshipctl - --username string username for the user entry in airshipctl + --password string password for the user entry in airshipctl. Mutually exclusive with token flag. + --token string token for the user entry in airshipctl. Mutually exclusive with username and password flags. + --username string username for the user entry in airshipctl. Mutually exclusive with token flag. diff --git a/cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden b/cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden index f70d58032..d906e8dd3 100644 --- a/cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden +++ b/cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden @@ -4,10 +4,10 @@ Usage: Examples: # List all the users airshipctl knows about -airshipctl config get-credential +airshipctl config get-credentials # Display a specific user information -airshipctl config get-credential e2e +airshipctl config get-credentials e2e Flags: -h, --help help for get-credentials diff --git a/docs/source/cli/cli.rst b/docs/source/cli/cli.rst new file mode 100644 index 000000000..42f4bb637 --- /dev/null +++ b/docs/source/cli/cli.rst @@ -0,0 +1,545 @@ +.. + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _airshipctl-cli: + +============== +AirshipCTL CLI +============== + +The AirshipCTL CLI is used in conjunction with the binary created by running ``make build``. This binary, by default, +is created in the ``airshipctl/bin/`` directory. + + +CLI Options +=========== + +**-h / \\-\\-help** + +Prints help for a specific command or command group. + +**\\-\\-debug** (Optional, default: false) + +Enables verbose output of commands. + +**\\-\\-airshipconf** (Optional, default: `$HOME/.airship/config`) + +Path to file for airshipctl configuration. + +**\\-\\-kubeconfig** (Optional, default: `$HOME/.airship/kubeconfig`) + +Path to kubeconfig associated with airshipctl configuration. + +.. _root-group: + +Root Group +========== + +Allows you to perform top level commands + +:: + + airshipctl + +Version +------- + +Output the version of the airshipctl binary. + +Usage: + +:: + + airshipctl version + +Completion +---------- + +Generate autocompletion script for airshipctl for the specified shell (bash or zsh). + +**shell** (Required) + +Shell to generate autocompletion script for. Supported values are `bash` and `zsh` + +Usage: + +:: + + airshipctl completion + +Examples +^^^^^^^^ + +This command can generate bash autocompletion. e.g. + +:: + + $ airshipctl completion bash + +Which can be sourced as such: + +:: + + $ source <(airshipctl completion bash) + +.. _bootstrap-group: + +Bootstrap Group +=============== + +Used to bootstrap the ephemeral Kubernetes cluster. + +ISOgen +------- + +Generate bootstrap ISO image. + +Usage: + +:: + + airshipctl bootstrap isogen + +RemoteDirect +------------ + +Bootstrap ephemeral node. + +Usage: + +:: + + airshipctl bootstrap remotedirect + +.. _cluster-group: + +Cluster Group +============= + +Control Kubernetes cluster. + +InitInfra +------------ + +Deploy initinfra components to cluster. + +**cluster-type** (Optional, default:"ephemeral") + +Select cluster type to deploy initial infrastructure to, currently only ephemeral is supported. + +**\\-\\-dry-run** (Optional). + +Don't deliver documents to the cluster, simulate the changes instead. + +**\\-\\-prune** (Optional, default:false) + +If set to true, command will delete all kubernetes resources that are not defined in airship documents and have +airshipit.org/deployed=initinfra label + +Usage: + +:: + + airshipctl cluster initinfra + +.. _config-group: + +Config Group +============ + +Modify airshipctl config files + +Get-Cluster +----------- + +Display cluster information. + +**name** (Optional, default: all defined clusters) + +Displays a specific cluster if specified, or if left blank all defined clusters. + +**\\-\\-cluster-type** (Required). + +cluster-type for the cluster-entry in airshipctl config. Currently only ephemeral cluster types are supported. + +Usage: + +:: + + airshipctl config get-cluster --cluster-type= + +Examples +^^^^^^^^ + +List all the clusters airshipctl knows about: + +:: + + airshipctl config get-cluster + +Display a specific cluster: + +:: + + airshipctl config get-cluster e2e --cluster-type=ephemeral + +Get-Context +----------- + +Displays context information + +**name** (Optional, default: all defined contexts) + +Displays a named context, if no name is provided display all defined contexts. + +**\\-\\-current-context** (Optional, default:false) + +Display the current context, supersedes the `name` argument. + +Usage: + +:: + + airshipctl config get-context + +Examples +^^^^^^^^ + +For all contexts: + +:: + + airshipctl config get-context + +For the current context: + +:: + + airshipctl config get-context --current + +For a named context: + +:: + + airshipctl config get-context e2e + + +Get-Credentials +--------------- + +Display a user's information. + +**name** (Optional, default: all defined users) + +Display a specific user's information. If no name is specified, list all defined users. + +Usage: + +:: + + airshipctl config get-credentials + +Examples +^^^^^^^^ + +List all the users airshipctl knows about: + +:: + + airshipctl config get-credentials + +Display a specific user's information: + +:: + + airshipctl config get-credentials e2e + +Init +---- + +Generate initial configuration files for airshipctl + +Usage: + +:: + + airshipctl config init + +Set-Cluster +----------- + +Sets a cluster entry in the airshipctl config. + +**name** (Required) + +The name of the cluster to add to airshipctl config. + +.. note:: + + Specifying a name that already exists will merge new fields on top of existing values for those fields. + +**\\-\\-certificate-authority** (Optional) + +Path to certificate-authority file for the cluster entry in airshipctl config + +**\\-\\-certificate-authority** (Required) + +Cluster-type for the cluster entry in airshipctl config + +**\\-\\-embed-certs** (Optional) + +Embed-certs for the cluster entry in airshipctl config + +**\\-\\-insecure-skip-tls-verify** (Optional, default:true) + +Insecure-skip-tls-verify for the cluster entry in airshipctl config + +**\\-\\-server** (Optional) + +Server for the cluster entry in airshipctl config + +Usage: + +:: + + airshipctl config set-cluster + +Examples +^^^^^^^^ + +Set only the server field on the e2e cluster entry without touching other values: + +:: + + airshipctl config set-cluster e2e --cluster-type=ephemeral --server=https://1.2.3.4 + +Embed certificate authority data for the e2e cluster entry: + +:: + + airshipctl config set-cluster e2e --cluster-type=target --certificate-authority-authority=~/.airship/e2e/kubernetes.ca.crt + +Disable cert checking for the dev cluster entry: + +:: + + airshipctl config set-cluster e2e --cluster-type=target --insecure-skip-tls-verify=true + +Configure client certificate: + +:: + + airshipctl config set-cluster e2e --cluster-type=target --embed-certs=true --client-certificate=".airship/cert_file" + +Set-Context +----------- + +Switch to a new context, or update context values in the airshipctl config + +**name** (Required) + +The name of the context to set. + +**\\-\\-cluster-string** + +Sets the cluster for the specified context in the airshipctl config. + +**\\-\\-cluster-type** + +Sets the cluster-type for the specified context in the airshipctl config. + +**\\-\\-current** + +Use current context from airshipctl config. + +**\\-\\-manifest** + +Sets the manifest for the specified context in the airshipctl config. + +**\\-\\-namespace** + +Sets the namespace for the specified context in the airshipctl config. + +**\\-\\-user** + +Sets the user for the specified context in the airshipctl config. + +Usage: + +:: + + airshipctl config set-context + +Examples +^^^^^^^^ + +Create a completely new e2e context entry: + +:: + + airshipctl config set-context e2e --namespace=kube-system --manifest=manifest --user=auth-info --cluster-type=target + +Update the current-context to e2e: + +:: + + airshipctl config set-context e2e + +Update attributes of the current-context: + +:: + + airshipctl config set-context --current --manifest=manifest + + +Set-Credentials +--------------- + +Sets a user entry in the airshipctl config. + +**name** (Required) + +The user entry to update in airshipctl config. + +.. note:: Specifying a name that already exists will merge new fields on top of existing values. + +**\\-\\-client-certificate** + +Path to client-certificate file for the user entry in airshipctl + +**\\-\\-client-key** + +Path to client-key file for the user entry in airshipctl + +**\\-\\-embed-certs** + +Embed client cert/key for the user entry in airshipctl + +**\\-\\-password** + +Password for the user entry in airshipctl + +.. note:: Username and Password flags are mutually exclusive with Token flag + +**\\-\\-token** + +Token for the user entry in airshipctl + +.. note:: Username and Password flags are mutually exclusive with Token flag + +**\\-\\-username** + +Username for the user entry in airshipctl + +.. note:: Username and Password flags are mutually exclusive with Token flag + +Usage: + +:: + + airshipctl config set-credentials + +Examples +^^^^^^^^ + +Set only the "client-key" field on the "cluster-admin" entry, without touching other values: + +:: + + airshipctl config set-credentials cluster-admin --username=~/.kube/admin.key + +Set basic auth for the "cluster-admin" entry + +:: + + airshipctl config set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif + +Embed client certificate data in the "cluster-admin" entry + +:: + + airshipctl config set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true + +.. _document-group: + +Document Group +============== + +Manages deployment documents. + +Pull +---- + +Pulls documents from remote git repository. + +Usage: + +:: + + airshipctl document pull + +Render +------ + +Render documents from model. + +**-a / \\-\\-annotation** + +Filter documents by Annotations. + +**-g / \\-\\-apiversion** + +Filter documents by API version. + +**-f / \\-\\-filter** + +Logical expression for document filtering. + +**-k / \\-\\-kind** + +Filter documents by Kinds. + +**-l / \\-\\-label** + +Filter documents by Labels. + +Usage: + +:: + + airshipctl document render + +.. _secret-group: + +Secret Group +============ + +Manages secrets. + +Generate +-------- + +Generates various secrets. + +MasterPassphrase +^^^^^^^^^^^^^^^^ + +Generates a secure master passphrase. + +Usage: + +:: + + airshipctl secret generate masterpassphrase diff --git a/docs/source/index.rst b/docs/source/index.rst index 2e0adf398..4215e2382 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,4 +23,5 @@ airshipctl Documentation developers plugins - testing-guidelines \ No newline at end of file + testing-guidelines + cli/cli \ No newline at end of file