From b7841132ef31628c19cb43e788d8281752b00003 Mon Sep 17 00:00:00 2001 From: Evan Baker Date: Fri, 29 Mar 2024 15:30:27 -0500 Subject: [PATCH] docs: add instructions to install the CLI through Krew (#193) # Description [Retina is available in Krew!](https://github.com/kubernetes-sigs/krew-index/pull/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 Co-authored-by: Jacques I Massa --- .goreleaser.yaml | 2 +- README.md | 47 ++++++++++++++++++-------------------- docs/installation/cli.md | 23 ++++++++++++++----- docs/installation/setup.md | 30 ++++++++++++------------ 4 files changed, 56 insertions(+), 46 deletions(-) diff --git a/.goreleaser.yaml b/.goreleaser.yaml index 78164e1806..0e0cfdfd6b 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -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: diff --git a/README.md b/README.md index eeb59e372d..b907aff491 100644 --- a/README.md +++ b/README.md @@ -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\]" ``` @@ -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 --namespace --selector ``` For further CLI documentation, see [Capture with Retina CLI](https://retina.sh/docs/captures/cli). @@ -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 \ diff --git a/docs/installation/cli.md b/docs/installation/cli.md index 7e2e6640ce..613340497d 100644 --- a/docs/installation/cli.md +++ b/docs/installation/cli.md @@ -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. diff --git a/docs/installation/setup.md b/docs/installation/setup.md index f080f212e0..90b0b69ff0 100644 --- a/docs/installation/setup.md +++ b/docs/installation/setup.md @@ -6,16 +6,15 @@ 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\]" ``` @@ -23,11 +22,12 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \ ### 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 \ @@ -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 \ @@ -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 \