diff --git a/docs/reference/ecctl-installing.md b/docs/reference/ecctl-installing.md index 6fdf1b001..698b7fc5c 100644 --- a/docs/reference/ecctl-installing.md +++ b/docs/reference/ecctl-installing.md @@ -1,46 +1,246 @@ --- mapped_pages: - https://www.elastic.co/guide/en/ecctl/current/ecctl-installing.html +applies_to: + serverless: ga + deployment: + ess: ga + ece: ga all --- # Installing [ecctl-installing] -The latest stable binaries can be found on the [release page](https://github.com/elastic/ecctl/releases) or compiled from the latest on the master branch to leverage the most recently merged features. +This guide explains how to install the current {{version.ecctl}} release of `ecctl` on supported operating systems. Release artifacts are available from the [release page](https://github.com/elastic/ecctl/releases). If you need changes that are not yet included in the latest release, you can build `ecctl` from source. -To learn more about building ecctl from the source, see the steps from our [Setting up a dev environment](https://github.com/elastic/ecctl/blob/master/CONTRIBUTING.md#setting-up-a-dev-environment). +## Installation methods [ecctl-installing-methods] +You can install `ecctl` using one of these methods: + +- **[macOS](#ecctl-installing-macos)**: Homebrew (recommended) or archive (`.tar.gz`) +- **[Linux](#ecctl-installing-linux)**: `deb`, `rpm`, or archive (`.tar.gz`) +- **[Windows](#ecctl-installing-windows)**: Install with `go install` +- **[Any OS](#ecctl-installing-source)**: Build from source + +For shell completions, refer to [Enable shell completions](#ecctl-installing-completions). If you download release artifacts (`.tar.gz`, `.deb`, or `.rpm`), refer to [Verify downloaded artifacts](#ecctl-installing-verify-checksums) to optionally verify their SHA-256 checksums before installation. ## Install on macOS [ecctl-installing-macos] -The simplest installation for macOS users is to install ecctl with [Homebrew](https://brew.sh/): +### Homebrew (recommended) [ecctl-installing-macos-homebrew] + +The simplest installation for macOS users is to install `ecctl` with [Homebrew](https://brew.sh/): +```bash +brew tap elastic/tap +brew install elastic/tap/ecctl ``` -$ brew tap elastic/tap -$ brew install elastic/tap/ecctl - -Updating Homebrew... -==> Installing ecctl from elastic/tap -... -==> Caveats -To get autocompletions working make sure to run "source <(ecctl generate completions)". -If you prefer to add to your shell interpreter configuration file run, for bash or zsh respectively: -* `echo "source <(ecctl generate completions)" >> ~/.bash_profile` -* `echo "source <(ecctl generate completions)" >> ~/.zshrc`. -==> Summary -🍺 /usr/local/Cellar/ecctl/1.5.0: 5 files, 22.6MB, built in 4 seconds + +### Install from archive (.tar.gz) [ecctl-installing-macos-archive] + +1. Download the `.tar.gz` archive for your architecture from the [release page](https://github.com/elastic/ecctl/releases): + + ```bash subs=true + # Apple Silicon + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_darwin_arm64.tar.gz + + # Intel (x86_64) + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_darwin_amd64.tar.gz + + ``` + +2. Extract the archive and move the `ecctl` binary to a directory in your `PATH`, for example `/usr/local/bin`. +3. Verify the installation: + +```bash +ecctl version ``` -::::{note} -To get autocompletions working, follow the instructions in the Homebrew output. -:::: +## Install on Linux [ecctl-installing-linux] + +### Install with deb/rpm packages (recommended) [ecctl-installing-linux-packages] + +Linux packages are published with every release and are available from the [release page](https://github.com/elastic/ecctl/releases). + +- Debian/Ubuntu: `ecctl__linux_64-bit.deb`, `ecctl__linux_32-bit.deb`, or `ecctl__linux_arm64.deb` +- RHEL/CentOS/Fedora: `ecctl__linux_64-bit.rpm`, `ecctl__linux_32-bit.rpm`, or `ecctl__linux_arm64.rpm` + +Download the package that matches your system and architecture, then install it with your package manager. For example: + +* On Debian/Ubuntu systems: + + ```bash subs=true + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_linux_64-bit.deb + sudo dpkg -i ecctl_{{version.ecctl}}_linux_64-bit.deb + ``` + +* On RHEL/CentOS/Fedora systems: + + ```bash subs=true + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_linux_64-bit.rpm + sudo rpm -i ecctl_{{version.ecctl}}_linux_64-bit.rpm + ``` + +### Install from archive (.tar.gz) [ecctl-installing-linux-archive] + +1. Download the Linux `.tar.gz` archive for your architecture from the [release page](https://github.com/elastic/ecctl/releases): + + ```bash subs=true + # x86_64 (AMD64) + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_linux_amd64.tar.gz + + # ARM64 + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_linux_arm64.tar.gz + + # x86 (386) + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_linux_386.tar.gz + ``` + +2. Extract the archive and move the `ecctl` binary to a directory in your `PATH`, for example `/usr/local/bin`: + + ```bash subs=true + tar -xzf ecctl_{{version.ecctl}}_linux_amd64.tar.gz + sudo cp ecctl /usr/local/bin + ``` + +3. Verify the installation: + + ```bash + ecctl version + ``` + +## Install on Windows [ecctl-installing-windows] + +Official Windows binaries are not currently published. Install `ecctl` with `go install`: + +1. Install [Go](https://go.dev/dl/). +2. Open **Command Prompt** or **PowerShell**. +3. Confirm Go is available: + + ```powershell + go version + ``` + +4. Install `ecctl`: + + ```powershell + go install github.com/elastic/ecctl@latest + ``` + + To install a different version, replace `@latest` with a specific tag, for example: + + ```powershell subs=true + go install github.com/elastic/ecctl@v{{version.ecctl}} + ``` +5. Add Go's binary directory to your `PATH` if needed (`%USERPROFILE%\go\bin` by default). +6. Verify the installation: + ```powershell + ecctl version + ``` -## Upgrade on macOS [ecctl-upgrading-macos] +## Build from source (all operating systems) [ecctl-installing-source] -To upgrade ecctl via brew: +Use this method if you need changes that are not yet included in an official release or want to build from a specific branch or commit. +### Prerequisites [ecctl-installing-source-prerequisites] + +- [Go](https://go.dev/doc/install) +- `git` + +### Build steps [ecctl-installing-source-steps] + +Clone the repository and build locally: + +```bash +git clone https://github.com/elastic/ecctl.git +cd ecctl +go build . ``` -$ brew upgrade ecctl + +This command produces an `ecctl` binary (`ecctl.exe` on Windows) in the current directory. + +You can also install directly with Go: + +```bash +go install . +``` + +This installs the binary into `GOBIN` (or `GOPATH/bin` if `GOBIN` is not set). Make sure that location is in your `PATH`. + +For contributor-focused setup details, see [Setting up a dev environment](https://github.com/elastic/ecctl/blob/master/CONTRIBUTING.md#setting-up-a-dev-environment). + +## Verify downloaded artifacts (optional) [ecctl-installing-verify-checksums] + +If you download release artifacts (`.tar.gz`, `.deb`, or `.rpm`), you can optionally verify their SHA-256 checksums before installing them. + +1. Download the checksum file: + + ```bash subs=true + curl -L -O https://download.elastic.co/downloads/ecctl/{{version.ecctl}}/ecctl_{{version.ecctl}}_checksums.txt + ``` + +2. Compute the SHA-256 checksum of the downloaded artifact. For example: + + ```bash subs=true + # macOS + shasum -a 256 ecctl_{{version.ecctl}}_darwin_arm64.tar.gz + + # Linux + sha256sum ecctl_{{version.ecctl}}_linux_amd64.tar.gz + ``` + +3. Display the expected checksum from the checksums file. For example: + + ```bash subs=true + grep "ecctl_{{version.ecctl}}_linux_amd64.tar.gz" ecctl_{{version.ecctl}}_checksums.txt + ``` + + Verify that the checksum matches the value returned by the checksum command. + +## Enable shell completions [ecctl-installing-completions] + +You can enable shell completions after installation. These instructions apply to Bash and Zsh on macOS and Linux. + +Load completions for the current shell session: + +```bash +source <(ecctl generate completions) ``` +Persist completions across sessions: + +- Bash: `echo "source <(ecctl generate completions)" >> ~/.bash_profile` +- Zsh: `echo "source <(ecctl generate completions)" >> ~/.zshrc` + +## Troubleshooting [ecctl-installing-verify-troubleshooting] + +- `ecctl: command not found`: Add the binary location to your `PATH`. +- `permission denied` when copying to system paths: Use elevated privileges (`sudo` on Linux/macOS). +- `go: command not found` on Windows: Ensure Go is installed correctly and restart the terminal after installation. + +## Upgrade [ecctl-upgrading] + +Use the same installation method you used to install `ecctl`: + +- **Homebrew (macOS)**: + ```bash + brew upgrade ecctl + ``` +- **Linux package (`deb`/`rpm`)**: Install a newer package from the [release page](https://github.com/elastic/ecctl/releases) +- **Archive (`.tar.gz`) (macOS/Linux)**: Download the latest archive from the [release page](https://github.com/elastic/ecctl/releases) and replace the existing binary. +- **Windows (`go install`)**: + ```powershell + go install github.com/elastic/ecctl@latest + ``` + +## Next steps [ecctl-installing-next-steps] + +After installing `ecctl`, continue with: + +- [Configure ecctl](/reference/ecctl-configuring.md) +- [Initialize your first configuration](/reference/ecctl_init.md) +- [Authentication methods](/reference/ecctl-authentication.md) +- [Usage examples](/reference/ecctl-examples.md) +- [Command reference](/reference/ecctl.md) + +If you use serverless projects, refer to [Manage serverless projects](/reference/ecctl_project.md)