airship/airshipctl
Code Issues Proposed changes

[#38] Add end-user documentation to project

Browse Source 
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 <Alexander.Hughes@pm.me>
This commit is contained in:
Alexander Hughes 2020-03-06 09:45:32 -05:00
parent d155be2145
commit 26fdd05b0f
11 changed files with 572 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cmd/cluster/initinfra.go
View File

@ -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`)
}

4
cmd/cluster/testdata/TestNewClusterCommandReturnGoldenOutput/cluster-initinfra-cmd-with-defaults.golden vendored
View File

@ -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

4
cmd/completion/completion.go
View File

@ -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

6
cmd/config/get_authinfo.go
View File

@ -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

25
cmd/config/set_authinfo.go
View File

@ -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,

6
cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-few-args.golden vendored
View File

@ -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.

6
cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-too-many-args.golden vendored
View File

@ -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.

17
cmd/config/testdata/TestConfigSetAuthInfoGoldenOutput/config-cmd-set-authinfo-with-help.golden vendored
View File

@ -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.

4
cmd/config/testdata/TestGetAuthInfoCmdGoldenOutput/missing.golden vendored
View File

@ -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

545
docs/source/cli/cli.rst Normal file
View File

@ -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 <command>
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 <shell>
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 <flags>
.. _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 <name> --cluster-type=<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 <NAME>
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 <name> <flags>
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 <name> <flags>
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 <name> <flags>
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 <flags>
.. _secret-group:
Secret Group
============
Manages secrets.
Generate
--------
Generates various secrets.
MasterPassphrase
^^^^^^^^^^^^^^^^
Generates a secure master passphrase.
Usage:
::
airshipctl secret generate masterpassphrase

3
docs/source/index.rst
View File

@ -23,4 +23,5 @@ airshipctl Documentation
developers
plugins
testing-guidelines
testing-guidelines
cli/cli