Skip to content

Commit

Permalink
docs: add instructions to install the CLI through Krew (#193)
Browse files Browse the repository at this point in the history
# Description

[Retina is available in
Krew!](kubernetes-sigs/krew-index#3722)
Updates the docs with installation instructions using Krew.
Also updates the Helm chart installation instructions to fetch the
latest released version instead of hardcoding a version.

## Related Issue

related to #108 
provides a permanent fix for #163

---------

Signed-off-by: Evan Baker <[email protected]>
Co-authored-by: Jacques I Massa <[email protected]>
  • Loading branch information
rbtr and jimassa authored Mar 29, 2024
1 parent 8df153c commit b784113
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 46 deletions.
2 changes: 1 addition & 1 deletion .goreleaser.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ builds:
- windows
- darwin
ldflags:
- -X github.com/microsoft/retina/cli/cmd.Version={{.Version}}
- -X github.com/microsoft/retina/cli/cmd.Version=v{{.Version}}
main: cli/main.go

archives:
Expand Down
47 changes: 22 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,12 @@ Retina has two major features:
Retina can be installed using the Helm chart from GHCR:

```bash
# Set the version to a specific version here or get latest version from GitHub API.
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--version $VERSION \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set logLevel=info \
--set enabledPlugin_linux="\[dropreason\,packetforward\,linuxutil\,dns\]"
```
Expand All @@ -56,31 +58,25 @@ After Helm install, follow steps in [Using Prometheus and Grafana](https://retin

#### Captures via CLI

Currently, Retina CLI only supports Linux.
The preferred way to install the Retina CLI using [Krew](https://krew.sigs.k8s.io/).

- Option 1: Download from Release

Download the correct `kubectl-retina` package for your platform from the latest [Retina release](https://github.com/microsoft/retina/releases).
Feel free to move the binary to `/usr/local/bin/`, or add it to your `PATH` otherwise.

- Option 2: Build from source

Requirements:

- go 1.21 or newer
```bash
kubectl krew install retina
```

Clone the Retina repo and execute:
Other installation options are documented in [CLI Installation](https://retina.sh/docs/installation/cli).

```shell
go build -o bin/kubectl-retina cli/main.go
```
Verify installation:

and move bin/kubectl-retina in to your $PATH.
```bash
$ kubectl retina version
v0.0.4 # or latest version
```

Execute Retina:
To quickly start creating a capture:

```shell
kubectl-retina capture create --help
```bash
kubectl retina capture create --name <my-capture> --namespace <my-namespace> --selector <app=my-app>
```

For further CLI documentation, see [Capture with Retina CLI](https://retina.sh/docs/captures/cli).
Expand All @@ -90,10 +86,11 @@ For further CLI documentation, see [Capture with Retina CLI](https://retina.sh/d
Install Retina using Helm:

```bash
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--version $VERSION \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set image.pullPolicy=Always \
--set logLevel=info \
--set os.windows=true \
Expand Down
23 changes: 17 additions & 6 deletions docs/installation/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,34 @@ Currently, Retina CLI supports Linux, Windows, and MacOS on x86_64 and ARM64 pla

For CLI usage, see [Capture with Retina CLI](../captures/cli.md).

## Option 1: Download from Release
## Option 1: Install using Krew

Download `kubectl-retina` from the latest [Retina release](https://github.com/microsoft/retina/releases).
Feel free to move the binary to `/usr/local/bin/`, or add it to your `PATH` otherwise.
Retina CLI is available as a [Krew plugin](https://krew.sigs.k8s.io/)! To install it, run:

```bash
kubectl krew install retina
```

## Option 2: Download the binary from the latest release on GitHub

Download the `kubectl-retina` package for your platform from the latest [Retina release](https://github.com/microsoft/retina/releases/latest).

## Option 2: Build from source

Building the CLI requires go1.21 or greater.

To build the CLI simply with Go:
To build the CLI simply and quickly with Go:

```bash
go build -o bin/kubectl-retina cli/main.go
```

To cross-compile for all supported platforms, use [GoReleaser](https://goreleaser.com/):
The release pipeline uses [GoReleaser](https://goreleaser.com/), which is the recommended way to build the CLI.

To build the CLI with GoReleaser:

```bash
goreleaser build --snapshot --clean
goreleaser build --snapshot --clean [--single-target]
```

Note: --single-target is optional and can be used to build for the current platform only. Omit it to cross-compile for all supported platforms.
30 changes: 16 additions & 14 deletions docs/installation/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,28 @@ Note: you can also run captures with just the [CLI](./cli.md).

## Installation

When installing with helm, substitute the `version` and image `tag` arguments to the desired version, if different.

### Basic Mode

```shell
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--version $VERSION \
--namespace kube-system \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set logLevel=info \
--set enabledPlugin_linux="\[dropreason\,packetforward\,linuxutil\,dns\]"
```

### Basic Mode (with Capture support)

```shell
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--version $VERSION \
--namespace kube-system \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set logLevel=info \
--set image.pullPolicy=Always \
--set logLevel=info \
Expand All @@ -43,11 +43,12 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
See [Metric Modes](../metrics/modes.md).

```shell
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--version $VERSION \
--namespace kube-system \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set image.pullPolicy=Always \
--set logLevel=info \
--set os.windows=true \
Expand All @@ -64,11 +65,12 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
See [Metric Modes](../metrics/modes.md).

```shell
VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
--version v0.0.2 \
--version $VERSION \
--namespace kube-system \
--set image.tag=v0.0.2 \
--set operator.tag=v0.0.2 \
--set image.tag=$VERSION \
--set operator.tag=$VERSION \
--set image.pullPolicy=Always \
--set logLevel=info \
--set os.windows=true \
Expand Down

0 comments on commit b784113

Please sign in to comment.