Solum/FeatureBlueprints/NewCLI

New CLI
https://blueprints.launchpad.net/solum/+spec/new-cli

Problem description
The current CLI implementation in Solum is not user friendly or intuitive - for example it uses CAMP terminology such as Assembly, Plan, etc. that can confuse the a solum user not familiar with those terms. This spec proposes a new CLI interface design that optimizes for intuitive, simple, user experience.

Proposed change
The scope of this spec is what will be implemented as a FIRST step in redesign of the CLI interface, and is not intended to be comprehensive CLI spec. There will be additional set of CLI commands and options needed immediately next, this spec does not cover all of them.

Login
As an app developer, I want to use my openstack credentials to authenticate to Solum from the CLI console.

solum login [-u USERNAME -p PASSWORD] | [-a API_KEY]

Either UserName/Password or API_KEY needs to be specified. If any of them are not specified, then the CLI will first try to read them from the environment variables. Otherwise CLI will prompt for UserName/Password in interactive mode. When Password is entered by the user in interactive mode, the characters are hidden on the console

Register app
As an app developer already authenticated to Solum, I want to register my app with a single CLI command.

solum app create [app_template_filename]

''solum app create <--langpack > <--giturl > <--runcmd > [--name ] [--services ] [--desc ] [--settrigger ] [-- custom_var_filename ]''

Registers the app with Solum by storing app metadata/generate app URL/generate git trigger URLs and any other one time app setup actions

Precondition: Can be called immediately after Login

Example command when all the arguments are supplied on the command line:

''solum app create --langpack JavaTomcat7 --giturl "url to code repo", --runcmd "command to start the app" --name MyJavaApp --services Trove --desc “My first java app” -testcmd "path to file name or in-place command text" --setgittrigger build (or deploy) -- custom_var_filename myvars.yaml '' Parameters can be specified either on the command line, or in an app template file. The app template file will be a yaml file, with the file name+path explicitly specified on the command line.

Mandatory Parameters: The CLI will interactively prompt for mandatory parameters not supplied on the initial app create command. If language pack is not specified, interactively show a list of available language pack names/Id’s/short desc the user can choose from.

Optional Parameters: use default values for optional parameters not specified on the command line.

- name: *generate a unique app name* - services: *default to no services* - desc: *default to empty string* - testcmd: *default to none* - setgittrigger: *default to "don't automatically setup git trigger"*

The three workflows (CI+Build), (CI+Build+Deploy), and (Deploy only) can be triggered on the same app that was registered as part of the App Create command. What this means is that the workflow selection does not happen during app registration, but happens in response to a specific CLI command

- "App Build" command triggers the CI+Build workflow - "App Deploy" triggers the CI+Build+Deploy workflow - "App Deploy --buildno=7865 triggers the Deploy only workflow

Output of app create command: app create returns the following output -

- App URL: [Web App URL] - at this point the app has not been deployed, and the URL is not live yet. - Git trigger URL for (CI+build) workflow - Git trigger URL for (CI+build+deploy) workflow

User has the option of manually updating their git repository with the chosen trigger URL.

Build app
As an app developer, I want to issue a single CLI command to execute integration and then build processes for my app.


 * solum app build *

Executes the "CI+Build" workflow

Starts from source code and results in a DU: Pull source code, unit test, optionally functional test using a transient deployment, persist DU

Deploy app
As an app developer, I want to issue a single CLI command to deploy my registered app and generate a running app.

executes CI+build+deploy workflow
 * solum app deploy *

The deploy command can also be used to deploy a pre-built artifact:

executes the "deploy only" workflow, to deploy the specified build
 * solum app deploy MyJavaApp --buildno=972*

Show app status
As an app developer, I want to issue a single CLI command to view the details of my app.

Displays the current state of the app (run state + build state)
 * solum app show *

- Run state: running/not running [deployed build number=970(if running)] - Last build status: success/failed/in progress [build number=972] - App URL: [Web App URL] - GitTriggerURL's - App Registration Info

List apps
As an app developer, I want to issue a single CLI command to view an index of all my registered apps and their current states.

Outputs a list of apps for current user: for each app, show App Name, App status (running, stopped), and App URL
 * solum apps list*

Delete app
As an app developer, I want to issue a single CLI command to destroy all resources and artifacts associated with one of my registered apps.

The command will delete all app registration as well as release history It will also delete all the logs associated with the app.
 * solum app delete *

The command can optionally be invoked with a *--preservelogs* option.

Create language pack
As an app developer, I want to issue a single CLI command to create my own language pack and register it with Solum so that it is accessible only to the customer tenant I belong.

As an operator of Solum, I want to issue a single CLI command to create and register language packs, and make them available to all customer tenants.


 * solum langpack create --name "MyTomcatLangPack" --path "location of languagepack files" --desc "my custom language pack for tomcat"*

The language pack files consist of a docker file and a set of associated scripts (*build.sh, test.sh, run.sh*) - these files have well known names. The files can be located on a local/network drive or a URL.

List language packs
As an app developer, I want to issue a single CLI command to view all languages packs accessible to my customer tenant, including language packs provided by an operator and language packs created by other app developers and made accessible to me.

Lists all available language packs: operator defined standard packs as well as developer defined custom packs that are within the scope of the customer tenant Id
 * solum langpacks list*

Git Experience
As an app developer, I want to view all the possible trigger URLs available for my app, so that I can can manually configure my code repository to trigger specific workflows on my code in response to events on my codebase.

As an app developer, I want the CLI to provide an option to set up such a trigger on my repository when I register a new app to Solum, requesting minimal credentials from me to access the repository.

As an app developer, I want the CLI to provide an option to set up such a trigger on my repository after my app has been registered, likely as part of the "solum app update" command.

Setting git triggers is optional.

There are two ways I can setup git based triggers

- **Manually** read the Git Trigger URL's reported by "app create" or "app show" commands, and configure them in my git repository - **Specify -settrigger** parameter to the the "app create" CLI command to have it automatically configured. This parameter can take one of two possible values: Build, or Deploy. Build will trigger the (CI+Build) workflow, and Deploy will trigger the (CI+Build+CD) workflow

Help
As an app developer, I want the CLI to issue a help message for any command or partial command, including usage examples and a summary description of each of the commands available.


 * solum help [command]*

- *solum help* - will list all commands, along with 1 line description of the command - *solum help * - will show usage details of the command, including an example usage