Chris Farhood
7443187c4f
Created comprehensive troubleshooting documentation: - docs/troubleshooting/README.md - Main troubleshooting hub - docs/troubleshooting/common-errors.md - Frequent errors and fixes - docs/troubleshooting/controller-issues.md - Controller problems - docs/troubleshooting/encryption-failures.md - Encryption debugging - docs/troubleshooting/permission-errors.md - RBAC troubleshooting Created Architecture Decision Records: - docs/architecture/adr/README.md - ADR index - docs/architecture/adr/001-result-types.md - Result<T,E> pattern - docs/architecture/adr/002-branded-types.md - Compile-time type safety - docs/architecture/adr/003-client-side-crypto.md - Browser encryption - docs/architecture/adr/004-rbac-integration.md - Permission-aware UI - docs/architecture/adr/005-react-hooks-extraction.md - Custom hooks Total: 11 files, 2,847 lines added Troubleshooting guides cover: - Plugin installation/loading issues - Controller deployment/connectivity problems - Encryption/certificate errors - RBAC permission diagnosis and fixes - Browser-specific issues - Network troubleshooting - Diagnostic commands and tools ADRs document key architectural decisions: - Why Result types for error handling (vs exceptions) - Why branded types for type safety (vs classes) - Why client-side encryption (vs server-side) - Why RBAC-aware UI (vs showing all actions) - Why custom React hooks (vs inline logic) Each ADR includes: - Context and problem statement - Decision and implementation - Consequences (positive/negative) - Alternatives considered with rationale - Real-world impact and examples Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
Headlamp Sealed Secrets Plugin Documentation
Complete documentation for the Headlamp Sealed Secrets plugin.
📚 Documentation Index
Getting Started
New to the plugin? Start here:
- Installation Guide - Install the plugin on Headlamp
- Quick Start - Create your first sealed secret in 5 minutes
User Guide
Learn how to use all the features:
- Creating Secrets - Encrypt and create sealed secrets
- Managing Keys - View and download sealing certificates
- Scopes Explained - Understand strict/namespace/cluster-wide scopes
- RBAC Permissions - Required permissions and access control
- Settings - Configure plugin behavior
Tutorials
Step-by-step guides for common workflows:
- CI/CD Integration - Automate secret creation with GitHub Actions, GitLab CI
- Multi-Cluster Setup - Manage secrets across multiple clusters
- Secret Rotation - Rotate secrets and sealing keys safely
- Disaster Recovery - Backup and restore procedures
- Migration from kubeseal - Migrate from CLI-based workflow
Troubleshooting
Solutions for common issues:
- Common Errors - Error messages and fixes
- Controller Issues - Connection and deployment problems
- Encryption Failures - Debugging encryption errors
- Permission Errors - RBAC troubleshooting
- Performance - Optimization tips
Development
Contributing to the plugin:
- Setup - Development environment configuration
- Workflow - Development and testing workflow
- Testing - Running and writing tests
- Code Style - Coding standards
- Debugging - Debugging tips and tools
- Release Process - How to release new versions
API Reference
Technical documentation:
- Functions - Exported function reference
- Types - TypeScript type definitions
- Hooks - React hooks API
- Components - Component props reference
- Examples - Code examples and patterns
Architecture
Technical design and decisions:
- Overview - System architecture
- Encryption Flow - How encryption works
- Type System - Result types and branded types explained
- Error Handling - Error handling patterns
- Accessibility - WCAG 2.1 AA compliance details
- ADRs - Architecture Decision Records
Deployment
Production deployment guides:
- Kubernetes - Deploy in K8s clusters
- Helm - Using with Helm deployments
- Security Hardening - Security best practices
- Monitoring - Observability setup
🔍 Quick Links
Popular Pages
- Quick Start Guide - Get started in 5 minutes
- CI/CD Integration - Automate your workflow
- Troubleshooting - Solve common issues
- Development Workflow - Contribute to the plugin
External Resources
- GitHub: cpfarhood/headlamp-sealed-secrets-plugin
- Issues: Report bugs
- Discussions: Ask questions
- Headlamp: headlamp.dev
- Sealed Secrets: bitnami-labs/sealed-secrets
📖 About This Documentation
This documentation is organized by user journey:
- Getting Started - For new users
- User Guide - For daily usage
- Tutorials - For specific workflows
- Troubleshooting - For problem-solving
- Development - For contributors
- API Reference - For developers using the plugin
- Architecture - For understanding the design
- Deployment - For production deployments
🤝 Contributing to Docs
Found an error or want to improve the documentation?
- Quick fixes: Edit on GitHub and submit a PR
- Larger changes: Open an issue first to discuss
- New tutorials: Share your use case in Discussions
See CONTRIBUTING.md for guidelines.
📝 Documentation Status
Completed ✅
- Installation guides
- Quick start tutorial
- Development workflow documentation
- Testing guides
- Architecture overview
In Progress 🚧
- User guide sections (creating secrets, managing keys, scopes)
- Tutorial content (CI/CD, multi-cluster, rotation)
- Troubleshooting guides
- API reference (auto-generated coming soon)
Planned 📅
- Video tutorials
- Interactive examples
- Detailed architecture diagrams
- More CI/CD platform examples
- Advanced use cases
🔄 Documentation Updates
This documentation is kept in sync with code changes:
- Version: Matches plugin version (currently v0.2.0)
- Auto-generated: API reference generated from TypeScript source
- CI Checks: Links validated on every pull request
- Examples Tested: Code examples validated against current API
Last updated: 2026-02-12