kubectl-fzf

Kubectl-fzf

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

Table of Contents

• Kubectl-fzf
• Table of Contents
• Features
• Requirements
• Installation
  • kubectl-fzf binaries
  • Shell autocompletion
    • Zsh plugins: Antigen
  • kubectl-fzf-server
    • Minimal RBAC
• Usage
  • kubectl-fzf-server: local version
  • 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.19)
• awk
• fzf

Installation

kubectl-fzf binaries

# Completion binary called during autocompletion
go install github.com/codeactual/kubectl-fzf/v4/cmd/kubectl-fzf-completion@main
# If you want to run the kubectl-fzf server locally
go install github.com/codeactual/kubectl-fzf/v4/cmd/kubectl-fzf-server@main

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):

# bash version
mkdir -p ~/.config/kubectl-fzf
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

Zsh plugins: Antigen

You can use antigen to load it as a zsh plugin

antigen bundle robbyrussell/oh-my-zsh plugins/docker
antigen bundle codeactual/kubectl-fzf@main shell/

kubectl-fzf-server

kubectl-fzf-server now targets standalone deployments only. Running it inside a Kubernetes pod is no longer supported.

Minimal RBAC

Apply the read-only RBAC manifest to grant kubectl-fzf the cluster permissions it needs without exposing Secret contents:

kubectl apply -f docs/rbac-readonly.yaml

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

Usage

kubectl-fzf-server: local version

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

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 kubectl_fzf by calling the kubectl completion

# 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