helmview/README.md

HelmView - Visual Helm Chart Editor & Validator

HelmView is a production-ready web-based visual Helm chart editor and validator. Upload existing Helm charts, render them, visualize all Kubernetes resources, edit them safely with autocomplete + validation, and export fully working Helm charts that pass all validation checks.

🚀 Features

Core Functionality

• 📤 Chart Upload: Upload Helm charts as .tgz, .tar.gz, or .zip archives
• 🔄 Helm Rendering: Render charts with custom values, release names, and namespaces
• 👀 Visual Resource View: Grid view of all Kubernetes resources with filtering
• ✏️ YAML Editor: Monaco editor with:
  • Real-time syntax highlighting
  • Kubernetes-aware autocomplete
  • Schema-based validation
  • Inline error markers
• 📦 Safe Export: Export modified charts with automatic validation
• 🔍 Advanced Filtering: Filter resources by kind, name, namespace, and labels
• 📊 Resource Tracking: Track modifications and view diffs

Security Features

• ✅ Sandboxed filesystem per project
• ✅ Protection against zip-slip attacks
• ✅ File size limits (100MB default)
• ✅ Execution timeouts for Helm commands
• ✅ No user code execution - only Helm template/lint
• ✅ Input validation and YAML schema checking

📋 Tech Stack

Frontend

• React 18 with Vite (JavaScript)
• Monaco Editor for YAML editing with autocomplete
• React Router for navigation
• Axios for API communication
• js-yaml for YAML parsing

Backend

• FastAPI (Python 3.11+)
• Helm 3 CLI integration
• PyYAML for YAML processing
• Kubernetes Python Client for schema validation

Infrastructure

• Docker + Docker Compose for containerized deployment
• PostgreSQL support ready (optional, for history/versioning)

🛠️ Installation & Setup

Prerequisites

• Docker 20.10+
• Docker Compose 2.0+
• 4GB RAM minimum
• 10GB free disk space

Quick Start

1. Clone the repository

git clone <repository-url>
cd helmview

2. Start the application

docker-compose up --build

3. Access the application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

The application will automatically:

• Install Helm 3 in the backend container
• Set up all dependencies
• Create necessary directories
• Start both frontend and backend services

Environment Variables

Create a .env file to customize settings:

# Backend Configuration
WORKSPACE_BASE_PATH=/tmp/helmview_workspaces
MAX_UPLOAD_SIZE=104857600  # 100MB in bytes
HELM_TIMEOUT=60  # seconds

# Frontend Configuration
VITE_API_URL=http://localhost:8000

📖 Usage Guide

1. Create a Project

1. Click "Create Project" on the dashboard
2. Enter project name and optional description
3. Click "Create Project"

2. Upload a Helm Chart

1. Open your project
2. Click "Upload Chart"
3. Drag & drop or browse for your chart file (.tgz, .tar.gz, or .zip)
4. Click "Upload Chart"

3. Render the Chart

1. Click "Render" or "Re-render"
2. Configure render options:
   • Release Name: Name for the Helm release
   • Namespace: Target Kubernetes namespace
   • Values Override: Optional YAML to override values
3. Click "Render Chart"
4. View rendered resources in the grid

4. Edit Resources

1. Click on any resource card to expand it
2. Switch to the "YAML" tab
3. Edit the YAML with autocomplete support:
   • Press Ctrl+Space for autocomplete suggestions
   • Real-time validation shows errors instantly
4. Click "Save Changes" (only enabled when valid)

5. Filter Resources

Use the filters section to narrow down resources:

• Kind: Filter by resource type (Deployment, Service, etc.)
• Name: Search by resource name
• Namespace: Filter by namespace

6. Export Modified Chart

1. Click "Export Chart"
2. Review the export process steps
3. Click "Export Chart"
4. Wait for validation (helm lint + helm template)
5. If successful, click "Download Chart"

The exported chart includes:

