README.md
March 22, 2026 · View on GitHub
kubectl.nvim
Processes kubectl outputs to enable vim-like navigation in a buffer for your cluster.
✨ Features
Navigate your cluster in a buffer, using hierarchy where possible (backspace for up, enter for down) e.g. root -> deployment -> pod -> container
Colored output and smart highlighting
Floating windows for contextual stuff such as logs, description, containers..
Completion
Commands: :Kubectl, :Kubens, :Kubectx
Run kubectl commands directly or open interactive views. All commands support tab completion.
:Kubectl get endpoints -- Run kubectl and show output in split :Kubectl view [resource] -- Open interactive view for any resource :Kubectl top -- Open top dashboard :Kubectl diff [path] -- Diff resources :Kubens [namespace] -- Switch or select namespace :Kubectx [context] -- Switch or select context
Change context using cmd :Kubectx context-name or the context view
Exec into containers
In the pod view, select a pod by pressing<cr> and then again <cr> on the container you want to exec into
Sort by headers
By moving the cursor to anywhere in a column and pressinggs
Tail logs
Diff view: :Kubectl diff (path)
Port forward
Aliases (fallback view)
A fallback view that directs custom resources and has basic functionality such desc, edit, delOverview
Picker for recent items
⚡️ Required Dependencies
- neovim >= 0.10
⚡️ Optional Dependencies
📦 Installation
Install the plugin with your preferred package manager:
lazy.nvim
return {
{
"ramilito/kubectl.nvim",
-- use a release tag to download pre-built binaries
version = "2.*",
-- OR build from source, requires nightly: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust
-- build = 'make build',
-- OR if you use nix, build from source with:
-- build = 'nix run .#build-plugin',
dependencies = "saghen/blink.download",
config = function()
require("kubectl").setup()
end,
},
}
⌨️ Keymaps
We expose open, close and toggle to bind against:
Toggle
vim.keymap.set(
"n",
"<leader>k",
'<cmd>lua require("kubectl").toggle({ tab: boolean })<cr>',
{ noremap = true, silent = true }
)
Override existing
local group = vim.api.nvim_create_augroup("kubectl_mappings", { clear = true })
vim.api.nvim_create_autocmd("FileType", {
group = group,
pattern = "k8s_*",
callback = function(ev)
local k = vim.keymap
local opts = { buffer = ev.buf }
k.set("n", "<C-e>", "<Plug>(kubectl.picker_view)", opts)
end,
})
Delete existing
local group = vim.api.nvim_create_augroup("kubectl_mappings", { clear = true })
vim.api.nvim_create_autocmd("FileType", {
group = group,
pattern = "k8s_*",
callback = function(ev)
local k = vim.keymap
local opts = { buffer = ev.buf }
pcall(k.del, "n", 1, opts)
pcall(k.del, "n", 2, opts)
pcall(k.del, "n", 3, opts)
pcall(k.del, "n", 5, opts)
pcall(k.del, "n", 6, opts)
end,
})
Default Mappings
You can override the plugin's keymaps using the <Plug> mappings:
Default Mappings
-- default mappings
local group = vim.api.nvim_create_augroup("kubectl_mappings", { clear = true })
vim.api.nvim_create_autocmd("FileType", {
group = group,
pattern = "k8s_*",
callback = function(ev)
local k = vim.keymap.set
local opts = { buffer = ev.buf }
-- Global
k("n", "g?", "<Plug>(kubectl.help)", opts) -- Help float
k("n", "gr", "<Plug>(kubectl.refresh)", opts) -- Refresh view
k("n", "gs", "<Plug>(kubectl.sort)", opts) -- Sort by column
k("n", "gD", "<Plug>(kubectl.delete)", opts) -- Delete resource
k("n", "gd", "<Plug>(kubectl.describe)", opts) -- Describe resource
k("n", "gy", "<Plug>(kubectl.yaml)", opts) -- View yaml
k("n", "ge", "<Plug>(kubectl.edit)", opts) -- Edit resource
k("n", "<C-l>", "<Plug>(kubectl.filter_label)", opts) -- Filter labels
k("n", "<BS>", "<Plug>(kubectl.go_up)", opts) -- Go back to previous view
k("v", "<C-f>", "<Plug>(kubectl.filter_term)", opts) -- Filter selected text
k("n", "<CR>", "<Plug>(kubectl.select)", opts) -- Resource select action (different on each view)
k("n", "<Tab>", "<Plug>(kubectl.tab)", opts) -- Select resource
k("n", "<S-Tab>", "<Plug>(kubectl.clear_selection)", opts) -- Clear selection
k("n", "", "<Plug>(kubectl.quit)", opts) -- Close view (when applicable)
k("n", "gk", "<Plug>(kubectl.kill)", opts) -- Pod/portforward kill
k("n", "<M-h>", "<Plug>(kubectl.toggle_headers)", opts) -- Toggle headers
k("n", "<f4>", "<Plug>(kubectl.toggle_fullscreen)", opts) -- Toggle fullscreen
-- Views
k("n", "<C-p>", "<Plug>(kubectl.picker_view)", opts) -- Picker view
k("n", "<C-a>", "<Plug>(kubectl.alias_view)", opts) -- Aliases view
k("n", "<C-x>", "<Plug>(kubectl.contexts_view)", opts) -- Contexts view
k("n", "<C-f>", "<Plug>(kubectl.filter_view)", opts) -- Filter view
k("n", "<C-n>", "<Plug>(kubectl.namespace_view)", opts) -- Namespaces view
k("n", "gP", "<Plug>(kubectl.portforwards_view)", opts) -- Portforwards view
-- views
k("n", "1", "<Plug>(kubectl.view_deployments)", opts) -- Deployments view
k("n", "2", "<Plug>(kubectl.view_pods)", opts) -- Pods view
k("n", "3", "<Plug>(kubectl.view_configmaps)", opts) -- ConfigMaps view
k("n", "4", "<Plug>(kubectl.view_secrets)", opts) -- Secrets view
k("n", "5", "<Plug>(kubectl.view_services)", opts) -- Services view
k("n", "6", "<Plug>(kubectl.view_ingresses)", opts) -- Ingresses view
k("n", "", "<Plug>(kubectl.view_api_resources)", opts) -- API-Resources view
k("n", "", "<Plug>(kubectl.view_clusterrolebinding)", opts) -- ClusterRoleBindings view
k("n", "", "<Plug>(kubectl.view_crds)", opts) -- CRDs view
k("n", "", "<Plug>(kubectl.view_cronjobs)", opts) -- CronJobs view
k("n", "", "<Plug>(kubectl.view_daemonsets)", opts) -- DaemonSets view
k("n", "", "<Plug>(kubectl.view_events)", opts) -- Events view
k("n", "", "<Plug>(kubectl.view_helm)", opts) -- Helm view
k("n", "", "<Plug>(kubectl.view_horizontalpodautoscalers)", opts) -- HorizontalPodAutoscalers view
k("n", "", "<Plug>(kubectl.view_jobs)", opts) -- Jobs view
k("n", "", "<Plug>(kubectl.view_nodes)", opts) -- Nodes view
k("n", "", "<Plug>(kubectl.view_overview)", opts) -- Overview view
k("n", "", "<Plug>(kubectl.view_persistentvolumes)", opts) -- PersistentVolumes view
k("n", "", "<Plug>(kubectl.view_persistentvolumeclaims)", opts) -- PersistentVolumeClaims view
k("n", "", "<Plug>(kubectl.view_replicasets)", opts) -- ReplicaSets view,
k("n", "", "<Plug>(kubectl.view_serviceaccounts)", opts) -- ServiceAccounts view
k("n", "", "<Plug>(kubectl.view_statefulsets)", opts) -- StatefulSets view
k("n", "", "<Plug>(kubectl.view_storageclasses)", opts) -- StorageClasses view
k("n", "", "<Plug>(kubectl.view_top_nodes)", opts) -- Top view for nodes
k("n", "", "<Plug>(kubectl.view_top_pods)", opts) -- Top view for pods
-- Deployment/DaemonSet actions
k("n", "grr", "<Plug>(kubectl.rollout_restart)", opts) -- Rollout restart
k("n", "gss", "<Plug>(kubectl.scale)", opts) -- Scale workload
k("n", "gi", "<Plug>(kubectl.set_image)", opts) -- Set image (only if 1 container)
-- Pod/Container logs
k("n", "gl", "<Plug>(kubectl.logs)", opts) -- Logs view
k("n", "gh", "<Plug>(kubectl.history)", opts) -- Change logs --since= flag
k("n", "f", "<Plug>(kubectl.follow)", opts) -- Follow logs
k("n", "gw", "<Plug>(kubectl.wrap)", opts) -- Toggle wrap log lines
k("n", "gp", "<Plug>(kubectl.prefix)", opts) -- Toggle container name prefix
k("n", "gt", "<Plug>(kubectl.timestamps)", opts) -- Toggle timestamps prefix
k("n", "gpp", "<Plug>(kubectl.previous_logs)", opts) -- Toggle show previous logs
-- Node actions
k("n", "gO", "<Plug>(kubectl.cordon)", opts) -- Cordon node
k("n", "gU", "<Plug>(kubectl.uncordon)", opts) -- Uncordon node
k("n", "gS", "<Plug>(kubectl.shell)", opts) -- Shell pod
k("n", "gR", "<Plug>(kubectl.drain)", opts) -- Drain node
-- Top actions
k("n", "gn", "<Plug>(kubectl.top_nodes)", opts) -- Top nodes
k("n", "gp", "<Plug>(kubectl.top_pods)", opts) -- Top pods
-- CronJob actions
k("n", "gss", "<Plug>(kubectl.suspend_cronjob)", opts) -- Suspend CronJob
k("n", "gc", "<Plug>(kubectl.create_job)", opts) -- Create Job from CronJob
k("n", "gp", "<Plug>(kubectl.portforward)", opts) -- Pods/Services portforward
k("n", "gx", "<Plug>(kubectl.browse)", opts) -- Ingress view
k("n", "gy", "<Plug>(kubectl.yaml)", opts) -- Helm view
end,
})
Lazy Setup
For overriding the default mappings when using lazy.nvim check out our wiki page.
⚙️ Configuration
Setup
{
log_level = vim.log.levels.INFO,
auto_refresh = {
enabled = true,
interval = 300, -- milliseconds
},
diff = {
bin = "kubediff" -- or any other binary
},
kubectl_cmd = { cmd = "kubectl", env = {}, args = {} },
terminal_cmd = nil, -- Exec will launch in a terminal if set, i.e. "ghostty -e"
namespace = "All",
namespace_fallback = {}, -- If you have limited access you can list all the namespaces here
headers = {
enabled = true,
hints = true,
context = true,
heartbeat = true,
blend = 20,
skew = {
enabled = true,
log_level = vim.log.levels.OFF,
},
},
lineage = {
enabled = true, -- This feature is in beta at the moment
},
logs = {
prefix = true,
timestamps = true,
since = "5m"
},
alias = {
apply_on_select_from_history = true,
max_history = 5,
},
filter = {
apply_on_select_from_history = true,
max_history = 10,
},
filter_label = {
max_history = 20,
},
float_size = {
-- Almost fullscreen:
-- width = 1.0,
-- height = 0.95, -- Setting it to 1 will cause bottom to be cutoff by statuscolumn
-- For more context aware size:
width = 0.9,
height = 0.8,
-- Might need to tweak these to get it centered when float is smaller
col = 10,
row = 5,
},
statusline = {
enabled = true
},
obj_fresh = 5, -- highlight if creation newer than number (in minutes)
api_resources_cache_ttl = 60 * 60 * 3, -- 3 hours in seconds
}
🎨 Colors
The plugin uses the following highlight groups:
Highlight Groups
| Name | Default | Color |
|---|---|---|
| KubectlHeader | { fg = "#569CD6" } | |
| KubectlWarning | { fg = "#D19A66" } | |
| KubectlError | { fg = "#D16969" } | |
| KubectlInfo | { fg = "#608B4E" } | |
| KubectlDebug | { fg = "#DCDCAA" } | |
| KubectlSuccess | { fg = "#4EC9B0" } | |
| KubectlPending | { fg = "#C586C0" } | |
| KubectlDeprecated | { fg = "#D4A5A5" } | |
| KubectlExperimental | { fg = "#CE9178" } | |
| KubectlNote | { fg = "#9CDCFE" } | |
| KubectlGray | { fg = "#666666" } | |
| KubectlPselect | { bg = "#3e4451" } | |
| KubectlPmatch | { link = "KubectlWarning" } | |
| KubectlUnderline | { underline = true } | - |
Events
We trigger events that you can use to run custom logic:
events
| Name | When | Data |
|---|---|---|
| K8sResourceSelected | On main views, when selecting a resource unless overridden (like pod view) | kind, name, ns |
| K8sContextChanged | After context change | context |
| K8sCacheLoaded | After api-resources cache is loaded | - |
Example: saving session on context change
vim.api.nvim_create_autocmd("User", {
group = group,
pattern = "K8sContextChanged",
callback = function(ctx)
local results =
require("kubectl.actions.commands").shell_command("kubectl", { "config", "use-context", ctx.data.context })
if not results then
vim.notify(results, vim.log.levels.INFO)
end
end,
})
🚀 Performance
Startup
The setup function only adds ~1ms to startup. We use kubectl proxy and curl to reduce latency.
Efficient resource monitoring
We leverage the kubernetes informer to efficiently monitor resource updates.
By using the resourceVersion, we avoid fetching all resources in each loop.
Instead, the Informer provides only the changes, significantly reducing overhead and improving performance.
⚠️ Versioning
As of v2, the plugin is in a stable state. No breaking changes are scheduled at this time, and we remain committed to delivering a reliable, consistent user experience.
Troubleshooting
Winbar
If you have a Winbar plugin, such as lualine there will be conflicts with the winbar in this plugin. To solve this, you should add our filetypes to the exclude files table.
🔥 Developers
Instructions from here: repro.lua You can find one prepared here: ./repro.lua
💪🏼 Motivation
This plugins main purpose is to browse the kubernetes state using vim like navigation and keys, similar to oil.nvim for file browsing.