kubectl-fzf

kubectl-fzf provides a fast and powerful fzf autocompletion for kubectl.

Core differences from https://github.com/bonnefoa/kubectl-fzf:

• Reduced dependencies.
• Focus on local development use case.

Table of Contents

• Kubectl-fzf
• Table of Contents
• Features
• Requirements
• Installation
  • kubectl-fzf binaries
  • Shell autocompletion
• Usage
  • Completion
    • Configuration
• Troubleshooting
  • Debug kubectl-fzf-completion
  • Debug Tab Completion
  • Debug kubectl-fzf-server

Features

• Seamless integration with kubectl autocompletion
• Fast completion
• Label autocompletion
• Automatic namespace switch

Requirements

• go (minimum version 1.25)
• awk
• fzf

Installation

kubectl-fzf binaries

# Completion binary called during autocompletion.
go install github.com/codeactual/kubectl-fzf/v4/cmd/kubectl-fzf-completion@main
kubectl-fzf-completion -h

# Server which updates the cache files consumed by kubectl-fzf-completion to provide search results.
go install github.com/codeactual/kubectl-fzf/v4/cmd/kubectl-fzf-server@main
kubectl-fzf-server -h

kubectl-fzf-completion needs to be in you $PATH so make sure that your $GOPATH bin is included:

PATH=$PATH:$GOPATH/bin

Shell autocompletion

Source the autocompletion functions from the checked-out repository (or unpacked release archive)/

Note

Sourcing the native kubectl completion scripts are optional in order to provide fallback results.

mkdir -p ~/.config/kubectl-fzf

# bash version
install -m0644 shell/kubectl_fzf.bash ~/.config/kubectl-fzf/kubectl_fzf.bash
echo "source <(kubectl completion bash)" >> ~/.bashrc
echo "source ~/.config/kubectl-fzf/kubectl_fzf.bash" >> ~/.bashrc

# zsh version
install -m0644 shell/kubectl_fzf.plugin.zsh ~/.config/kubectl-fzf/kubectl_fzf.plugin.zsh
echo "source <(kubectl completion zsh)" >> ~/.zshrc
echo "source ~/.config/kubectl-fzf/kubectl_fzf.plugin.zsh" >> ~/.zshrc

The server only stores Secret metadata (namespace, name, type, and key counts), never the values themselves.

Usage

flowchart TB
    subgraph TargetCluster
        k8s[api-server]
    end

    subgraph Laptop
        shell[Shell]
        fileNode([$XDG_CACHE_HOME/kubectl-fzf/TargetCluster/pods])
        comp[kubectl-fzf-completion]
        server[kubectl-fzf-server]
    end
    shell -- kubectl get pods TAB --> comp -- Read content and feed it to fzf --> fileNode
    server -- Write autocompletion informations --> fileNode

    k8s <-- Watch --> server

Loading

kubectl-fzf-server will watch cluster resources and keep the current state of the cluster in local files. By default, files are written in $XDG_CACHE_HOME/kubectl-fzf (or $HOME/.cache/kubectl-fzf when XDG_CACHE_HOME is unset). Set KUBECTL_FZF_CACHE_DIR to override the cache root.

Advantages:

• Minimal setup needed.
• Local cache is maintained up to date.

Drawbacks:

• It can be CPU and memory intensive on big clusters.
• It also can be bandwidth intensive. The most expensive is the initial listing at startup and on error/disconnection. Big namespace can increase the probability of errors during initial listing.
• It can generate load on the kube-api servers if multiple user are running it.

To create cache files necessary for kubectl_fzf, just run in a tmux or a screen

kubectl-fzf-server

It will watch the cluster in the current context. If you switch context, kubectl-fzf-server will detect and start watching the new cluster. The initial resource listing can be long on big clusters and autocompletion might need 30s+.

connect: connection refused or similar messages are expected if there's network issues/interruptions and kubectl-fzf-server will automatically reconnect.

Completion

Once kubectl-fzf-server is running, you will be able to use use fzf-powered completion when using kubectl normally.

# Get fzf completion on pods on all namespaces
kubectl get pod <TAB>

# Open fzf autocompletion on all available label
kubectl get pod -l <TAB>

# Open fzf autocompletion on all available field-selector. Usually much faster to list all pods running on an host compared to kubectl describe node.
kubectl get pod --field-selector <TAB>

# This will fallback to the normal kubectl completion (if sourced) 
kubectl <TAB>

Configuration

When using a remote HTTP endpoint, set --http-endpoint (or KUBECTL_FZF_HTTP_ENDPOINT) on kubectl-fzf-completion to point to the server's address.

Troubleshooting

Debug kubectl-fzf-completion

Build and test a completion with debug logs:

go build ./cmd/kubectl-fzf-completion && KUBECTL_FZF_LOG_LEVEL=debug ./kubectl-fzf-completion k8s_completion 'get pods '  

Force Tab completion to use the completion binary in the current directory:

export KUBECTL_FZF_COMPLETION_BIN=./kubectl-fzf-completion

Debug Tab Completion

To debug Tab completion, you can activate the shell debug logs:

export KUBECTL_FZF_COMP_DEBUG_FILE=/tmp/debug

Check that the completion function is correctly sourced:

type kubectl_fzf_completion
kubectl_fzf_completion is a shell function from /home/codeactual/.antigen/bundles/kubectl-fzf-main/shell/kubectl_fzf.plugin.zsh

Use zsh completion debug:

kubectl get pods <C-X>?
Trace output left in /tmp/zsh497886kubectl1 (up-history to view)

Debug kubectl-fzf-server

To launch kubectl-fzf-server with debug logs

kubectl-fzf-server --log-level debug