diff --git a/README.md b/README.md index 060d4d2..f1ce578 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ hava is a Go CLI tool to interact with app.hava.io platform. - - ## Overview This tool is a CLI driven binary to interface with the Hava API/SaaS platform. This will allow practitioners to download a single binary that can be and used as part of CI/CD pipelines in tools like Github Actions, Gitlab CICD and Azure Devops, as well as part of local users commands or scripts. @@ -18,11 +16,6 @@ Check out our [current roadmap and drivers](./ROADMAP.md) for Hava CLI. - [Usage](#usage) - [Print hava CLI help](#print-hava-cli-help) - [Create and List Sources](#create-and-list-sources) - - [CLI JSON Output](#cli-json-output) - - [Sync Sources](#sync-sources) - - [Delete Sources](#delete-sources) - - [CLI Completion Setup](#cli-completion-setup) - - [CLI Interactive Config Setup](#cli-interactive-config-setup) - [Pre-Requisites](#pre-requisites) - [Environment Variable](#environment-variable) - [Configuration File](#configuration-file) @@ -30,19 +23,10 @@ Check out our [current roadmap and drivers](./ROADMAP.md) for Hava CLI. - [Running in Automation/CICD](#running-in-automationcicd) - [Source Commands](#source-commands) - [Source List all](#source-list-all) - - [Source List SourceID](#source-list-sourceid) - - [Source Sync SourceID](#source-sync-sourceid) - [Source Create AWS (Using Access Keys)](#source-create-aws-using-access-keys) - - [Source Create AWS (Using Cross Account Role)](#source-create-aws-using-cross-account-role) - - [Source Create GCP](#source-create-gcp) - - [Source Create Azure](#source-create-azure) - - [Source Delete](#source-delete) - - [Source Update AWS|AZURE|GCP](#source-update-awsazuregcp) - [Output Formats](#output-formats) - [Table Output](#table-output) - [Json Output](#json-output) - - [CSV Output](#csv-output) - - [Markdown Output](#markdown-output) - [Build Local Binary](#build-local-binary) - [Testing Locally](#testing-locally) @@ -50,6 +34,21 @@ Check out our [current roadmap and drivers](./ROADMAP.md) for Hava CLI. Binaries are created as part of a release, check out the [Release Page](https://github.com/teamhava/hava-ui-cli/releases) for the latest version. +**MacOs Installation Homebrew** +```sh +brew tap teamhava/hava +brew install hava +``` + + +**Linux Installation** +```sh +version="x.x.x" +arch="arm64" +curl -L -o hava.zip "https://github.com/teamhava/hava-ui-cli/releases/download/${version}/hava_Linux_${arch}.zip" +unzip hava.zip +``` + Specific [OS (Linux|OSX|Windows|Docker) installation here](./docs/installation.md). @@ -88,26 +87,7 @@ Use "hava [command] --help" for more information about a command. ![hava_create_list](./docs/images/hava_create_list_sources.cast.gif) -### CLI JSON Output - -![hava_json_out](./docs/images/hava_CLI_json_output.cast.gif) - - -### Sync Sources - -![hava_print_source](./docs/images/hava_source_sync.cast.gif) - -### Delete Sources - -![hava_delete_sources](./docs/images/hava_source_delete.cast.gif) - -### CLI Completion Setup - -![hava_cli_completion](./docs/images/hava_cli_completion.cast.gif) - -### CLI Interactive Config Setup - -![hava_config_setup](./docs/images/hava_config_setup.cast.gif) +More [Usage examples](./docs/usage.md). ## Pre-Requisites @@ -146,7 +126,7 @@ When running `hava` CLI in automation or a CICD pipeline, we recommend export/se Some commands do require human inputs or can be bypassed with a flag (eg `--autoapprove`). -Checkout our [Github CLI Test workflow](./.github/workflows/cli-test.yml) and other [CICD examples](./cicd-examples/README.md) for other platforms like Gitlab-CI and Azure DevOps. +Checkout our [Github CLI Test workflow](./docs/cicd-examples/github/workflows/cli-test.yml) and other [CICD examples](./docs/cicd-examples/README.md) for other platforms like Gitlab-CI and Azure DevOps. # Source Commands @@ -184,16 +164,6 @@ Flags: ╰───┴─────────────┴──────────────────────────────────────┴──────────────────────┴────────────┴────────┴────────────────────╯ ``` -## Source List SourceID - -`hava source list --source-id a58b7cb1-f9da-42ad-9fc1-8dc61b0d3e38` - - -## Source Sync SourceID - -`hava source sync a58b7cb1-f9da-42ad-9fc1-8dc61b0d3e38` - - ## Source Create AWS (Using Access Keys) `hava source create aws --name dev --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY` @@ -208,53 +178,14 @@ Flags: ╰───┴─────────────┴──────────────────────────────────────┴──────────────────────┴────────────┴────────┴────────────────────╯ ``` -## Source Create AWS (Using Cross Account Role) - -`hava source create aws --name devCAR --role-arn $AWS_CROSS_ACCOUNT_ROLE` - -```bash -[INFO] Created AWS Source for the following source: - -╭───┬─────────────┬──────────────────────────────────────┬────────────────────────────────────────┬────────┬────────┬────────────────────────────────╮ -│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ -├───┼─────────────┼──────────────────────────────────────┼────────────────────────────────────────┼────────┼────────┼────────────────────────────────┤ -│ 1 │ devCAR │ 31f9b6a6-4e48-400a-8ced-5bfc2a1aacc2 │ arn:aws:iam::123456789012:role/HavaCAR │ devCAR │ queued │ Sources::AWS::CrossAccountRole │ -╰───┴─────────────┴──────────────────────────────────────┴────────────────────────────────────────┴────────┴────────┴────────────────────────────────╯ -``` - -## Source Create GCP - -`hava source create gcp --name GCPDev --configFile $GCP_ENCODED_FILE` - -```bash -[INFO] Created GCP Source for the following source: - -╭───┬─────────────┬──────────────────────────────────────┬──────────────────┬────────┬────────┬─────────────────────────────────────────╮ -│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ -├───┼─────────────┼──────────────────────────────────────┼──────────────────┼────────┼────────┼─────────────────────────────────────────┤ -│ 1 │ GCPDev │ 8818d864-46e9-4b8d-acdd-a31d8936e62f │ credentials.json │ GCPDev │ queued │ Sources::GCP::ServiceAccountCredentials │ -╰───┴─────────────┴──────────────────────────────────────┴──────────────────┴────────┴────────┴─────────────────────────────────────────╯ -``` - -## Source Create Azure - -`hava create source azure --name AzureDev --client-id $ARM_CLIENT_ID --tenant-id $ARM_TENANT_ID --subscription-id $ARM_SUBSCRIPTION_ID` - - -## Source Delete - -`hava source delete 22872411-20e8-4b6e-aa46-41866c9c1897` - - -## Source Update AWS|AZURE|GCP - -`hava source update gcp --name GCPDevChange --source-id f2a26440-10bf-43d1-9742-8361de30590f` - - +More [`hava source` commands found here](./docs/source_cmds.md). ## Output Formats +Table is the default format, however there are output formats of JSON (--json), CSV (--csv) , Markdown (--markdown) and HTML (--html) +See [output formats for more information](./docs/outputs-format.md). + ### Table Output A table is the default format when outputting information about hava sources @@ -293,28 +224,8 @@ hava source list --json | jq ] ``` -### CSV Output - -```bash -hava source list --csv -,DisplayName,Id,Info,Name,State,Type -1,dev,4f14c115-3b0d-40ea-b075-6df9b2fb81c9,AKIAIOSFODNN7EXAMPLE,dev,active,Sources::AWS::Keys -2,GCPDevChange3,f2a26440-10bf-43d1-9742-8361de30590f,credentials.json,GCPDevChange3,active,Sources::GCP::ServiceAccountCredentials -``` - - -### Markdown Output - -```bash -hava source list --markdown -| | DisplayName | Id | Info | Name | State | Type | -| ---:| --- | --- | --- | --- | --- | --- | -| 1 | dev | 4f14c115-3b0d-40ea-b075-6df9b2fb81c9 | AKIAIOSFODNN7EXAMPLE | dev | active | Sources::AWS::Keys | -| 2 | GCPDevChange3 | f2a26440-10bf-43d1-9742-8361de30590f | credentials.json | GCPDevChange3 | active | Sources::GCP::ServiceAccountCredentials | -``` - # Build Local Binary -`make local-build` +`make local-build` will build a local binary ## Testing Locally diff --git a/cicd-examples/README.md b/docs/cicd-examples/README.md similarity index 82% rename from cicd-examples/README.md rename to docs/cicd-examples/README.md index b8a381d..359a5ba 100644 --- a/cicd-examples/README.md +++ b/docs/cicd-examples/README.md @@ -16,7 +16,7 @@ The following are sample CICD pipelines for various platforms. We recommend choo ## Gitlab CI -- [Gitlab CI](./gitlab/.gitla-ci.yml) (Uses the docker image) +- [Gitlab CI](./gitlab/.gitlab-ci.yml) (Uses the docker image) ## Circle CI diff --git a/cicd-examples/azuredevops/azure-pipelines.yml b/docs/cicd-examples/azuredevops/azure-pipelines.yml similarity index 100% rename from cicd-examples/azuredevops/azure-pipelines.yml rename to docs/cicd-examples/azuredevops/azure-pipelines.yml diff --git a/cicd-examples/buildkite/pipeline.yml b/docs/cicd-examples/buildkite/pipeline.yml similarity index 100% rename from cicd-examples/buildkite/pipeline.yml rename to docs/cicd-examples/buildkite/pipeline.yml diff --git a/cicd-examples/circleci/config.yml b/docs/cicd-examples/circleci/config.yml similarity index 100% rename from cicd-examples/circleci/config.yml rename to docs/cicd-examples/circleci/config.yml diff --git a/cicd-examples/github/README.md b/docs/cicd-examples/github/README.md similarity index 100% rename from cicd-examples/github/README.md rename to docs/cicd-examples/github/README.md diff --git a/cicd-examples/github/cli-test.yml b/docs/cicd-examples/github/cli-test.yml similarity index 100% rename from cicd-examples/github/cli-test.yml rename to docs/cicd-examples/github/cli-test.yml diff --git a/cicd-examples/github/docker-test.yml b/docs/cicd-examples/github/docker-test.yml similarity index 100% rename from cicd-examples/github/docker-test.yml rename to docs/cicd-examples/github/docker-test.yml diff --git a/cicd-examples/gitlab/.gitlab-ci.yml b/docs/cicd-examples/gitlab/.gitlab-ci.yml similarity index 100% rename from cicd-examples/gitlab/.gitlab-ci.yml rename to docs/cicd-examples/gitlab/.gitlab-ci.yml diff --git a/cicd-examples/jenkins/Jenkinsfile b/docs/cicd-examples/jenkins/Jenkinsfile similarity index 100% rename from cicd-examples/jenkins/Jenkinsfile rename to docs/cicd-examples/jenkins/Jenkinsfile diff --git a/docs/outputs-format.md b/docs/outputs-format.md new file mode 100644 index 0000000..f6ad204 --- /dev/null +++ b/docs/outputs-format.md @@ -0,0 +1,119 @@ +## Output Formats + + + +### Table Output +A table is the default format when outputting information about hava sources + +```bash +hava source list +╭───┬───────────────┬──────────────────────────────────────┬──────────────────────┬───────────────┬────────┬─────────────────────────────────────────╮ +│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ +├───┼───────────────┼──────────────────────────────────────┼──────────────────────┼───────────────┼────────┼─────────────────────────────────────────┤ +│ 1 │ dev │ 4f14c115-3b0d-40ea-b075-6df9b2fb81c9 │ AKIAIOSFODNN7EXAMPLE │ dev │ active │ Sources::AWS::Keys │ +│ 2 │ GCPDevChange3 │ f2a26440-10bf-43d1-9742-8361de30590f │ credentials.json │ GCPDevChange3 │ active │ Sources::GCP::ServiceAccountCredentials │ +╰───┴───────────────┴──────────────────────────────────────┴──────────────────────┴───────────────┴────────┴─────────────────────────────────────────╯ +``` + +### Json Output + + +```bash +hava source list --json | jq +[ + { + "DisplayName": "dev", + "Id": "4f14c115-3b0d-40ea-b075-6df9b2fb81c9", + "Info": "AKIAIOSFODNN7EXAMPLE", + "Name": "dev", + "State": "active", + "Type": "Sources::AWS::Keys" + }, + { + "DisplayName": "GCPDevChange3", + "Id": "f2a26440-10bf-43d1-9742-8361de30590f", + "Info": "credentials.json", + "Name": "GCPDevChange3", + "State": "active", + "Type": "Sources::GCP::ServiceAccountCredentials" + } +] +``` + +### CSV Output + +```bash +hava source list --csv +,DisplayName,Id,Info,Name,State,Type +1,dev,4f14c115-3b0d-40ea-b075-6df9b2fb81c9,AKIAIOSFODNN7EXAMPLE,dev,active,Sources::AWS::Keys +2,GCPDevChange3,f2a26440-10bf-43d1-9742-8361de30590f,credentials.json,GCPDevChange3,active,Sources::GCP::ServiceAccountCredentials +``` + + +### Markdown Output + +```bash +hava source list --markdown +| | DisplayName | Id | Info | Name | State | Type | +| ---:| --- | --- | --- | --- | --- | --- | +| 1 | dev | 4f14c115-3b0d-40ea-b075-6df9b2fb81c9 | AKIAIOSFODNN7EXAMPLE | dev | active | Sources::AWS::Keys | +| 2 | GCPDevChange3 | f2a26440-10bf-43d1-9742-8361de30590f | credentials.json | GCPDevChange3 | active | Sources::GCP::ServiceAccountCredentials | +``` + + +### HTML Output + +``` +hava source list --html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 DisplayNameIdInfoNameStateType
1appGCP09409035-87d4-478b-bec0-25349825d390credentials.jsonappGCPactiveSources::GCP::ServiceAccountCredentials
2devTestAWSa2d8d0c8-0fd4-4483-ab2a-71e4ef58e093AKIAIOSFODNN7EXAMPLEdevTestAWSactiveSources::AWS::Keys
3devTestAWScarc3b9d2d7-0cb1-4fd1-92d7-beed7ceb7b22arn:aws:iam::777777777777:role/HavaCARdevTestAWScaractiveSources::AWS::CrossAccountRole
4devTestAzure76903928-8ae0-4ccb-8dee-ede61db9dc5cuPfVzmPStDe9yadevTestAzureinactiveSources::Azure::Credentials
+``` diff --git a/docs/source_cmds.md b/docs/source_cmds.md new file mode 100644 index 0000000..a2651ab --- /dev/null +++ b/docs/source_cmds.md @@ -0,0 +1,102 @@ +# Source Commands + +`hava source -h` + +```bash +Create/List/Delete/Update sources to Hava for different providers (AWS/Azure/Google Cloud) + +Usage: + hava source [flags] + hava source [command] + +Available Commands: + create Create sources to Hava + delete Delete sources to Hava + list List sources of Hava + sync Sync sources to Hava + update Update sources to Hava + +Flags: + --all hava source --all + -h, --help help for source + --sourceId string sourceId of AWS|Azure|GCP source +``` + +## Source List all + +`hava source list` + +``` +╭───┬─────────────┬──────────────────────────────────────┬──────────────────────┬────────────┬────────┬────────────────────╮ +│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ +├───┼─────────────┼──────────────────────────────────────┼──────────────────────┼────────────┼────────┼────────────────────┤ +│ 1 │ devTestAWS │ 8eb192e2-9beb-466b-ae14-c05fc8403cf4 │ AKIAIOSFODNN7EXAMPLE │ devTestAWS │ active │ Sources::AWS::Keys │ +╰───┴─────────────┴──────────────────────────────────────┴──────────────────────┴────────────┴────────┴────────────────────╯ +``` + +## Source List SourceID + +`hava source list --source-id a58b7cb1-f9da-42ad-9fc1-8dc61b0d3e38` + + +## Source Sync SourceID + +`hava source sync a58b7cb1-f9da-42ad-9fc1-8dc61b0d3e38` + + +## Source Create AWS (Using Access Keys) + +`hava source create aws --name dev --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY` + +```bash +[INFO] Created AWS Source for the following source: + +╭───┬─────────────┬──────────────────────────────────────┬──────────────────────┬────────────┬────────┬────────────────────╮ +│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ +├───┼─────────────┼──────────────────────────────────────┼──────────────────────┼────────────┼────────┼────────────────────┤ +│ 1 │ devTestAWS │ 040d5b5e-03b9-4343-9393-8ad0794512f4 │ AKIAIOSFODNN7EXAMPLE │ devTestAWS │ queued │ Sources::AWS::Keys │ +╰───┴─────────────┴──────────────────────────────────────┴──────────────────────┴────────────┴────────┴────────────────────╯ +``` + +## Source Create AWS (Using Cross Account Role) + +`hava source create aws --name devCAR --role-arn $AWS_CROSS_ACCOUNT_ROLE` + +```bash +[INFO] Created AWS Source for the following source: + +╭───┬─────────────┬──────────────────────────────────────┬────────────────────────────────────────┬────────┬────────┬────────────────────────────────╮ +│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ +├───┼─────────────┼──────────────────────────────────────┼────────────────────────────────────────┼────────┼────────┼────────────────────────────────┤ +│ 1 │ devCAR │ 31f9b6a6-4e48-400a-8ced-5bfc2a1aacc2 │ arn:aws:iam::123456789012:role/HavaCAR │ devCAR │ queued │ Sources::AWS::CrossAccountRole │ +╰───┴─────────────┴──────────────────────────────────────┴────────────────────────────────────────┴────────┴────────┴────────────────────────────────╯ +``` + +## Source Create GCP + +`hava source create gcp --name GCPDev --configFile $GCP_ENCODED_FILE` + +```bash +[INFO] Created GCP Source for the following source: + +╭───┬─────────────┬──────────────────────────────────────┬──────────────────┬────────┬────────┬─────────────────────────────────────────╮ +│ │ DISPLAYNAME │ ID │ INFO │ NAME │ STATE │ TYPE │ +├───┼─────────────┼──────────────────────────────────────┼──────────────────┼────────┼────────┼─────────────────────────────────────────┤ +│ 1 │ GCPDev │ 8818d864-46e9-4b8d-acdd-a31d8936e62f │ credentials.json │ GCPDev │ queued │ Sources::GCP::ServiceAccountCredentials │ +╰───┴─────────────┴──────────────────────────────────────┴──────────────────┴────────┴────────┴─────────────────────────────────────────╯ +``` + +## Source Create Azure + +`hava create source azure --name AzureDev --client-id $ARM_CLIENT_ID --tenant-id $ARM_TENANT_ID --subscription-id $ARM_SUBSCRIPTION_ID` + + +## Source Delete + +`hava source delete 22872411-20e8-4b6e-aa46-41866c9c1897` + + +## Source Update AWS|AZURE|GCP + +`hava source update gcp --name GCPDevChange --source-id f2a26440-10bf-43d1-9742-8361de30590f` + diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..514fd04 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,55 @@ +## Usage + +### Print hava CLI help + +![print help](./images/hava_help.cast.gif) + + +`hava -h` + +```bash +A CLI to interface with the Hava platform. + +Hava CLI empowers engineers the ability to automate and interact +with the Hava platform. + +Usage: + hava [command] + +Available Commands: + completion Generate the autocompletion script for the specified shell + help Help about any command + source Create/List/Delete/Update sources to Hava + +Flags: + --autoapprove Auto approve the hava command. --autoapprove, false by default + -h, --help help for hava + -v, --version version for hava + +Use "hava [command] --help" for more information about a command. +``` + +### Create and List Sources + +![hava_create_list](./images/hava_create_list_sources.cast.gif) + +### CLI JSON Output + +![hava_json_out](./images/hava_CLI_json_output.cast.gif) + + +### Sync Sources + +![hava_print_source](./images/hava_source_sync.cast.gif) + +### Delete Sources + +![hava_delete_sources](./images/hava_source_delete.cast.gif) + +### CLI Completion Setup + +![hava_cli_completion](./images/hava_cli_completion.cast.gif) + +### CLI Interactive Config Setup + +![hava_config_setup](./images/hava_config_setup.cast.gif) \ No newline at end of file