kubectl-beam

A kubectl plugin for connecting to BEAM (Erlang VM) nodes running in Kubernetes pods.

Installation

Using Make

make install

This installs the plugin to ~/.local/bin/kubectl-beam. Make sure ~/.local/bin is in your PATH.

Manual Installation

Copy the kubectl-beam script to any directory in your PATH:

cp kubectl-beam /usr/local/bin/
chmod +x /usr/local/bin/kubectl-beam

Verify Installation

kubectl beam --version

Requirements

• kubectl configured and connected to a Kubernetes cluster
• For IEx shells: Elixir installed locally
• For Erlang shells: Erlang/OTP installed locally
• For Observer mode: Erlang/OTP with wx support

Note: For IEx remote shells, your local Erlang/Elixir versions should match the deployed pod versions to avoid compatibility issues. The erl command is more forgiving with version mismatches.

Usage

Basic Examples

Connect to a pod using IEx:

kubectl beam iex my-app-pod

Connect to a pod in a specific namespace:

kubectl beam iex -n production my-app-pod

Connect using Erlang shell:

kubectl beam erl my-app-pod

Observer Mode

Start the Erlang Observer GUI connected to a remote node:

kubectl beam iex --observer -n production my-app-pod

This launches the Observer application locally, allowing you to inspect processes, memory usage, and other runtime metrics on the remote node.

Advanced Usage

Use long names instead of short names:

kubectl beam iex -l my-app-pod

Specify an explicit cookie:

kubectl beam iex --cookie mysecretcookie my-app-pod

Specify a custom cookie path on the pod:

kubectl beam iex --cookie-path /app/config/.erlang.cookie my-app-pod

Specify a cookie from a custom environment variable:

kubectl beam iex --cookie-env MY_COOKIE_VAR my-app-pod

Connect to a specific container in a multi-container pod:

kubectl beam iex -c app-container my-app-pod

How It Works

The plugin establishes a connection to remote BEAM nodes by:

1. Port-forwarding EPMD (port 4369) and Erlang distribution ports (9100-9109) from the pod to localhost
2. Automatically detecting or accepting a specified Erlang cookie
3. Configuring local DNS resolution to map the pod IP to localhost
4. Starting a local hidden BEAM node that connects to the remote node via --remsh

This approach provides full terminal support because the shell runs locally while communicating with the remote node through the port-forward tunnel.

Cookie Detection

The plugin attempts to detect the Erlang cookie in the following order:

1. Explicitly provided via --cookie flag
2. From a custom path via --cookie-path flag
3. From environment variables (tried in order):
   • $RELEASE_COOKIE
   • $ERLANG_COOKIE
   • $COOKIE
4. From common file paths:
   • /opt/app/releases/COOKIE
   • /app/releases/COOKIE
   • /opt/release/COOKIE
   • /release/COOKIE
   • ~/.erlang.cookie
   • /root/.erlang.cookie

Flags

Flag	Description	Default
-n, --namespace	Kubernetes namespace	default
-c, --container	Container name (for multi-container pods)
--observer	Start Observer GUI	false
-l, --long-names	Use long names	false
--cookie	Explicit Erlang cookie	Auto-detected
--cookie-path	Path to cookie file on pod
--cookie-env	Environment variable containing cookie	RELEASE_COOKIE

Troubleshooting

Cannot detect cookie

If the plugin cannot automatically detect the cookie, specify it explicitly:

kubectl beam iex --cookie yourcookie my-app-pod

Or specify the path where the cookie is stored:

kubectl beam iex --cookie-path /custom/path/to/.erlang.cookie my-app-pod

Port forwarding fails

Ensure no other processes are using ports 4369 or 9100-9109 on your local machine.

Multiple nodes detected

If multiple BEAM nodes are running in the same pod, set the NODE_BASENAME environment variable in your pod to specify which node to connect to.

Observer requires wx support

If Observer mode fails with an error about wx, ensure your local Erlang installation includes wx support:

erl -noshell -eval 'wx:new(), init:stop()'

Examples

The examples/ directory contains minimal Erlang and Elixir applications demonstrating both short names (sname) and long names (name) for testing kubectl-beam.

Quick Start with Examples

# Setup local test environment with kind
./examples/setup-local.sh

# Connect to test pods
kubectl beam erl erlang-app-sname --cookie test_cookie_secret
kubectl beam iex elixir-app-name --cookie test_cookie_secret -l

See examples/README.md for detailed information about short names vs long names and testing.

Development

Running Tests

Install bats-core and run the test suite:

brew install bats-core  # macOS
# or
apt-get install bats    # Debian/Ubuntu

# Unit tests (no cluster required)
make test

# Integration tests (requires deployed test pods)
make test-integration

# All tests
make test-all

License

Copyright 2026 Dairon Medina Caro me@dairon.org

Licensed under the Apache License, Version 2.0. See LICENSE file for details.