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 -> deplyoment -> pod -> container

Colored output and smart highlighting

Floating windows for contextual stuff such as logs, description, containers..

Completion

Run custom commands e.g :Kubectl get endpoints

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 pressing gs}

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, del}

Overview

Lineage

_{A plugin similar to kube-lineage ⚠️ This is a beta feature and not all bugs are sorted out}

⚡️ Required Dependencies

• kubectl
• curl
• neovim >= 0.10

⚡️ Optional Dependencies

• kubediff or DirDiff (If you want to use the diff feature)
• Helm (for helm view)

📦 Installation

Install the plugin with your preferred package manager:

lazy.nvim

return {
  {
    "ramilito/kubectl.nvim",
    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()<cr>', { noremap = true, silent = true })

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", "<Plug>(kubectl.help)", "g?", opts) -- Help float
    k("n", "<Plug>(kubectl.refresh)", "gr", opts) -- Refresh view
    k("n", "<Plug>(kubectl.sort)", "gs", opts) -- Sort by column
    k("n", "<Plug>(kubectl.delete)", "gD", opts) -- Delete resource
    k("n", "<Plug>(kubectl.describe)", "gd", opts) -- Describe resource
    k("n", "<Plug>(kubectl.yaml)", "gy", opts) -- View yaml
    k("n", "<Plug>(kubectl.edit)", "ge", opts) -- Edit resource
    k("n", "<Plug>(kubectl.filter_label)", "<C-l>", opts) -- Filter labels
    k("n", "<Plug>(kubectl.go_up)", "<BS>", opts) -- Go back to previous view
    k("v", "<Plug>(kubectl.filter_term)", "<C-f>", opts) -- Filter selected text
    k("n", "<Plug>(kubectl.select)", "<CR>", opts) -- Resource select action (different on each view)
    k("n", "<Plug>(kubectl.tab)", "<Tab>", opts) -- Tab completion (ascending, when applicable)
    k("n", "<Plug>(kubectl.shift_tab)", "<Tab>", opts) -- Tab completion (descending, when applicable)
    k("n", "<Plug>(kubectl.quit)", "", opts) -- Close view (when applicable)
    k("n", "<Plug>(kubectl.kill)", "gk", opts) -- Pod/portforward kill
    k("n", "<Plug>(kubectl.toggle_headers)", "<M-h>", opts) -- Toggle headers

    -- Views
    k("n", "<Plug>(kubectl.alias_view)", "<C-a>", opts) -- Aliases view
    k("n", "<Plug>(kubectl.contexts_view)", "<C-x>", opts) -- Contexts view
    k("n", "<Plug>(kubectl.filter_view)", "<C-f>", opts) -- Filter view
    k("n", "<Plug>(kubectl.namespace_view)", "<C-n>", opts) -- Namespaces view
    k("n", "<Plug>(kubectl.portforwards_view)", "gP", opts) -- Portforwards view
    k("n", "<Plug>(kubectl.view_deployments)", "1", opts) -- Deployments view
    k("n", "<Plug>(kubectl.view_pods)", "2", opts) -- Pods view
    k("n", "<Plug>(kubectl.view_configmaps)", "3", opts) -- ConfigMaps view
    k("n", "<Plug>(kubectl.view_secrets)", "4", opts) -- Secrets view
    k("n", "<Plug>(kubectl.view_services)", "5", opts) -- Services view
    k("n", "<Plug>(kubectl.view_ingresses)", "6", 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_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_pv)", "", opts) -- PersistentVolumes view
    k("n", "<Plug>(kubectl.view_pvc)", "", opts) -- PersistentVolumeClaims view
    k("n", "<Plug>(kubectl.view_sa)", "", opts) -- ServiceAccounts 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", "<Plug>(kubectl.rollout_restart)", "grr", opts) -- Rollout restart
    k("n", "<Plug>(kubectl.scale)", "gss", opts) -- Scale workload
    k("n", "<Plug>(kubectl.set_image)", "gi", opts) -- Set image (only if 1 container)

    -- Pod/Container logs
    k("n", "<Plug>(kubectl.logs)", "gl", opts) -- Logs view
    k("n", "<Plug>(kubectl.history)", "gh", opts) -- Change logs --since= flag
    k("n", "<Plug>(kubectl.follow)", "f", opts) -- Follow logs
    k("n", "<Plug>(kubectl.wrap)", "gw", opts) -- Toggle wrap log lines
    k("n", "<Plug>(kubectl.prefix)", "gp", opts) -- Toggle container name prefix
    k("n", "<Plug>(kubectl.timestamps)", "gt", opts) -- Toggle timestamps prefix
    k("n", "<Plug>(kubectl.previous_logs)", "gpp", opts) -- Toggle show previous logs

    -- Node actions
    k("n", "<Plug>(kubectl.cordon)", "gC", opts) -- Cordon node
    k("n", "<Plug>(kubectl.uncordon)", "gU", opts) -- Uncordon node
    k("n", "<Plug>(kubectl.drain)", "gR", opts) -- Drain node

    -- Top actions
    k("n", "<Plug>(kubectl.top_nodes)", "gn", opts) -- Top nodes
    k("n", "<Plug>(kubectl.top_pods)", "gp", opts) -- Top pods

    -- CronJob actions
    k("n", "<Plug>(kubectl.suspend_cronjob)", "gx", opts) -- Suspend CronJob
    k("n", "<Plug>(kubectl.create_job)", "gc", opts) -- Create Job from CronJob

    k("n", "<Plug>(kubectl.portforward)", "gp", opts) -- Pods/Services portforward
    k("n", "<Plug>(kubectl.browse)", "gx", opts) -- Ingress view
    k("n", "<Plug>(kubectl.yaml)", "gy", 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 = {} },
  namespace = "All",
  namespace_fallback = {}, -- If you have limited access you can list all the namespaces here
  hints = true,
  context = true,
  heartbeat = true,
  kubernetes_versions = true,
  lineage = {
    enabled = false, -- 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,
  },
  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,
  },
  obj_fresh = 5, -- highlight if creation newer than number (in minutes)
}

🎨 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 }	-

🚀 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 we advance to v1.0.0, our primary goal is to maintain the stability of the plugin and minimize any breaking changes. We are committed to providing a reliable and consistent user experience.

💪🏼 Motivation

This plugins main purpose is to browse the kubernetes state using vim like navigation and keys, similar to oil.nvim for file browsing.