kubectl-peek: understand Kubernetes Secret relationships from your terminal

Working with Kubernetes Secrets is easy until you need to answer questions such as:

• What does this Secret contain?
• Which workloads use it?
• Was it generated by an operator?
• Is it safe to delete?

Answering those questions usually means switching between several kubectl commands, decoding Base64 values manually, grepping manifests, and inspecting custom resources one by one.

I wanted something much simpler.

That is why I built kubectl-peek.

kubectl-peek is a lightweight interactive CLI and native kubectl plugin focused on inspecting Kubernetes Secrets and understanding their relationships from the terminal.

No controllers.

No CRDs installed by the tool.

No web UI.

No cluster-side components.

Everything runs client-side using the kubeconfig and RBAC permissions you already have.

Why I built it

My goal was to create something intentionally small but genuinely useful during day-to-day platform engineering work.

I wanted a tool that:

• works with any Kubernetes cluster
• requires no cluster-side installation
• respects the existing kubeconfig and RBAC model
• keeps Secret inspection fast and interactive
• avoids unnecessary API calls unless relationship discovery is requested

Instead of copying Secret names between commands, decoding values manually, opening workload manifests, and hunting through operators or CRDs, I wanted one focused workflow.

What kubectl-peek does

The tool provides an interactive Secret browser directly in your terminal.

You can:

• browse Secrets in a namespace
• filter the list interactively
• inspect decoded Secret values
• redact values when they should not be displayed
• discover resources that use a Secret
• detect resources that produce or reference a Secret
• extend relationship discovery to custom resources through YAML rules
• use it as either kubectl-peek or kubectl peek

By default, Secret values are displayed and relationship discovery is disabled.

This keeps normal inspection fast and avoids extra API requests or permission warnings when you only need to inspect a Secret.

Demo

The basic workflow stays intentionally simple:

1. Run kubectl-peek secret
2. Filter the Secret list
3. Select a Secret
4. Inspect its metadata
5. Review decoded or redacted values
6. Enable relationship discovery only when needed

Inspect Secret values

Start the interactive browser with:

kubectl-peek secret

or through the native plugin form:

kubectl peek secret

Filter by name:

kubectl-peek secret database

Use another namespace:

kubectl-peek secret database -n staging

By default, decoded values are displayed directly in the terminal.

Example:

Secret: database-credentials
Namespace: staging
Type: Opaque

password:
────────────────────────────────────────────────────────────
example-password

Hide Secret values

Sometimes you need the metadata and relationships but should not expose the actual values.

Use:

kubectl-peek secret --show-values=false

The key remains visible while the value is replaced with its byte length:

password:
────────────────────────────────────────────────────────────
<redacted: 24 bytes>

This is useful during:

• screen sharing
• terminal recordings
• screenshots
• demos
• collaborative troubleshooting
• environments where Secret contents should stay hidden

Relationship discovery is opt-in

Relationship discovery is disabled by default.

Enable it explicitly with:

kubectl-peek secret --show-usage

When enabled, kubectl-peek searches supported Kubernetes resources and configured custom-resource rules for relationships such as:

• uses
• produces
• references

Example:

Secret: database-credentials
Namespace: staging
Type: Opaque
Used by:
  Deployment/backend
    uses: container environment (container/backend envFrom)
  CronJob/backup
    uses: environment variable (container/backup env/BACKUP_PASSWORD -> password)

You can combine discovery with value redaction:

kubectl-peek secret \
  --show-usage \
  --show-values=false

That gives you the dependency information without printing sensitive values.

Built-in Secret discovery

With --show-usage, kubectl-peek can discover references from common Kubernetes resources.

Currently supported resources include:

• Pods
• Deployments
• StatefulSets
• DaemonSets
• Jobs
• CronJobs
• ServiceAccounts
• Ingresses
• Gateway API Gateways

It detects references through fields such as:

