|
| 1 | +# Helm Diff Plugin |
| 2 | + |
| 3 | +Helm Diff is a Go-based Helm plugin that provides diff functionality for comparing Helm charts and releases. It shows what changes would occur during helm upgrade, rollback, or between different releases/revisions. |
| 4 | + |
| 5 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +**Prerequisites:** |
| 10 | +- Go >= 1.21 (currently uses Go 1.24.5) |
| 11 | +- Helm v3 (tested with v3.17.4 and v3.18.6) |
| 12 | +- Make sure `/home/runner/go/bin` is in your PATH for staticcheck: `export PATH=$PATH:/home/runner/go/bin` |
| 13 | + |
| 14 | +**Bootstrap and Build Process:** |
| 15 | +- ALWAYS run: `make bootstrap` first - downloads dependencies and installs staticcheck. Takes <1 second (if already done) or ~50 seconds (first time). |
| 16 | +- Build the plugin: `make build` - includes linting and compiles the binary. Takes ~9 seconds after bootstrap. |
| 17 | +- NEVER CANCEL builds. Set timeout to 3+ minutes for bootstrap, 2+ minutes for build operations. |
| 18 | + |
| 19 | +**Testing:** |
| 20 | +- Run unit tests: `make test` - includes coverage analysis. Takes ~12 seconds. NEVER CANCEL - set timeout to 3+ minutes. |
| 21 | +- Tests include comprehensive coverage (38.7% overall) and use a fake helm binary for isolation. |
| 22 | +- Test coverage is generated in `cover.out` with detailed function-level coverage reports. |
| 23 | + |
| 24 | +**Linting and Code Quality:** |
| 25 | +- Local linting: `make lint` - runs gofmt, go vet, and staticcheck verification. Takes ~2 seconds. |
| 26 | +- Code formatting: `make format` - applies gofmt formatting automatically. Takes <1 second. |
| 27 | +- Full golangci-lint runs only in CI via GitHub Actions, not available locally. |
| 28 | +- ALWAYS run `make format` and `make lint` before committing changes. |
| 29 | + |
| 30 | +**Plugin Installation:** |
| 31 | +- Install as Helm plugin: `make install` or `make install/helm3` - builds and installs to Helm plugins directory. Takes ~3 seconds. |
| 32 | +- The plugin installs via `install-binary.sh` script which handles cross-platform binary installation. |
| 33 | + |
| 34 | +## Validation Scenarios |
| 35 | + |
| 36 | +**ALWAYS test your changes with these scenarios:** |
| 37 | + |
| 38 | +1. **Basic Plugin Functionality:** |
| 39 | + ```bash |
| 40 | + # Test the binary directly |
| 41 | + ./bin/diff version |
| 42 | + ./bin/diff --help |
| 43 | + ./bin/diff upgrade --help |
| 44 | + ``` |
| 45 | + |
| 46 | +2. **Real Chart Diffing:** |
| 47 | + ```bash |
| 48 | + # Create a test chart and diff it |
| 49 | + cd /tmp && helm create test-chart |
| 50 | + cd /path/to/helm-diff |
| 51 | + HELM_NAMESPACE=default HELM_BIN=helm ./bin/diff upgrade --install --dry-run test-release /tmp/test-chart |
| 52 | + ``` |
| 53 | + |
| 54 | +3. **Plugin Installation Verification:** |
| 55 | + ```bash |
| 56 | + # Test plugin installation |
| 57 | + export HELM_DATA_HOME=/tmp/helm-test |
| 58 | + make install |
| 59 | + /tmp/helm-test/plugins/helm-diff/bin/diff version |
| 60 | + ``` |
| 61 | + |
| 62 | +## Build Times and Timeouts |
| 63 | + |
| 64 | +**CRITICAL: NEVER CANCEL long-running commands. Use these timeout values:** |
| 65 | + |
| 66 | +- `make bootstrap`: <1 second (if already done) or ~50 seconds (first time) (set timeout: 5+ minutes) |
| 67 | +- `make build`: ~9 seconds after bootstrap (set timeout: 3+ minutes) |
| 68 | +- `make test`: ~12 seconds (set timeout: 3+ minutes) |
| 69 | +- `make lint`: ~2 seconds (set timeout: 1 minute) |
| 70 | +- `make format`: <1 second (set timeout: 1 minute) |
| 71 | +- `make install`: ~3 seconds (set timeout: 2 minutes) |
| 72 | + |
| 73 | +## Common Tasks |
| 74 | + |
| 75 | +**Repository Structure:** |
| 76 | +- `main.go` - Entry point that delegates to cmd package |
| 77 | +- `cmd/` - Command-line interface implementation (upgrade, release, revision, rollback, version) |
| 78 | +- `diff/` - Core diffing logic and output formatting |
| 79 | +- `manifest/` - Kubernetes manifest parsing and handling |
| 80 | +- `scripts/` - Build and verification scripts (gofmt, govet, staticcheck) |
| 81 | +- `testdata/`, `*/testdata/` - Test fixtures and mock data |
| 82 | +- `plugin.yaml` - Helm plugin configuration |
| 83 | +- `install-binary.sh` - Cross-platform installation script |
| 84 | +- `Makefile` - Build system with all common targets |
| 85 | + |
| 86 | +**Key Files to Check After Changes:** |
| 87 | +- Always run tests after modifying `cmd/` or `diff/` packages |
| 88 | +- Check `plugin.yaml` version if making release changes |
| 89 | +- Verify `Makefile` targets if changing build process |
| 90 | +- Review `install-binary.sh` if modifying installation process |
| 91 | + |
| 92 | +**Environment Variables for Testing:** |
| 93 | +- `HELM_NAMESPACE` - Kubernetes namespace for operations |
| 94 | +- `HELM_BIN` - Path to helm binary (for direct testing) |
| 95 | +- `HELM_DIFF_USE_UPGRADE_DRY_RUN` - Use helm upgrade --dry-run instead of template |
| 96 | +- `HELM_DIFF_THREE_WAY_MERGE` - Enable three-way merge diffing |
| 97 | +- `HELM_DIFF_NORMALIZE_MANIFESTS` - Normalize YAML before diffing |
| 98 | +- `HELM_DIFF_OUTPUT_CONTEXT` - Configure output context lines |
| 99 | + |
| 100 | +**CI/CD Information:** |
| 101 | +- GitHub Actions runs on push/PR to master branch |
| 102 | +- Tests run on Ubuntu, macOS, Windows with multiple Helm versions |
| 103 | +- Integration tests use Kind (Kubernetes in Docker) |
| 104 | +- Linting uses golangci-lint via GitHub Actions (not available locally) |
| 105 | +- Cross-platform plugin installation is tested via Docker |
| 106 | + |
| 107 | +**Direct Binary Usage (for development):** |
| 108 | +```bash |
| 109 | +# Build and test directly without Helm plugin installation |
| 110 | +go build -o bin/diff -ldflags="-X github.com/databus23/helm-diff/v3/cmd.Version=dev" |
| 111 | +HELM_NAMESPACE=default HELM_BIN=helm ./bin/diff upgrade --install --dry-run my-release ./chart-path |
| 112 | +``` |
| 113 | + |
| 114 | +**Common Commands Reference:** |
| 115 | +```bash |
| 116 | +# Full development cycle |
| 117 | +make bootstrap # Install dependencies (once) |
| 118 | +make build # Build with linting |
| 119 | +make test # Run all tests |
| 120 | +make format # Format code |
| 121 | +make install # Install as Helm plugin |
| 122 | + |
| 123 | +# Validation |
| 124 | +./bin/diff version # Check version |
| 125 | +./bin/diff upgrade --help # Check help |
| 126 | +make test # Run test suite |
| 127 | +``` |
| 128 | + |
| 129 | +## Important Notes |
| 130 | + |
| 131 | +- The plugin supports Helm v3 only (v2 support was removed) |
| 132 | +- Uses Go modules for dependency management |
| 133 | +- Cross-platform support: Linux, macOS, Windows, FreeBSD |
| 134 | +- Multiple output formats: diff, simple, template, dyff |
| 135 | +- Supports both client-side and server-side dry-run modes |
| 136 | +- Includes three-way merge capabilities for advanced diffing |
| 137 | +- Plugin binary is named `diff` and installed as `helm diff` command |
0 commit comments