fluxcd.nvim

A Neovim plugin for FluxCD Kustomization manifest management and dry-run rendering.

Disclaimer

This plugin was heavily inspired by kusomization.nvim and can work in conjunction with it.

It was coded purely using claude-4-sonnet, courtesy of Cursor, which means I have to make myself clear on couple of things:

• I do not have the slightest idea how all this code works, I just needed a tool at hand right away and was able to create one using LLMs.
• Therefore I'm not sure that I'll be able to support or develop it any further past my personal needs.
• Feel free to fork, modify, develop it in any possible way you see fit.

✨ Features

• 🔍 Auto-detection - Automatically detects FluxCD Kustomization manifests
• 🏃‍♂️ Dry-run rendering - Renders manifests using flux build kustomization --dry-run
• 📁 Smart path management - File-specific kustomization paths with Telescope directory picker
• 💾 Persistent storage - Remembers paths across Neovim sessions
• 🪟 Smart window management - Preserves your layout (neo-tree friendly)
• 🔧 Seamless workflow - One-command operation from path selection to rendering

📋 Requirements

• Neovim 0.8+
• FluxCD CLI - Install from fluxcd.io
• Dependencies:
  • plenary.nvim
  • telescope.nvim

📁 Plugin Structure

fluxcd.nvim/
├── .gitignore
├── LICENSE
├── README.md
├── doc/
│   └── fluxcd.txt              # Vim help documentation
├── examples/
│   ├── lazy.lua                # lazy.nvim configuration example
│   ├── packer.lua              # packer.nvim configuration example
│   └── sample-kustomization.yaml # Sample FluxCD manifest
├── lua/
│   ├── fluxcd.lua              # Main entry point
│   └── fluxcd/
│       └── init.lua            # Core plugin logic
└── plugin/
    └── fluxcd.lua              # Plugin initialization

📦 Installation

Using lazy.nvim

{
  'vgromanov/fluxcd.nvim',
  dependencies = {
    'nvim-lua/plenary.nvim',
    'nvim-telescope/telescope.nvim',
  },
  ft = 'yaml',
  config = function()
    require('fluxcd').setup()
  end,
}

Using packer.nvim

use {
  'vgromanov/fluxcd.nvim',
  requires = {
    'nvim-lua/plenary.nvim',
    'nvim-telescope/telescope.nvim',
  },
  ft = 'yaml',
  config = function()
    require('fluxcd').setup()
  end,
}

Using vim-plug

Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'
Plug 'vgromanov/fluxcd.nvim'

" Add to your init.vim/init.lua
lua require('fluxcd').setup()

⚙️ Configuration

Default Configuration

require('fluxcd').setup({
  flux_cmd = 'flux', -- FluxCD CLI command
})

Custom Keymaps

Add custom keymaps to your configuration:

-- Default keymaps (if you want to override them)
vim.keymap.set('n', '<leader>fd', '<cmd>FluxcdDryRun<CR>', { desc = 'FluxCD dry-run' })
vim.keymap.set('n', '<leader>fp', '<cmd>FluxcdSetPath<CR>', { desc = 'Set FluxCD path' })
vim.keymap.set('n', '<leader>fs', '<cmd>FluxcdStatus<CR>', { desc = 'FluxCD status' })

🚀 Usage

Basic Workflow

1. Open a FluxCD Kustomization YAML file

   apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
   kind: Kustomization
   metadata:
     name: my-app
   spec:
     interval: 1m
     path: "./apps"
     sourceRef:
       kind: GitRepository
       name: my-repo

2. Run dry-run - Press <leader>fd or use :FluxcdDryRun

   • First time: Telescope picker opens for kustomization path selection
   • Subsequent runs: Uses remembered path automatically

3. View results - Rendered manifests appear in a split window

Commands

Command	Description
:FluxcdDryRun	Run FluxCD dry-run for current kustomization
:FluxcdSetPath	Set/change kustomization path with directory picker
:FluxcdStatus	Show plugin status and debug information

Default Keymaps

Keymap	Command	Description
<leader>fd	:FluxcdDryRun	Run dry-run
<leader>fp	:FluxcdSetPath	Set kustomization path
<leader>fs	:FluxcdStatus	Show status

📖 How It Works

Supported FluxCD Versions

The plugin automatically detects FluxCD Kustomization manifests with these API versions:

• kustomize.toolkit.fluxcd.io/v1
• kustomize.toolkit.fluxcd.io/v1beta1
• kustomize.toolkit.fluxcd.io/v1beta2

File-specific Path Management

Each FluxCD manifest can have its own kustomization path:

• apps/frontend.yaml → ./apps/frontend
• clusters/prod.yaml → ./clusters/production
• Paths are stored persistently in ~/.local/share/nvim/fluxcd_paths.json

Smart Window Management

The plugin intelligently manages windows:

• Finds main editor window (skips neo-tree, terminals, etc.)
• Creates splits from the correct window
• Preserves your existing layout
• Reuses result buffers for the same kustomization

🔧 Advanced Configuration

Complete lazy.nvim Example

{
  'vgromanov/fluxcd.nvim',
  dependencies = {
    'nvim-lua/plenary.nvim',
    'nvim-telescope/telescope.nvim',
  },
  ft = 'yaml',
  keys = {
    { '<leader>fd', '<cmd>FluxcdDryRun<CR>', desc = 'FluxCD dry-run' },
    { '<leader>fp', '<cmd>FluxcdSetPath<CR>', desc = 'Set FluxCD path' },
    { '<leader>fs', '<cmd>FluxcdStatus<CR>', desc = 'FluxCD status' },
  },
  config = function()
    require('fluxcd').setup({
      flux_cmd = 'flux', -- Custom flux command if needed
    })
  end,
}

Custom Flux Command

If your flux binary is in a custom location:

require('fluxcd').setup({
  flux_cmd = '/usr/local/bin/flux',
})

🐛 Troubleshooting

FluxCD CLI Not Found

Ensure FluxCD CLI is installed and in your PATH:

# Install FluxCD CLI
curl -s https://fluxcd.io/install.sh | sudo bash

# Verify installation
flux version

Check Plugin Status

Use :FluxcdStatus to see:

• Whether current file is detected as FluxCD Kustomization
• Storage file location and status
• Total stored paths
• Debug information

Storage Location

Kustomization paths are stored in:

• Linux/macOS: ~/.local/share/nvim/fluxcd_paths.json
• Windows: %LOCALAPPDATA%\nvim-data\fluxcd_paths.json

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository
2. Make your changes
3. Test with your FluxCD manifests
4. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by kustomize.vim
• Built with plenary.nvim and telescope.nvim
• FluxCD team for the amazing GitOps toolkit

📊 Status

• ✅ FluxCD API version detection
• ✅ Dry-run execution with flux CLI
• ✅ File-specific path management
• ✅ Persistent storage
• ✅ Telescope integration
• ✅ Smart window management
• ✅ Auto-detection and notifications

---

Made with ❤️ for the FluxCD and Neovim communities