Guides

Installation

Install kuma-migrator with Homebrew, from a release archive, or from source, and verify a release archive.

Homebrew

Supported platforms: macOS Apple Silicon (arm64), macOS Intel (amd64), Linux amd64, Linux arm64.

brew tap bcollard/kuma-migrator
brew install --cask kuma-migrator

Or in one command:

brew install --cask bcollard/kuma-migrator/kuma-migrator

Upgrade:

brew upgrade --cask kuma-migrator

Release archives

Download the archive for your platform from GitHub Releases.

Platform Architecture Archive
Linux amd64, arm64 kuma-migrator_<version>_linux_<arch>.tar.gz
macOS amd64 (Intel), arm64 (Apple Silicon) kuma-migrator_<version>_darwin_<arch>.tar.gz
Windows amd64 kuma-migrator_<version>_windows_amd64.zip

Linux amd64:

VERSION=$(gh release view --repo Kong/kuma-migrator --json tagName --jq '.tagName' | tr -d 'v')
curl -L "https://github.com/Kong/kuma-migrator/releases/latest/download/kuma-migrator_${VERSION}_linux_amd64.tar.gz" | tar xz
sudo mv kuma-migrator /usr/local/bin/

Linux arm64:

VERSION=$(gh release view --repo Kong/kuma-migrator --json tagName --jq '.tagName' | tr -d 'v')
curl -L "https://github.com/Kong/kuma-migrator/releases/latest/download/kuma-migrator_${VERSION}_linux_arm64.tar.gz" | tar xz
sudo mv kuma-migrator /usr/local/bin/

From source

Requires Go 1.24 or later.

git clone https://github.com/Kong/kuma-migrator.git
cd kuma-migrator
make build
# binary at ./dist/kuma-migrator

Verify a release archive

Every release archive carries a build provenance attestation. It binds the archive to the commit and the GitHub Actions run that built it. Check it with the GitHub CLI (gh attestation verify is built in):

VERSION=$(gh release view --repo Kong/kuma-migrator --json tagName --jq '.tagName' | tr -d 'v')
curl -LO "https://github.com/Kong/kuma-migrator/releases/latest/download/kuma-migrator_${VERSION}_linux_amd64.tar.gz"
gh attestation verify "kuma-migrator_${VERSION}_linux_amd64.tar.gz" --repo Kong/kuma-migrator

The Homebrew cask is built from the same archives, and its sha256 fields match the attested checksums.txt.

Runtime requirements

Tool Needed for
kubectl on PATH extract --kube-context, and applying Kubernetes-format output
kumactl on PATH extract --kumactl-context against a self-hosted control plane, and applying with kumactl

migrate needs neither: it reads and writes local files only.

For a Kong Mesh control plane, use the Kong Mesh build of kumactl. The Kuma OSS binary refuses to talk to a Kong Mesh control plane. Extraction from Konnect uses direct HTTPS calls and only reads the context from the kumactl config file. For the token, see Konnect read-only access.

Check the installed version:

kuma-migrator version

Next: Getting started.