324 lines
9.3 KiB
Markdown
324 lines
9.3 KiB
Markdown
# 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**
|
|
```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**
|