• Secret volumes
• projected Secret volumes
• imagePullSecrets
• environment variables
• envFrom
• init containers
• ephemeral containers
• Gateway listener certificates
• Ingress TLS configuration

This makes it much easier to understand whether a Secret is still referenced before rotating or deleting it.

A safer message when nothing is found

A missing relationship must not be interpreted as proof that a Secret is unused.

When --show-usage is enabled but no supported reference is found, kubectl-peek displays:

Used by:
  No references were found among the supported built-in resources and configured usage rules.
  This does not guarantee that the Secret is unused; unsupported resources, external systems, or unconfigured custom resources may still reference it.

This distinction matters because a Secret may still be used by:

• an unsupported Kubernetes resource
• a custom resource without a configured rule
• an external system
• an application that retrieves the Secret dynamically
• a resource in another namespace

The output is dependency information, not a deletion guarantee.

Discover relationships in custom resources

Instead of hardcoding every Kubernetes operator, kubectl-peek can load relationship rules from a YAML file.

That makes it possible to support resources such as:

• External Secrets Operator
• cert-manager
• Crossplane
• Vault operators
• internal platform APIs
• private CRDs

without modifying the application itself.

Example:

rules:
  - apiVersions:
      - external-secrets.io/v1
      - external-secrets.io/v1beta1
    kind: ExternalSecret
    resource: externalsecrets
    references:
      - path: spec.target.name
        relation: produces
        description: generated Secret

Load the rule file explicitly:

kubectl-peek secret \
  --show-usage \
  --rules rules.yaml

Or configure a persistent default:

export KUBECTL_PEEK_RULE_FILE="$HOME/.config/kubectl-peek/rules.yaml"

Then run:

kubectl-peek secret --show-usage

Built-in and rule-based relationships are combined in the same Used by section.

Installation

Homebrew

brew tap pierinho13/tools
brew install --cask kubectl-peek

GitHub Releases

Download the archive for your operating system and architecture, extract it, and place the binary in a directory included in your PATH.

Build from source

git clone https://github.com/pierinho13/kubectl-peek.git
cd kubectl-peek
go build -o kubectl-peek .

Basic usage

Browse Secrets:

kubectl-peek secret

Filter by name:

kubectl-peek secret database

Use another namespace:

kubectl-peek secret -n staging

Use another context:

kubectl-peek secret --context production

Specify a kubeconfig:

kubectl-peek secret --kubeconfig ~/.kube/config

Discover relationships:

kubectl-peek secret --show-usage

Hide values:

kubectl-peek secret --show-values=false

Load custom discovery rules:

kubectl-peek secret \
  --show-usage \
  --rules rules.yaml

Permissions

Basic Secret inspection requires permission to read Secrets in the selected namespace.

Relationship discovery requires additional list permissions for the supported or configured resources being inspected.

This means:

kubectl-peek secret

can remain useful with a smaller permission set, while:

kubectl-peek secret --show-usage

performs the broader dependency search only when requested.

Security

Decoded Secret values are displayed by default.

Those values may remain visible in:

• terminal scrollback
• screen recordings
• screenshots
• shared sessions
• captured command output

Use:

kubectl-peek secret --show-values=false

when values should remain hidden.

The tool should still be used only in trusted environments and with the minimum RBAC permissions required for the task.

Final thoughts

kubectl-peek started as a small utility for inspecting Kubernetes Secrets more comfortably.

Its purpose is to make two related workflows easier:

Inspect what a Secret contains.

and:

Understand which supported resources use, produce, or reference it.

The relationship model is intentionally transparent. Built-in finders cover common Kubernetes resources, YAML rules extend the same mechanism to custom resources, and an empty result is clearly presented as incomplete evidence rather than proof that a Secret is safe to delete.

The project is open source:

https://github.com/pierinho13/kubectl-peek

Contributions, ideas, and new rule examples are welcome.

If you’re interested in this kind of platform engineering work, you can learn more about my experience or get in touch.