{"id":13575622,"url":"https://github.com/bonnefoa/kubectl-fzf","last_synced_at":"2025-12-29T23:41:04.557Z","repository":{"id":40625747,"uuid":"155163258","full_name":"bonnefoa/kubectl-fzf","owner":"bonnefoa","description":"A fast kubectl autocompletion with fzf","archived":false,"fork":false,"pushed_at":"2024-04-23T17:36:21.000Z","size":740,"stargazers_count":447,"open_issues_count":8,"forks_count":33,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-05T11:43:22.175Z","etag":null,"topics":["autocompletion","bash","completion","fuzzy-search","fzf","kubectl","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bonnefoa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-29T06:35:15.000Z","updated_at":"2024-10-30T15:46:28.000Z","dependencies_parsed_at":"2024-06-20T05:44:16.317Z","dependency_job_id":"661955d5-3fb4-4180-8988-829428818645","html_url":"https://github.com/bonnefoa/kubectl-fzf","commit_stats":{"total_commits":484,"total_committers":11,"mean_commits":44.0,"dds":0.3326446280991735,"last_synced_commit":"68bf6b00ff05376fb34ba76cf12ed9939200ca55"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnefoa%2Fkubectl-fzf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnefoa%2Fkubectl-fzf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnefoa%2Fkubectl-fzf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnefoa%2Fkubectl-fzf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bonnefoa","download_url":"https://codeload.github.com/bonnefoa/kubectl-fzf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247260741,"owners_count":20910069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocompletion","bash","completion","fuzzy-search","fzf","kubectl","kubernetes"],"created_at":"2024-08-01T15:01:02.669Z","updated_at":"2025-12-29T23:41:04.517Z","avatar_url":"https://github.com/bonnefoa.png","language":"Go","funding_links":[],"categories":["Completions","Go"],"sub_categories":["ZSH on Windows"],"readme":"# Kubectl-fzf\n\nkubectl-fzf provides a fast and powerful fzf autocompletion for kubectl.\n\n[![asciicast](https://asciinema.org/a/yHKY5vQ40ZaOwMQnhLfYJ5Pja.png)](https://asciinema.org/a/yHKY5vQ40ZaOwMQnhLfYJ5Pja?t=01)\n\nTable of Contents\n=================\n\n* [Kubectl-fzf](#kubectl-fzf)\n* [Table of Contents](#table-of-contents)\n* [Features](#features)\n* [Requirements](#requirements)\n* [Installation](#installation)\n   * [kubectl-fzf binaries](#kubectl-fzf-binaries)\n   * [Shell autocompletion](#shell-autocompletion)\n      * [Zsh plugins: Antigen](#zsh-plugins-antigen)\n   * [kubectl-fzf-server](#kubectl-fzf-server)\n      * [Install kubectl-fzf-server as a pod](#install-kubectl-fzf-server-as-a-pod)\n      * [Install kubectl-fzf-server as a systemd service](#install-kubectl-fzf-server-as-a-systemd-service)\n* [Usage](#usage)\n   * [kubectl-fzf-server: local version](#kubectl-fzf-server-local-version)\n   * [kubectl-fzf-server: pod version](#kubectl-fzf-server-pod-version)\n   * [Completion](#completion)\n      * [Configuration](#configuration)\n* [Troubleshooting](#troubleshooting)\n   * [Debug kubectl-fzf-completion](#debug-kubectl-fzf-completion)\n   * [Debug Tab Completion](#debug-tab-completion)\n   * [Debug kubectl-fzf-server](#debug-kubectl-fzf-server)\n\n# Features\n\n- Seamless integration with kubectl autocompletion\n- Fast completion\n- Label autocompletion\n- Automatic namespace switch\n\n# Requirements\n\n- go (minimum version 1.19)\n- awk\n- [fzf](https://github.com/junegunn/fzf)\n\n# Installation\n\n## kubectl-fzf binaries\n\n```shell\n# Completion binary called during autocompletion\ngo install github.com/bonnefoa/kubectl-fzf/v3/cmd/kubectl-fzf-completion@main\n# If you want to run the kubectl-fzf server locally\ngo install github.com/bonnefoa/kubectl-fzf/v3/cmd/kubectl-fzf-server@main\n```\n\n`kubectl-fzf-completion` needs to be in you $PATH so make sure that your $GOPATH bin is included:\n```\nPATH=$PATH:$GOPATH/bin\n```\n\n## Shell autocompletion\n\nSource the autocompletion functions:\n```\n# bash version\nwget https://raw.githubusercontent.com/bonnefoa/kubectl-fzf/main/shell/kubectl_fzf.bash -O ~/.kubectl_fzf.bash\necho \"source \u003c(kubectl completion bash)\" \u003e\u003e ~/.bashrc\necho \"source ~/.kubectl_fzf.bash\" \u003e\u003e ~/.bashrc\n\n# zsh version\nwget https://raw.githubusercontent.com/bonnefoa/kubectl-fzf/main/shell/kubectl_fzf.plugin.zsh -O ~/.kubectl_fzf.plugin.zsh\necho \"source \u003c(kubectl completion zsh)\" \u003e\u003e ~/.zshrc\necho \"source ~/.kubectl_fzf.plugin.zsh\" \u003e\u003e ~/.zshrc\n```\n\n### Zsh plugins: Antigen\n\nYou can use [antigen](https://github.com/zsh-users/antigen) to load it as a zsh plugin\n```shell\nantigen bundle robbyrussell/oh-my-zsh plugins/docker\nantigen bundle bonnefoa/kubectl-fzf@main shell/\n```\n\n## kubectl-fzf-server\n\n### Install kubectl-fzf-server as a pod\n\nYou can deploy `kubectl-fzf-server` as a pod in your cluster.\n\nFrom the [k8s directory](https://github.com/bonnefoa/kubectl-fzf/tree/main/k8s):\n```shell\nhelm template --namespace myns --set image.kubectl_fzf_server.tag=v3 --set toleration=aToleration . | kubectl apply -f -\n```\n\nYou can check the latest image version [here](https://cloud.docker.com/repository/docker/bonnefoa/kubectl-fzf/general).\n\n### Install kubectl-fzf-server as a systemd service\n\nYou can install `kubectl-fzf-server` as a systemd unit server.\n\n```\n# Create user systemd config\nmkdir -p ~/.config/systemd/user\nwget https://raw.githubusercontent.com/bonnefoa/kubectl-fzf/main/systemd/kubectl_fzf_server.service -O ~/.config/systemd/user/kubectl_fzf_server.service\n# Set fullpath of kubectl-fzf-server\nsed -i \"s#INSTALL_PATH#$GOPATH/bin#\" ~/.config/systemd/user/kubectl_fzf_server.service\n\n# Reload to pick up new service\nsystemctl --user daemon-reload\n\n# Start the server\nsystemctl --user start kubectl_fzf_server.service\n\n# Automatically enable it at startup\nsystemctl --user enable kubectl_fzf_server.service\n\n# Get log\njournalctl --user-unit=kubectl_fzf_server.service\n```\n\n# Usage\n\n## kubectl-fzf-server: local version\n\n``` mermaid\nflowchart TB\n    subgraph TargetCluster\n        k8s[api-server]\n    end\n\n    subgraph Laptop\n        shell[Shell]\n        fileNode([/tmp/kubectl_fzf_cache/TargetCluster/pods])\n        comp[kubectl-fzf-completion]\n        server[kubectl-fzf-server]\n    end\n    shell -- kubectl get pods TAB --\u003e comp -- Read content and feed it to fzf --\u003e fileNode\n    server -- Write autocompletion informations --\u003e fileNode\n\n    k8s \u003c-- Watch --o server\n```\n\n`kubectl-fzf-server` will watch cluster resources and keep the current state of the cluster in local files.\nBy default, files are written in `/tmp/kubectl_fzf_cache` (defined by `KUBECTL_FZF_CACHE`)\n\nAdvantages:\n- Minimal setup needed.\n- Local cache is maintained up to date.\n\nDrawbacks:\n- It can be CPU and memory intensive on big clusters.\n- 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.\n- It can generate load on the kube-api servers if multiple user are running it.\n\nTo create cache files necessary for `kubectl_fzf`, just run in a tmux or a screen\n\n```shell\nkubectl-fzf-server\n```\n\nIt will watch the cluster in the current context. If you switch context, `kubectl-fzf-server` will detect and start watching the new cluster.\nThe initial resource listing can be long on big clusters and autocompletion might need 30s+.\n\n`connect: connection refused` or similar messages are expected if there's network issues/interruptions and `kubectl-fzf-server` will automatically reconnect.\n\n## kubectl-fzf-server: pod version\n\n``` mermaid\nflowchart TB\n    subgraph TargetCluster\n        k8s[api-server]\n        server[kubectl-fzf-server]\n    end\n\n    subgraph Laptop\n        shell[Shell]\n        comp[kubectl-fzf-completion]\n    end\n\n\n    shell -- kubectl get pods TAB --\u003e comp \n    comp -- Through port forward\\nGET /k8s/resources/pods --\u003e server\n\n    k8s \u003c-- Watch --o server\n```\n\nIf the pod is deployed in your cluster, the autocompletion will be fetched automatically fetched using port forward.\n\nAdvantages:\n- No need to run a local `kubectl-fzf-server`\n- Only a single instance of `kubectl-fzf-server` per cluster is needed, lowering the load on the `kube-api` servers.\n\nDrawbacks:\n- Resources need to be fetched remotely, this can increased the completion time. A local cache is maintained to lower this.\n\n## Completion\n\nOnce `kubectl-fzf-server` is running, you will be able to use `kubectl_fzf` by calling the kubectl completion\n```shell\n# Get fzf completion on pods on all namespaces\nkubectl get pod \u003cTAB\u003e\n\n# Open fzf autocompletion on all available label\nkubectl get pod -l \u003cTAB\u003e\n\n# Open fzf autocompletion on all available field-selector. Usually much faster to list all pods running on an host compared to kubectl describe node.\nkubectl get pod --field-selector \u003cTAB\u003e\n\n# This will fallback to the normal kubectl completion (if sourced) \nkubectl \u003cTAB\u003e\n```\n\n### Configuration\n\nBy default, the local port used for the port-forward is 8080. You can override it through an environment variable:\n```\nKUBECTL_FZF_PORT_FORWARD_LOCAL_PORT=8081\n```\n\n# Troubleshooting\n\n## Debug kubectl-fzf-completion\n\nBuild and test a completion with debug logs:\n```\ngo build ./cmd/kubectl-fzf-completion \u0026\u0026 KUBECTL_FZF_LOG_LEVEL=debug ./kubectl-fzf-completion k8s_completion 'get pods '  \n```\n\nForce Tab completion to use the completion binary in the current directory:\n```\nexport KUBECTL_FZF_COMPLETION_BIN=./kubectl-fzf-completion\n```\n\n## Debug Tab Completion\n\nTo debug Tab completion, you can activate the shell debug logs:\n```\nexport KUBECTL_FZF_COMP_DEBUG_FILE=/tmp/debug\n```\n\nCheck that the completion function is correctly sourced:\n```\ntype kubectl_fzf_completion\nkubectl_fzf_completion is a shell function from /home/bonnefoa/.antigen/bundles/kubectl-fzf-main/shell/kubectl_fzf.plugin.zsh\n```\n\nUse zsh completion debug:\n```\nkubectl get pods \u003cC-X\u003e?\nTrace output left in /tmp/zsh497886kubectl1 (up-history to view)\n```\n\n## Debug kubectl-fzf-server\n\nTo launch kubectl-fzf-server with debug logs\n```shell\nkubectl-fzf-server --log-level debug\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnefoa%2Fkubectl-fzf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonnefoa%2Fkubectl-fzf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnefoa%2Fkubectl-fzf/lists"}