Skip to content

Commit

Permalink
reorganise documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
carljavier committed Sep 11, 2023
1 parent 3c6c9a3 commit c432e98
Show file tree
Hide file tree
Showing 13 changed files with 299 additions and 112 deletions.
133 changes: 22 additions & 111 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -18,38 +16,39 @@ 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)
- [Precedence](#precedence)
- [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)

## Installation

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


Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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`
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion cicd-examples/README.md → docs/cicd-examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
119 changes: 119 additions & 0 deletions docs/outputs-format.md
Original file line number Diff line number Diff line change
@@ -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
<table class="go-pretty-table">
<thead>
<tr>
<th>&nbsp;</th>
<th>DisplayName</th>
<th>Id</th>
<th>Info</th>
<th>Name</th>
<th>State</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr>
<td align="right">1</td>
<td>appGCP</td>
<td>09409035-87d4-478b-bec0-25349825d390</td>
<td>credentials.json</td>
<td>appGCP</td>
<td>active</td>
<td>Sources::GCP::ServiceAccountCredentials</td>
</tr>
<tr>
<td align="right">2</td>
<td>devTestAWS</td>
<td>a2d8d0c8-0fd4-4483-ab2a-71e4ef58e093</td>
<td>AKIAIOSFODNN7EXAMPLE</td>
<td>devTestAWS</td>
<td>active</td>
<td>Sources::AWS::Keys</td>
</tr>
<tr>
<td align="right">3</td>
<td>devTestAWScar</td>
<td>c3b9d2d7-0cb1-4fd1-92d7-beed7ceb7b22</td>
<td>arn:aws:iam::777777777777:role/HavaCAR</td>
<td>devTestAWScar</td>
<td>active</td>
<td>Sources::AWS::CrossAccountRole</td>
</tr>
<tr>
<td align="right">4</td>
<td>devTestAzure</td>
<td>76903928-8ae0-4ccb-8dee-ede61db9dc5c</td>
<td>uPfVzmPStDe9ya</td>
<td>devTestAzure</td>
<td>inactive</td>
<td>Sources::Azure::Credentials</td>
</tr>
</tbody>
</table>
```
Loading

0 comments on commit c432e98

Please sign in to comment.