From bace51d17cd6c0d81bb220a8bd268728b485d091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ota=CC=81vio=20Fernandes?= Date: Mon, 30 Nov 2020 15:36:13 +0100 Subject: [PATCH] Shipwright Command-Line Interface (EP) --- docs/proposals/cli.md | 189 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/proposals/cli.md diff --git a/docs/proposals/cli.md b/docs/proposals/cli.md new file mode 100644 index 0000000000..97ba4a9e20 --- /dev/null +++ b/docs/proposals/cli.md @@ -0,0 +1,189 @@ +--- +title: CLI +authors: + - "@otaviof" + +reviewers: + - "@gabemontero" + - "@HeavyWombat" + - "@coreydaley" + +approvers: + - TBD +creation-date: 2020-10-07 +last-updated: 2020-11-30 +status: provisional +--- + +CLI +--- + +# Summary + +This enhancement proposal describes a command-line client for Shipwright Build operator, covering +from the command line structure, the usage as a kubectl plugin, and as a standalone binary, as +well as testing this new project. + +# Motivation + +Command-line interface is a fundamental component for developer experience and modern automation. +This enhancement proposal describes a command-line interface, i.e. "CLI", to enhance the developer +experience and provide easier means to interact and automate Shipwright's Builds. + +## Goals + +- Improve the user experience by providing a specialized client +- Make possible extended automation with shell scripting + +## Non-Goals + +- Re-implement operator logic +- Become the mandatory API client + +# Proposal + +Create a command-line client for Shipwright Build to improve the user experience and also improve +the ability to automate workflows. + +This new project will concentrate our effects on the API client side of the Shipwright project, +and by maintaining the expected separation of `cmd` and `pkg`, developers can embed and extend the +possibilities of consuming Shipwright Operator API. + +A [proof-of-concept command-line interface project](https://github.com/otaviof/shp) has been +written to scaffold the features, and evaluate the changes proposed in this document. The project +documentation (`README.md`) is focused on developers and contributors, while the features it will +provide are contained in this document. + +## Usage and Installation + +This command-line application will be consumed as a standalone binary, or as a plugin in `kubectl`. +This implies a few more extra settings, and making sure the application binary complies with the +[expected convention](https://krew.sigs.k8s.io/docs/developer-guide/develop/best-practices/). + +### Standalone + +The standalone binary will be available via the usual means, final users will be able to simply +install with `go get…`, or pick a pre-compiled binary from GitHub release pages. Consider the +[release section](#Releasing) for more. + +### Plugin + +As a [krew plugin](https://krew.sigs.k8s.io/docs/developer-guide/), the expected usage is: + +```sh +$ kubectl shp ... +``` + +And the following global flags are expected, to keep consistency with `kubectl`: + +- `-h/--help` +- `-n/--namespace` +- `-A/--all-namespaces` + +Those three flags are mandatory to keep compatibility. However, the +[upstream kubectl package](https://pkg.go.dev/k8s.io/kubectl@v0.17.6/pkg/cmd/util) provides +[more options](https://github.com/otaviof/shp/blob/55ce2e8d58435b0264e3db0bef5cf439abfeca18/vendor/k8s.io/cli-runtime/pkg/genericclioptions/config_flags.go#L317) +out of the box. + +## Command + +The project will use [cobra](https://github.com/spf13/cobra)/[viper](https://github.com/spf13/viper) +for scaffolding the command-line structure, which in terms of organization and workflow, follows +`kubectl` convention. Thus, the following pattern: + +```sh +$ shp [options] +``` + +For instance: + +```sh +$ shp create build nodejs-ex +$ shp run build nodejs-ex +``` + +Alternatively, we may have a more conventional pattern, as in: + +```sh +$ shp [verb] [options] +``` + +For example: + +```sh +$ shp build create nodejs-ex +$ shp build run nodejs-ex +$ shp logs nodejs-ex +``` + +During the review process of this enhancement proposal, we must decide which pattern suits better, +which one we prefer to go ahead with. + +## Features + +For the initial release, the aim is to be able to define a `Build`, run it and display logs. + +### Defining a Build + +```sh +$ shp build [options] +``` + +Will be responsible for managing Build objects, using the verbs: `create`, `update`, list and +`delete`. Later on, end users should have the ability to bootstrap a local repository clone using a +single command. + +### Running a Build + +```sh +$ shp run build [options] +``` + +This sub-command will instantiate a new BuildRun resource for a Build, effectively starting the +build process. And, will print follow up commands that may be issued to see the BuildRun status +and inspect logs. + +### Logs + +```sh +$ shp logs [options] +``` + +Retrieve all logs related to the informed `BuildRun` name. It will also be able to follow +(`--follow`) container log output as they are executed. The log lines displayed are organised by +the sequence of steps, and easy to read the whole build process output in a single go. + +Additionally, it must provide easy syntax to reach a specific `BuildRun` instance, or the most +recent `BuildRun` for a `Build`. + +## More Features + +The command-line interface is planned to host more features, like for instance managing local and +remove artifacts, as well as help end-users to upload data into the cluster. + +Thus, the initial design of the CLI must allow more subcommands to be added, accommodating more +features which will depend in a client. + +## Testing + +The strategy to test the command-line application will be based on `go test` for the unit testing, +and for end-to-end testing we should adopt [bats](https://github.com/sstephenson/bats). Bats +framework gives us a structured way to run shell script commands and what we expect them to +return, the command-line client shp is no more than a shell command. + +The testing structure will be composed of: + +- **Unit**: written in Golang and using [Gomega](https://onsi.github.io/gomega/) for assertion; +- **End-to-End**: written in Golang and located at the traditional `test/e2e` directory; +- **System**: written using Bats framework (Bash), or similar approach; + +Bats will also be helpful for a future `shp` container-image, we are able to mount the Bats files +in the container-image produced, and run our system testing against it. Therefore, Bats covers +testing of a local command-line binary, as well as it does a container-image. Another tool may take +Bats' place, covering the same test-use cases accordingly. + +## Releasing + +The command-line release will initially be available on GitHub Pages process, on which we can also +index on Shipwright website. Later on we can evaluate the need for a container-image carrying on +the binary, or an RPM.