kubectl-pvc

A kubectl plugin for browsing and managing PVC contents via the PVC Explorer operator.

Uses your kubeconfig for authentication — no extra login required.

Prerequisites

• Go 1.26+
• kubectl with a valid kubeconfig pointing to a cluster with PVC Explorer installed
• On macOS: macFUSE (only for mount)

Installation

Manual (only option — no releases yet)

make install

Verify:

kubectl plugin list
kubectl pvc --version

Local Development

The project includes a Kind-based local environment in the pvc-explorer repo.

# Clone both repos side by side
git clone https://github.com/pvc-explorer-operator/pvc-explorer.git
git clone https://github.com/pvc-explorer-operator/kubectl-pvc-explorer.git

# Spin up the full dev environment (Kind cluster + PVC Explorer controller + demo PVCs)
cd pvc-explorer
./kind/setup.sh

# Build and test the plugin
cd ../kubectl-pvc-explorer
make install
kubectl pvc list

The setup script creates a Kind cluster, builds the controller, installs CRDs, and provisions demo PVCs across demo and demo-staging namespaces.

Quick Start

Wake an explorer, browse files, upload, mount, then clean up:

# Wake the agent (scale from 0 to 1)
kubectl pvc wake staging-uploads -n demo-staging

# List files at the root (expected: empty — fresh PVC)
kubectl pvc ls staging-uploads -n demo-staging /

# Create some local test files
echo "hello world" > /tmp/files/test.md
echo "# readme" > /tmp/files/README.md

# Upload local files to the PVC
kubectl pvc cp /tmp/files/*.md staging-uploads -n demo-staging

# Mount via FUSE and browse (macFUSE only, experimental)
kubectl pvc mount staging-uploads /tmp/mount-pvc -n demo-staging
# In another terminal:
ls /tmp/mount-pvc
cat /tmp/mount-pvc/test.md
cat /tmp/mount-pvc/README.md

# Sleep the agent (scale back to 0)
kubectl pvc sleep staging-uploads -n demo-staging

Usage

List all PVCExplorers

kubectl pvc list
kubectl pvc list -n my-namespace

Wake / Sleep agents

# Scale from 0 to 1 (create the agent pod)
kubectl pvc wake my-pvc -n my-namespace

# Wait up to 2 minutes for readiness
kubectl pvc wake my-pvc -n my-namespace --wait 2m

# Scale back to 0
kubectl pvc sleep my-pvc -n my-namespace

Browse files

# List root directory
kubectl pvc ls my-pvc -n my-namespace

# List specific path
kubectl pvc ls my-pvc -n my-namespace /data/logs

# Display file contents
kubectl pvc cat my-pvc -n my-namespace /data/config.yaml

Copy files

Download from PVC:

kubectl pvc cp my-pvc:/remote/path/file.txt ./local-file.txt

Upload to PVC:

kubectl pvc cp ./local-file.txt my-pvc:/remote/dir/

# Upload multiple files, bare name = root
kubectl pvc cp config/samples/* my-pvc -n demo

Execute commands in the agent pod

kubectl pvc exec my-pvc -n my-namespace -- bash
kubectl pvc exec my-pvc -n my-namespace -- ls -la /data

Mount via FUSE (experimental)

# Requires macFUSE (macOS) or libfuse (Linux)
kubectl pvc mount my-pvc /mnt/pvc -n my-namespace
ls /mnt/pvc
cat /mnt/pvc/file.txt
# Press Ctrl+C to unmount

Experimental: the mount command may change in future releases.

How Auth Works

The plugin authenticates via your existing kubeconfig — no separate login needed. When accessing an agent pod, it reads the bearer token from the *-agent-token Secret automatically.

Environment Variables

Variable	Description
$PVC_EXPLORER_NAMESPACE	Default namespace (falls back to default)
$KUBECONFIG	Path to kubeconfig (uses default if unset)

Release Process

Coming soon. Releases will be published via GitHub Actions with goreleaser when tagged.