# HelmView - Visual Helm Chart Editor & Validator

![HelmView](https://img.shields.io/badge/helm-v3-blue)
![React](https://img.shields.io/badge/react-18-blue)
![FastAPI](https://img.shields.io/badge/fastapi-0.109-green)
![Python](https://img.shields.io/badge/python-3.11+-blue)

**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**
```bash
git clone <repository-url>
cd helmview
```

2. **Start the application**
```bash
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:

```env
# 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
```bash
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
```bash
cd frontend
npm install
npm run dev
```

### Running Tests
```bash
# 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**
```bash
# 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**