borescope: a natural shell for Juju Kubernetes workload containers

borescope is an open-source command-line tool that provides a shell-like prompt for debugging Juju Kubernetes workload containers. It works with charm workloads running minimal rock container images without an included shell, allowing operators to interact with the container's Pebble service manager through existing Juju authority.

The tool is designed for operators who need to debug Juju Kubernetes workload containers where the workload rock has no bash or coreutils. It exposes Pebble commands such as services, logs, plan, checks, changes, and notices to help manage these environments effectively.

Users can get started by viewing the project on GitHub, where the code is distributed under an Apache 2.0 license. The tool is free and open source, making it accessible for immediate use without any cost or complex setup procedures.

borescope drives the workload's Pebble through the charm container, which always has a shell, so familiar file commands work even when the image is empty. This approach allows users to execute commands like ls and grep directly within the container environment.

The tool communicates with containers using the same mechanism as juju ssh, so it does not require kubectl or cluster-admin access. This means users only need the ability to juju ssh to the unit for borescope to function properly.

borescope ships a deliberately small command set that includes path-aware tab-completion, per-unit history, and single pipes. Users can also use the exec escape hatch to run any tool directly in the container with their current working directory.

The tool supports one-shot and snapshot modes, allowing users to script actions with --command or file a bug with --snapshot. The snapshot mode captures services, plan, checks, notices, and recent logs as a single stable JSON document.

borescope turns the target unit into a Pebble discovery step by confirming the unit, reading the charm's metadata.yaml for workload container names, and checking the container is alive. This process relies entirely on your Juju model access.

The default backend reaches the workload's Pebble socket through the charm container via juju ssh. When the socket is directly reachable, inside a charm or a local Pebble, it uses the real ops.pebble.Client HTTP API instead.

Some reviewers say the tool feels like bash with muscle memory mostly just working, providing a real REPL with cd and pwd. Users appreciate the familiar file commands and the way Pebble's own vocabulary is first-class.

The tool provides a prompt that feels like bash, talking to the container's Pebble through the Juju authority you already have. This design ensures that operators can interact with the container without needing additional permissions or tools.

borescope is under active development as of the latest update, with version 1 currently available. The project is hosted on GitHub and follows an Apache 2.0 license for its distribution.

The tool exposes Pebble commands such as services, logs, plan, checks, changes, and notices, offering features like path-aware tab-completion and per-unit history. These capabilities are built into the core functionality of the shell.

borescope works on rocks with no shell at all, making it suitable for environments where the workload rock lacks bash or coreutils. The charm container always has a shell, which borescope leverages to drive the workload's Pebble.

The official website of borescope: a natural shell for Juju Kubernetes workload containers is borescope.dev.