From f76a322166eed508bcff9c7cb54af9067480a841 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Wed, 19 Aug 2026 12:29:55 -0700 Subject: [PATCH] Use Homebrew to install cortextool in the getting-started guides The `cortexproject/homebrew-tap` tap now publishes `cortextool`, so the getting-started guides can install it with a single command instead of downloading a pinned release binary or running it in Docker. A host-installed `cortextool` reaches Cortex on `localhost` on every platform, which lets the single-binary guide drop its duplicated Linux vs macOS/Windows command blocks: one command now works everywhere. Docker is kept as a fallback since it is the only option for native Windows without WSL2. Also: - Bump the retained Docker fallbacks from v0.17.0 to v0.21.1. - Drop the `wget`/`chmod`/`sudo mv` install blocks in the microservices guide, which pinned v0.17.0 and downloaded the x86_64 macOS binary even on Apple Silicon. - Fix the Compose network name in the single-binary guide. Compose v2 derives the project name from the project directory's basename, and Step 1 has users `cd cortex/docs/getting-started`, so the network is `getting-started_default`, not `cortex-docs-getting-started_default`. - Replace the "cortextool fails on macOS/Windows" troubleshooting entry, which is obsolete now that Homebrew is the primary path, with one covering what can actually go wrong. Signed-off-by: Charlie Le --- docs/getting-started/microservices.md | 19 ++++------ docs/getting-started/single-binary.md | 52 ++++++++++++--------------- 2 files changed, 29 insertions(+), 42 deletions(-) diff --git a/docs/getting-started/microservices.md b/docs/getting-started/microservices.md index 3dde9b54b68..0e9f4e72c62 100644 --- a/docs/getting-started/microservices.md +++ b/docs/getting-started/microservices.md @@ -34,7 +34,7 @@ This guide will help you run Cortex in microservices mode using Kubernetes (Kind ### Optional Tools -- [cortextool](https://github.com/cortexproject/cortex-tools/) - For managing rules and alerts +- [cortextool](https://github.com/cortexproject/cortex-tools/) - For managing rules and alerts (install with `brew install cortexproject/tap/cortextool`) - [jq](https://jqlang.github.io/jq/) - For parsing JSON responses ## Architecture @@ -373,25 +373,19 @@ kubectl --namespace cortex port-forward svc/cortex-nginx 8080:80 & ### Install cortextool (if needed) -**macOS:** ```sh -wget https://github.com/cortexproject/cortex-tools/releases/download/v0.17.0/cortextool_0.17.0_mac-os_x86_64 -O cortextool -chmod +x cortextool -sudo mv cortextool /usr/local/bin/ +brew install cortexproject/tap/cortextool ``` -**Linux:** -```sh -wget https://github.com/cortexproject/cortex-tools/releases/download/v0.17.0/cortextool_0.17.0_linux_x86_64 -O cortextool -chmod +x cortextool -sudo mv cortextool /usr/local/bin/ -``` +Works on macOS and Linux (including WSL2), builds from source, takes about a minute. **Or use Docker:** ```sh -alias cortextool="docker run --rm --network host -v $(pwd):/workspace -w /workspace quay.io/cortexproject/cortex-tools:v0.17.0" +alias cortextool="docker run --rm --network host -v $(pwd):/workspace -w /workspace quay.io/cortexproject/cortex-tools:v0.21.1" ``` +The Docker alias needs `--network host` to reach the `kubectl port-forward` on your host, which only works on Linux. On macOS and Windows, install cortextool with Homebrew instead. + ### Load Recording and Alerting Rules ```sh @@ -594,6 +588,7 @@ Kind requires Docker to have enough resources: ### cortextool commands fail - Make sure port-forward is running: `kubectl --namespace cortex port-forward svc/cortex-nginx 8080:80 &` - Verify Cortex is responding: `curl http://localhost:8080/ready` +- If you're using the Docker alias, note that `--network host` only works on Linux. Install cortextool with `brew install cortexproject/tap/cortextool` to run it directly against the port-forward on any platform. ## Clean Up diff --git a/docs/getting-started/single-binary.md b/docs/getting-started/single-binary.md index fc9c40ce064..1a0424f05c1 100644 --- a/docs/getting-started/single-binary.md +++ b/docs/getting-started/single-binary.md @@ -32,7 +32,7 @@ This guide will help you get Cortex running in single-binary mode using Docker C ### Optional Tools -- [cortextool](https://github.com/cortexproject/cortex-tools/) - For managing rules and alerts (we'll use Docker to run this) +- [cortextool](https://github.com/cortexproject/cortex-tools/) - For managing rules and alerts (install with `brew install cortexproject/tap/cortextool`) ## Architecture @@ -159,22 +159,27 @@ Cortex can evaluate PromQL recording rules and alerting rules, similar to Promet The repository includes example rules in `rules.yaml` and `alerts.yaml`. -### Load Rules into Cortex +### Install cortextool -**For Linux users:** ```sh -docker run --network host \ - -v "$(pwd):/workspace" -w /workspace \ - quay.io/cortexproject/cortex-tools:v0.17.0 \ - rules sync rules.yaml alerts.yaml --id cortex --address http://localhost:9009 +brew install cortexproject/tap/cortextool ``` -**For macOS/Windows users:** +Works on macOS and Linux (including WSL2), builds from source, takes about a minute. + +**Or use Docker:** ```sh -docker run --network cortex-docs-getting-started_default \ - -v "$(pwd):/workspace" -w /workspace \ - quay.io/cortexproject/cortex-tools:v0.17.0 \ - rules sync rules.yaml alerts.yaml --id cortex --address http://cortex:9009 +alias cortextool="docker run --rm --network getting-started_default \ + -v $(pwd):/workspace -w /workspace \ + quay.io/cortexproject/cortex-tools:v0.21.1" +``` + +With the Docker alias, use `--address http://cortex:9009` instead of `http://localhost:9009` below — the container reaches Cortex over the Compose network, not your host. + +### Load Rules into Cortex + +```sh +cortextool rules sync rules.yaml alerts.yaml --id cortex --address http://localhost:9009 ``` **Note:** The `--id cortex` flag specifies the tenant ID. Cortex is multi-tenant, so rules are namespaced by tenant. @@ -194,20 +199,8 @@ Cortex includes a multi-tenant Alertmanager that receives alerts from the ruler. ### Load Alertmanager Configuration -**For Linux users:** -```sh -docker run --network host \ - -v "$(pwd):/workspace" -w /workspace \ - quay.io/cortexproject/cortex-tools:v0.17.0 \ - alertmanager load alertmanager-config.yaml --id cortex --address http://localhost:9009 -``` - -**For macOS/Windows users:** ```sh -docker run --network cortex-docs-getting-started_default \ - -v "$(pwd):/workspace" -w /workspace \ - quay.io/cortexproject/cortex-tools:v0.17.0 \ - alertmanager load alertmanager-config.yaml --id cortex --address http://cortex:9009 +cortextool alertmanager load alertmanager-config.yaml --id cortex --address http://localhost:9009 ``` ### View Alertmanager in Grafana @@ -484,11 +477,10 @@ lsof -i :3000 # Grafana 2. Check Cortex is receiving metrics: `curl "http://localhost:9009/prometheus/api/v1/query?query=up"` 3. Check Grafana datasource: Settings → Data sources → Cortex → Test -### cortextool fails on macOS/Windows -The `--network host` flag doesn't work on macOS/Windows. Use the Docker network name instead: -```sh -docker run --network cortex-docs-getting-started_default ... -``` +### cortextool cannot reach Cortex +1. Check the binary is on your `PATH`: `cortextool version` +2. Check Cortex is up: `docker compose ps` should show `cortex` as healthy +3. If you're using the Docker alias instead of a host install, use `--address http://cortex:9009` — a container can't reach Cortex on your host's `localhost` ### Out of memory errors Increase Docker's memory limit to 4GB or more: