kion-cli

Kion CLI

Kion CLI is a tool allowing Kion customers to generate short term access keys and federate into the cloud service provider console via the command line.

Setup

1. Build the application and place it in your path:

   go build -o kion
   ln -s $(pwd)/kion /usr/local/bin/
   
   # or
   
   make install
   

2. (optional) For ZSH completion place this file as _kion in your ZSH autocomplete path:

   #compdef kion
   
   _cli_zsh_autocomplete() {
     local -a opts
     local cur
     cur=${words[-1]}
     if [[ "$cur" == "-"* ]]; then
       opts=("${(@f)$(${words[@]:0:#words[@]-1} ${cur} --generate-bash-completion)}")
     else
       opts=("${(@f)$(${words[@]:0:#words[@]-1} --generate-bash-completion)}")
     fi
   
     if [[ "${opts[1]}" != "" ]]; then
       _describe 'values' opts
     else
       _files
     fi
   }
   
   compdef _cli_zsh_autocomplete kion
   

3. (optional) Create a configuration file in your home directory named .kion.yml:

   kion:
     url: https://mykion.example
     api_key: [api key]
     username:
     password:
     idms_id:
     saml_metadata_file:
     saml_sp_issuer:
   favorites:
     - name: sandbox
       account: "111122223333"
       cloud_access_role: Admin
       access_type: web               # optional (defaults to cli)
       region: us-gov-west-1          # optional
     - name: prod
       account: "111122224444"
       cloud_access_role: ReadOnly
   

User Manual

Description:

The Kion CLI allows users to perform common Kion workflows via the command line. Users can quickly generate short term access keys (stak) or federate into the cloud service provider web console via configured favorites or by walking through an account and role selection wizard.

Commands:

stak, s            Generate short-term access keys.

favorite, fav, f   Access pre-configured favorites to quickly generate staks or federate
                   into the cloud service provider console depending on the access_type
                   defined in the favorite.

console, con, c    Federate into the cloud service provider console.

run                Run a command with short-term access keys

help, h            Print usage text.

Files:

~/.kion.yml       The user configuration file. Defines credentials, target Kion
                  instance, and a list of favorites.

Global Options:

--endpoint URL, -e URL             URL of the Kion instance to interface with.

--user USERNAME, -u USERNAME       Username used for authenticating with Kion.

--password PASSWORD, -p PASSWORD   Password used for authenticating with Kion.

--idms IDMS_ID, -i IDMS_ID         IDMS ID with which to authenticate if using
                                   username and password. If only one IDMS is
                                   configured that uses username and password
                                   it is not required to specify its ID.

--saml_metadata_file FILENAME|URL  FILENAME or URL of the identity provider's
                                   XML metadata document.  If a URL, this file
                                   will be downloaded every time the CLI app
                                   is run.  If a local file, this should be an
                                   absolute path to a file on your computer.

--saml_sp_issuer ISSUER            SAML Service Provider issuer value from Kion
                                   for example:
                                   https://mykioninstance.example/api/v1/saml/auth/1

--token TOKEN, -t TOKEN            Token (API or Bearer) used to authenticate.

--help, -h                         Print usage text.

--version, -v                      Print the Kion CLI version.

STAK Command:

OPTIONS

  --print, -p                          Print STAK only. (default: false)

  --account val, -acc val, -a val      Target account number, used to bypass
                                       prompts, must be passed with --car.

  --car val, -c val                    Target cloud access role, used to bypass
                                       prompts, must be passed with --account.

  --region val, -r val                 Specify which region to target.

  --help, -h                           Print usage text.

Favorite Command:

SUB COMMANDS

  list                                 List all configured favorites. List
                                       accepts a --verbose / -v option to print
                                       additional details.

OPTIONS

  --print, -p                          Print STAK only. Has no effect on
                                       favorites with an "access_type" of
                                       "web". (default: false)


  --help, -h                           Print usage text.

Run Command:

OPTIONS

  --favorite val,  -fav val, -f val    Specify which favorite to run against.

  --account val, -acc val, -a val      Specify which account to target, must be
                                       passed with --car.

  --car val, -c val                    Specify which Cloud Access Role to use,
                                       must be passed with --account.

  --region val, -r val                 Specify which region to target.

  --help, -h                           Print usage text.

Environment:

Environment variables can be set to enable other modalities of Kion CLI usage. Kion CLI follows standard precedence for defining configurations:

Flag > Environment Variable > Configuration File > Default Value

KION_URL        URL of the Kion instance to interact with.

KION_USERNAME   Username used for authenticating with Kion.

KION_PASSWORD   Passwrod used for authenticating with Kion.

KION_IDMS_ID    IDMS ID with which to authenticate if using username and
                password. If only one IDMS is configured that uses username and
                password it is not required to specify its ID.

KION_API_KEY    API key used to authenticate. Corresponds to the `--token` flag.

KION_SAML_METADATA_FILE  FILENAME or URL of the identity provider's XML metadata
                         document.  If a URL, this file will be downloaded
                         every time the CLI app is run.  If a local file, this
                         should be an absolute path to a file on your computer.

KION_SAML_SP_ISSUER     The Kion IDMS issuer value, for example
                        https://mykioninstance.example/api/v1/saml/auth/1

SAML Setup

Kion CLI can use the same SAML identity provider as the Kion user interface to authenticate access to Kion. This allows for CLI access with no Kion credentials or API tokens stored to disk.

When SAML is used for authentication, Kion CLI will prompt users to authenticate via their IDP in a web browser. Once authenticated through the IDP, the web page is closed and Kion CLI will use this authenticated session to interact with the Kion API and generate cloud tokens.

Some extra setup is required to use SAML:

Contributing

1. Ensure you have golang installed and configured.
2. Clone the repository and initialize with make init. This will setup the necessary git hooks and other needed tools.
3. Create and populate your ~/.kion.yml configuration file. See the example at the top of this document.
4. When submitting a PR be sure to note your changes in the CHANGELOG.md.