{"id":31790936,"url":"https://github.com/rogosprojects/krelease-tracker","last_synced_at":"2025-10-10T16:47:02.578Z","repository":{"id":313610437,"uuid":"1050304679","full_name":"rogosprojects/krelease-tracker","owner":"rogosprojects","description":"Easily track container image deployments across Kubernetes namespaces, monitor and visualize release history.","archived":false,"fork":false,"pushed_at":"2025-09-24T06:46:47.000Z","size":230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-24T08:37:13.929Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rogosprojects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T08:40:20.000Z","updated_at":"2025-09-24T06:46:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"12c0fbfc-a1cb-4fe0-ac5e-5423cafc9cc5","html_url":"https://github.com/rogosprojects/krelease-tracker","commit_stats":null,"previous_names":["rogosprojects/krelease-tracker"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rogosprojects/krelease-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogosprojects%2Fkrelease-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogosprojects%2Fkrelease-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogosprojects%2Fkrelease-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogosprojects%2Fkrelease-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rogosprojects","download_url":"https://codeload.github.com/rogosprojects/krelease-tracker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogosprojects%2Fkrelease-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004698,"owners_count":26083751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T16:46:58.733Z","updated_at":"2025-10-10T16:47:02.571Z","avatar_url":"https://github.com/rogosprojects.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Release Tracker](docs/images/logo.jpeg)\n\n# Release Tracker\n\nA Go application that tracks container image deployments across Kubernetes namespaces, providing a web interface to monitor and visualize release history.\n\n## Features\n\n- **Kubernetes Integration**: Monitors Deployments, StatefulSets, DaemonSets, and ReplicaSets across specified namespaces automatically\n- **Data Storage**: SQLite database with automatic deduplication and retention (10 most recent releases per single component)\n- **REST API**: Endpoints for triggering collection, retrieving current releases, and accessing release history\n- **Web Interface**:\n  - Dashboard with hierarchical table view and full-text search\n  - Timeline page with release history visualization\n  - Badge viewer to generate shields.io style badges for READMEs\n  - Authentication support for API keys and badges\n  - Multi-client, multi-environment support\n- **Master and Slave Modes**: Centralized monitoring and control for multi-cluster deployments. [Read the full guide](MASTER_MODE_GUIDE.md)\n\n![Release Tracker Dashboard](docs/images/master_screen.png)\n\n## Architecture\n\n### Master Mode (in-cluster)\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Slave Mode    │    │   Slave Mode    │    │   Master Mode   │\n│   Client A      │───▶│   Client B      │───▶│   Aggregator    │\n│   - dev         │    │   - staging     │    │   - All Clients │\n│   - prod        │    │   - prod        │    │   - All Envs    │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n\n## Quick Start\n\n### Local Development\n\n#### Prerequisites\n\n- Go 1.21+\n- Docker (for containerization)\n- Kubernetes cluster with appropriate RBAC permissions\n\n1. **Clone and setup**:\n   ```bash\n   # Clone the repository first\n   cd krelease-tracker\n   go mod tidy\n   ```\n\n2. **Run locally** (requires kubeconfig):\n   ```bash\n   export NAMESPACES=\"default,kube-system\"\n   export IN_CLUSTER=\"false\"\n   export DATABASE_PATH=\"./releases.db\"\n   go run cmd/server/main.go\n   ```\n\n3. **Access the application**:\n   - Dashboard: http://localhost:8080\n   - Timeline: http://localhost:8080/timeline.html\n   - Badge Viewer: http://localhost:8080/badges.html\n   - API: http://localhost:8080/api/\n\n### Kubernetes Deployment with Helm\n\n```bash\n# Add Helm repository\nhelm repo add rogosprojects https://rogosprojects.github.io/helm\n# Update Helm repositories\nhelm repo update\n# Install\nhelm install krelease-tracker rogosprojects/krelease-tracker\n```\n**Done!** Follow the post-installation instructions to access the application.\n\n[Read the full Helm chart documentation with default values.yaml](https://rogosprojects.github.io/helm/charts/krelease-tracker/)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `8080` | HTTP server port |\n| `DATABASE_PATH` | `/data/releases.db` | SQLite database file path |\n| `NAMESPACES` | `default` | Comma-separated list of namespaces to monitor |\n| `COLLECTION_INTERVAL` | `60` | Collection interval in minutes |\n| `IN_CLUSTER` | `true` | Whether running inside Kubernetes cluster |\n| `KUBECONFIG` | `\"\"` | Path to kubeconfig file (for out-of-cluster) |\n| `API_KEYS` | `\"\"` | Comma-separated list of API keys for authentication (optional) |\n| `ENV_NAME` | `unknown` | Environment name displayed in badges (e.g., \"production\", \"staging\") |\n| `BASE_PATH` | `\"\"` | Base path for serving (e.g., \"/tracker\" for ingress with path prefix) |\n| `MODE` | `slave` | Application mode: \"master\" or \"slave\" |\n| `MASTER_URL` | `\"\"` | Master URL for sync (slave mode only) |\n| `MASTER_API_KEY` | `\"\"` | Master API key for sync (slave mode only) |\n| `SYNC_INTERVAL` | `5` | Sync interval in minutes (slave mode only) |\n| `PROXY_URL` | `\"\"` | HTTP/HTTPS proxy URL for sync requests (slave mode only) |\n| `TLS_INSECURE` | `false` | Skip TLS certificate verification for sync requests (slave mode only) |\n\n\n## API Authentication\n\nRelease Tracker supports optional API key authentication for all REST API endpoints with client-based access control. When API keys are configured, all `/api/*` endpoints require authentication.\n\n### API Key Types\n\n**1. Admin API Keys** - Full access to all clients and environments\n- Format: `{adminAuth}` (no client prefix)\n- Example: `admin-secret-key-12345678901234567890`\n- Access: Can view and manage all clients and environments\n\n**2. Standard API Keys** - Restricted access to specific client name\n- Format: `{clientName}-{clientAuth}` (exactly one hyphen separator)\n- Example: `client1-authkey12345678901234567890`\n- Access: Can only view and manage the specified client's data\n\n**API Key Requirements:**\n- Minimum 32 characters\n- Only alphanumeric characters, hyphens, and underscores allowed\n- Case-sensitive\n- For client keys: client name must not contain hyphens (use underscores instead)\n\n### Access Control Behavior\n\n**Admin API Keys:**\n- Can access all clients and environments\n- Web UI shows full client/environment selector\n- Can use any client name in API requests\n- Can access all badge endpoints\n\n**Standard API Keys:**\n- Restricted to the specified client only\n- Web UI auto-selects the client and shows environment selector only\n- API requests are validated - can only access the authenticated client's data\n- Badge URLs must match the authenticated client\n- Attempting to access other clients returns `403 Forbidden`\n\n\n### Authentication Methods\n\n**1. HTTP Headers (recommended for API clients):**\n```bash\n# Admin API key - access all clients\ncurl -H \"Authorization: Bearer admin-master-key-12345678901234567890\" \\\n     \"http://localhost:8080/api/releases/current?client_name=any-client\u0026env_name=any-env\"\n\n# Client API key - restricted access\ncurl -H \"X-API-Key: client1-authkey12345678901234567890\" \\\n     \"http://localhost:8080/api/releases/current?client_name=client1\u0026env_name=production\"\n```\n\n**2. Query Parameters (for web UI access):**\n```bash\n# Admin access - shows client/environment selector\nhttp://localhost:8080/?apikey=admin-master-key-12345678901234567890\n\n# Client-specific access - auto-selects client, shows environment selector\nhttp://localhost:8080/?apikey=client1-authkey12345678901234567890\n\n```\n\n**3. Badge URLs (URL-based authentication):**\n```bash\n# Admin API key can access any client's badges\nhttp://localhost:8080/badges/admin-master-key-12345678901234567890/any-client/production/deployment/app/container\n\n# Client API key can only access its own client's badges\nhttp://localhost:8080/badges/client1-authkey12345678901234567890/client1/production/deployment/app/container\n```\n\n\n### Security Notes\n\n- **HTTPS Recommended**: Always use HTTPS in production to protect API keys in transit\n- **Query Parameter Logging**: API keys in URLs may appear in access logs - use headers when possible\n- **Key Rotation**: Multiple API keys are supported for zero-downtime rotation\n- **Client Isolation**: Standard API keys provide secure client data isolation\n- **No Authentication**: If `API_KEYS` is not set, authentication is disabled entirely\n\n\n## RBAC Requirements\n\nThe application requires the following Kubernetes permissions:\n\n```yaml\nrules:\n- apiGroups: [\"\"]\n  resources: [\"pods\"]\n  verbs: [\"get\", \"list\", \"watch\"]\n- apiGroups: [\"apps\"]\n  resources: [\"deployments\", \"statefulsets\", \"daemonsets\", \"replicasets\"]\n  verbs: [\"get\", \"list\", \"watch\"]\n- apiGroups: [\"\"]\n  resources: [\"namespaces\"]\n  verbs: [\"get\", \"list\"]\n```\n## Database Schema\n\nThe SQLite database stores release information with the following schema:\n\n```sql\nCREATE TABLE releases (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    namespace TEXT NOT NULL,\n    workload_name TEXT NOT NULL,\n    workload_type TEXT NOT NULL,\n    container_name TEXT NOT NULL,\n    image_repo TEXT NOT NULL,\n    image_name TEXT NOT NULL,\n    image_tag TEXT NOT NULL,\n    client_name TEXT NOT NULL,\n    env_name TEXT NOT NULL,\n    first_seen DATETIME NOT NULL,\n    last_seen DATETIME NOT NULL,\n    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n    UNIQUE(namespace, workload_name, container_name, client_name, env_name, image_repo, image_name, image_tag)\n);\n```\n## Web Interface\n\n### Dashboard\n- **Hierarchical View**: Namespace → Workload Type → Workload Name → Container → Image Details\n- **Search**: Full-text search across all fields\n- **Real-time Data**: Live collection and refresh capabilities\n- **Navigation**: Direct links to timeline view for each component\n\n### Timeline\n- **Component Selection**: Dropdown selectors for namespace/workload/container\n- **Visual Timeline**: Chronological view of releases with timestamps\n- **Release Details**: Complete image information for each release\n- **URL Parameters**: Direct linking to specific component timelines\n\n### Badges\n- **Viewer**: Interactive badge generator with API key authentication\n- **Authentication**: URL-based API key authentication for badge requests\n- **Markdown**: Copyable markdown for README embedding\n\n## Logging\n\n- Structured logging for collection activities\n- Error tracking and reporting\n- Request logging for API endpoints\n\n## Security\n\n### Container Security\n- Non-root user execution\n- Read-only root filesystem\n- Minimal Alpine base image\n- Security context with dropped capabilities\n\n### RBAC\n- Least-privilege access to Kubernetes resources\n- Namespace-scoped permissions where possible\n- Service account isolation\n\n\n## Documentation\n\nFor detailed guides on specific features and configurations:\n\n- **[API Endpoints Documentation](docs/API_ENDPOINTS_GUIDE.md)** - REST API documentation with authentication details\n- **[Proxy Support Guide](docs/PROXY_SUPPORT_GUIDE.md)** - Configure HTTP/HTTPS proxy for sync and ping operations\n- **[Ping System Guide](docs/PING_SYSTEM_GUIDE.md)** - Health monitoring and slave connectivity tracking\n- **[Master Mode Guide](docs/MASTER_MODE_GUIDE.md)** - Setting up master instances for multi-cluster deployments\n- **[API Key Client Access Control](docs/api-key-client-access-control-implementation.md)** - Detailed API authentication implementation\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogosprojects%2Fkrelease-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frogosprojects%2Fkrelease-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogosprojects%2Fkrelease-tracker/lists"}