• All your modifications
• Bumped version in Chart.yaml
• Generated overlay templates (_helmview_generated.yaml)
• Full Helm validation passed

🏗️ Architecture

Project Structure

helmview/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── requirements.txt     # Python dependencies
│   └── Dockerfile          # Backend container
├── frontend/
│   ├── src/
│   │   ├── components/     # React components
│   │   │   ├── ResourceCard.jsx
│   │   │   ├── YamlEditor.jsx
│   │   │   ├── UploadSection.jsx
│   │   │   ├── RenderSection.jsx
│   │   │   └── ExportModal.jsx
│   │   ├── pages/          # Page components
│   │   │   ├── ProjectDashboard.jsx
│   │   │   └── RenderView.jsx
│   │   ├── api.js          # API client
│   │   ├── App.jsx         # Root component
│   │   └── main.jsx        # Entry point
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile          # Frontend container
└── docker-compose.yml       # Orchestration

API Endpoints

Projects

• POST /api/projects - Create a new project
• GET /api/projects - List all projects
• GET /api/projects/{id} - Get project details
• DELETE /api/projects/{id} - Delete a project

Charts

• POST /api/projects/{id}/upload - Upload a Helm chart
• POST /api/projects/{id}/render - Render chart with options
• GET /api/projects/{id}/resources - Get all resources
• PUT /api/projects/{id}/resources/{uid} - Update a resource
• POST /api/projects/{id}/export - Export modified chart
• GET /api/projects/{id}/download - Download exported chart

Utilities

• GET /health - Health check
• GET /api/kubernetes-schemas/{kind} - Get K8s schema for autocomplete

🔒 Security Notes

Implemented Protections

1. File Upload Security

   • Size limits enforced (100MB default)
   • Extension validation
   • Zip-slip protection during extraction
   • Safe path traversal checks

2. Execution Security

   • No arbitrary code execution
   • Helm runs only with template and lint commands
   • No hook execution
   • Command timeouts (60s default)

3. Isolation

   • Each project gets a sandboxed directory
   • Temporary files cleaned up after operations
   • Docker container isolation

4. Input Validation

   • YAML syntax validation
   • Kubernetes schema validation
   • API input sanitization

Production Recommendations

• Add authentication/authorization
• Implement rate limiting
• Use persistent storage (PostgreSQL) for project metadata
• Set up HTTPS/TLS
• Configure resource limits in docker-compose
• Add audit logging
• Implement RBAC for multi-user scenarios
• Regular security updates for dependencies

🧪 Development

Local Development (without Docker)

Backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Running Tests

# Backend tests (add pytest)
cd backend
pytest

# Frontend tests (add vitest)
cd frontend
npm run test

📊 Future Enhancements

Planned Features

• Database Integration: PostgreSQL for project history, versioning, and diffs
• Undo/Redo: Per-resource undo/redo functionality
• Template Source Tracking: Show which Helm template produced each resource
• Values Highlighting: Highlight values.yaml keys used by resources
• Multi-user Support: User authentication and project sharing
• Diff Viewer: Visual diff between original and modified resources
• Form Editors: GUI editors for common resource types
• Search: Full-text search across all resources
• Export to Git: Push modified charts directly to Git repositories

🐛 Troubleshooting

Common Issues

1. Backend fails to start

# Check Helm installation
docker-compose exec backend helm version

# Check logs
docker-compose logs backend

2. Frontend can't connect to backend

• Verify backend is running: curl http://localhost:8000/health
• Check CORS settings in backend/main.py
• Ensure VITE_API_URL is set correctly

3. Chart upload fails

• Verify file size is under 100MB
• Ensure file is valid .tgz, .tar.gz, or .zip
• Check backend logs for detailed error

4. Export fails validation

• Review helm lint output in the modal
• Check for YAML syntax errors
• Ensure all resources have required fields

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

📧 Support

For issues and questions:

• GitHub Issues: [Create an issue]
• Documentation: [Wiki]

---

Built with ❤️ for the Kubernetes community