kube-schema.nvim

Dynamically inject Kubernetes and CRD schemas into yaml-language-server for YAML files in Neovim. Get validation and completion for your Kubernetes manifests and CRDs, automatically.

---

✨ Features

• 🧠 Auto-detects apiVersion and kind in your YAML buffer
• 🔗 Injects the correct schema for both built-in Kubernetes resources and CRDs
• ⚡ Debounced hot reloads schema on buffer changes to keep editing snappy
• 🧹 Cleans up temporary schema files on exit
• 🔔 Optional notifications via fidget.nvim when available
• 🛠️ Zero config — just install and go!

---

🚀 Installation

lazy.nvim:

{
  "rxbn/kube-schema.nvim",
  opts = {},
}

---

⚙️ Configuration

No configuration is required by default — simply call:

require("kube-schema").setup()

If you want to tune the behavior, setup() accepts a few options:

Option	Type	Default	Description
debounce_ms	number	250	Delay (in ms) before refreshing schemas after text changes. Set to 0 to disable debouncing altogether.
cache_dir	string	vim.fn.stdpath("cache")	Directory where the combined schema files are stored.
notifications	boolean	true	Whether to surface schema updates/errors via fidget.nvim (when available) or fall back to vim.notify.

Example:

require("kube-schema").setup({
  debounce_ms = 150,
  cache_dir = vim.fn.stdpath("data") .. "/kube-schema",
  notifications = false,
})

ℹ️ If fidget.nvim is installed, kube-schema.nvim uses it to surface schema refresh progress and errors automatically. Set notifications = false to disable all status messages.

If you want to customize or extend further, PRs and issues are always welcome!

In order to prevent the "Matches multiple schemas when only one must validate" error, you can use this helper function to configure yamlls:

yamlls = require("kube-schema").configure_yamlls(),

You can also pass custom settings to yamlls, they will be merged with the default settings:

yamlls = require("kube-schema").configure_yamlls({
    settings = {
        yaml = {
            validate = true,
        },
    },
})

You can also use the following manual configuration:

settings = {
    yaml = {
        schemas = {
            kubernetes = "",
        },
    },
},

---

🧩 How it works

• On opening a YAML file, the plugin scans for apiVersion and kind.
• It matches these against built-in Kubernetes resources and CRDs.
• The correct JSON schema(s) are combined and injected into the yamlls LSP client.
• If the file does not look Kubernetes-related yet, the plugin keeps a light-weight watch and upgrades once apiVersion/kind appear.
• As you edit, the schema updates live (debounced to avoid unnecessary LSP churn).
• Temporary schema files are cleaned up on exit.

---

📦 Example

Open a Kubernetes manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  # ... get completion and validation!

The correct schema is automatically applied for validation and completion.

---

🛠️ Requirements

• Neovim 0.11+
• yaml-language-server (yamlls) enabled in your LSP setup

---

🩺 Health Check

Run the built-in health check to verify your setup:

:checkhealth kube-schema

It reports Neovim version, cache directory status, yamlls availability, and optional dependencies like fidget.nvim.

---

🔍 FAQ

Q: Does this work with custom CRDs? A: Yes! If your CRD is in the datreeio/CRDs-catalog, it will be picked up automatically.

Q: Does it support multiple resources in one file? A: Yes, all detected resources are combined into a single schema.

Q: Does it modify my LSP config? A: No, it only updates the schema for the current buffer in yamlls.

---

🧑‍💻 Contributing

PRs and issues are welcome! Feel free to open an issue if you have any questions or suggestions.

---

📄 License

MIT

---

🙏 Credits

• yannh/kubernetes-json-schema
• datreeio/CRDs-catalog
• someone-stole-my-name/yaml-companion.nvim

---

Happy Kubernetes YAMLing! 🚢