yaml-ls-k8s

An LSP proxy that wraps yaml-language-server and automatically provides Kubernetes schema validation and completion — no manual schema configuration needed.

It detects apiVersion/kind in your YAML files and fetches the matching JSON schema from GitHub, giving you validation, hover docs, and autocompletion for both core Kubernetes resources and CRDs out of the box.

• Automatic schema detection — parses apiVersion and kind from YAML content and maps them to the correct JSON schema
• Core Kubernetes resources — Deployments, Services, ConfigMaps, etc. via yannh/kubernetes-json-schema
• CRD support — Gateway API, cert-manager, external-secrets, Argo, Istio, and 600+ more via datreeio/CRDs-catalog
• Multi-document YAML — handles --- separated files with mixed resource types
• Full ObjectMeta completion — CRD schemas are enriched with the complete metadata definition (annotations, labels, name, namespace, etc.)
• Local schema caching — schemas are downloaded once and cached on disk
• Modeline passthrough — respects # yaml-language-server: $schema=... modelines when present
• Zero dependencies — built with Go standard library only

Editor (stdin/stdout) → yaml-ls-k8s → yaml-language-server (child process)
                          ↕                        ↕
                    detect apiVersion/kind    schema validation
                    fetch & cache schemas     completions, hover

yaml-ls-k8s sits between your editor and yaml-language-server, intercepting LSP messages to inject the correct yaml.schemas configuration based on the content of each file.

yaml-language-server must be installed:

npm install -g yaml-language-server

Pre-built binaries for Linux and macOS (amd64/arm64) are available on the releases page:

# Example: macOS ARM64 (Apple Silicon)
curl -sL https://github.com/bl4ko/yaml-ls-k8s/releases/latest/download/yaml-ls-k8s-darwin-arm64.tar.gz | tar xz
mv yaml-ls-k8s ~/.local/bin/

go install github.com/bl4ko/yaml-ls-k8s/cmd/yaml-ls-k8s@latest

git clone https://github.com/bl4ko/yaml-ls-k8s.git
cd yaml-ls-k8s
make install   # builds and copies to ~/.local/bin/

require('lspconfig').yamlls.setup({
  cmd = { "yaml-ls-k8s", "--yamlls-path", "yaml-language-server" },
})

-- lua/plugins/lspconfig.lua
return {
  {
    "neovim/nvim-lspconfig",
    opts = {
      servers = {
        yamlls = {
          mason = false,
          cmd = { "yaml-ls-k8s", "--yamlls-path", "yaml-language-server" },
        },
      },
    },
  },
}

vim.lsp.config("yamlls", {
  cmd = { "yaml-ls-k8s", "--yamlls-path", "yaml-language-server" },
  root_markers = { ".git" },
  single_file_support = true,
})
vim.lsp.enable("yamlls")

If you use helm-ls for Helm templates, point its yamlls path to yaml-ls-k8s:

require('lspconfig').helm_ls.setup({
  settings = {
    ['helm-ls'] = {
      yamlls = {
        path = "yaml-ls-k8s",
      },
    },
  },
})

yaml-ls-k8s communicates over stdio and implements the standard LSP protocol. Any editor that supports configuring a custom LSP command can use it — just set the command to yaml-ls-k8s --yamlls-path yaml-language-server.

Check logs:

tail -f ~/.config/yaml-ls-k8s/server.log

Clear schema cache:

rm -rf ~/.cache/yaml-ls-k8s/schemas/

Test if a schema exists:

# Core K8s resource
curl -s -o /dev/null -w "%{http_code}" \
  "https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.35.3-standalone-strict/deployment-apps-v1.json"

# CRD
curl -s -o /dev/null -w "%{http_code}" \
  "https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/gateway.networking.k8s.io/httproute_v1.json"

make build       # build binary
make test        # run all tests (unit + e2e)
make test-unit   # unit tests only
make test-e2e    # e2e tests (requires yaml-language-server)
make install     # build + install to ~/.local/bin/

MIT