{"id":28955883,"url":"https://github.com/guibes/runbook-operator","last_synced_at":"2026-05-17T03:12:18.811Z","repository":{"id":298606186,"uuid":"1000511507","full_name":"guibes/runbook-operator","owner":"guibes","description":"A cloud-native Kubernetes operator that automatically generates and manages runbook documentation from PrometheusRule configurations with multiple output formats.","archived":false,"fork":false,"pushed_at":"2025-06-12T00:11:48.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T00:38:09.144Z","etag":null,"topics":["alerting","automation","cloud-native","devops","documentation","gitops","incident-response","kubernetes","monitoring","operator","prometheus","runbooks","sre"],"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/guibes.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}},"created_at":"2025-06-11T22:49:32.000Z","updated_at":"2025-06-12T00:11:51.000Z","dependencies_parsed_at":"2025-06-12T00:38:18.581Z","dependency_job_id":"58535f50-37a9-43db-8d61-115b3349455f","html_url":"https://github.com/guibes/runbook-operator","commit_stats":null,"previous_names":["guibes/runbook-operator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/guibes/runbook-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guibes%2Frunbook-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guibes%2Frunbook-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guibes%2Frunbook-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guibes%2Frunbook-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guibes","download_url":"https://codeload.github.com/guibes/runbook-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guibes%2Frunbook-operator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261548756,"owners_count":23175502,"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","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":["alerting","automation","cloud-native","devops","documentation","gitops","incident-response","kubernetes","monitoring","operator","prometheus","runbooks","sre"],"created_at":"2025-06-23T20:11:58.604Z","updated_at":"2026-05-17T03:12:13.769Z","avatar_url":"https://github.com/guibes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# RunbookOperator\n\nA cloud-native Kubernetes operator that automatically generates, manages, and distributes runbook documentation from PrometheusRule configurations.\n\n## The Problem\n\nManual runbook creation and maintenance is time-consuming, error-prone, and often results in outdated documentation when you need it most. Traditional approaches suffer from:\n\n- Runbooks that become stale and disconnected from actual alert definitions\n- Inconsistent documentation formats across teams\n- Manual effort required to keep runbooks synchronized with monitoring rules\n- Lack of standardized incident response procedures\n- No automated validation of runbook procedures\n\n## The Solution\n\nRunbookOperator bridges the gap between alerting and incident response by automatically generating comprehensive runbooks directly from your PrometheusRule annotations. It provides:\n\n- **Automated Generation**: Runbooks are created and updated automatically when PrometheusRule resources change\n- **Multiple Output Formats**: Generate Markdown, HTML, ConfigMaps, and integrate with external APIs\n- **Validation**: Built-in validation ensures runbooks are complete and accurate\n- **GitOps Integration**: Seamlessly integrates with existing GitOps workflows\n- **Template System**: Customizable templates for different alert types and teams\n\n## Quick Example\n\nDefine your alert with runbook content in your PrometheusRule:\n```yaml\n    apiVersion: monitoring.coreos.com/v1\n    kind: PrometheusRule\n    metadata:\n      name: app-alerts\n    spec:\n      groups:\n      - name: application\n        rules:\n        - alert: HighMemoryUsage\n          expr: memory_usage \u003e 0.8\n          annotations:\n            runbook: |\n              ## Impact\n              Application performance degrades when memory exceeds 80%\n              \n              ## Investigation\n              1. Check pod memory: kubectl top pods -l app=myapp\n              2. Review logs: kubectl logs -l app=myapp --tail=100\n              \n              ## Remediation\n              1. Restart pod: kubectl delete pod -l app=myapp\n              2. Scale horizontally: kubectl scale deployment myapp --replicas=3\n```\nThe operator automatically creates a Runbook resource and generates documentation:\n```yaml\n    apiVersion: runbook.runbook.io/v1alpha1\n    kind: Runbook\n    metadata:\n      name: high-memory-usage\n    spec:\n      alertName: \"HighMemoryUsage\"\n      severity: \"warning\"\n      team: \"platform\"\n      outputs:\n        - format: \"markdown\"\n          destination: \"/tmp/runbooks\"\n        - format: \"html\"\n          destination: \"/tmp/runbooks/html\"\n```\n## Prerequisites\n\n- Kubernetes v1.11.3+ cluster\n- Go 1.21+ (for development)\n- Docker 17.03+ (for building images)\n- kubectl v1.11.3+\n\n## Installation\n\n### Quick Start with Kind\n\nCreate development cluster:\n```bash\n    kind create cluster --name runbook-dev\n```\n\nInstall the operator:\n```bash\n    kubectl apply -f https://raw.githubusercontent.com/guibes/runbook-operator/main/config/default\n```\nApply a sample runbook:\n```bash\n    kubectl apply -f https://raw.githubusercontent.com/guibes/runbook-operator/main/config/samples/runbook_v1alpha1_runbook.yaml\n```\n### Production Installation\n\n1. **Install CRDs:**\n```bash\n       kubectl apply -f config/crd/bases/\n```\n2. **Deploy the operator:**\n```bash\n       make deploy IMG=your-registry/runbook-operator:latest\n```\n3. **Create storage for runbook outputs:**\n```bash\n       kubectl apply -f config/storage/\n```\n## Usage\n\n### Basic Runbook Creation\n\nCreate a runbook resource:\n```yaml\n    apiVersion: runbook.runbook.io/v1alpha1\n    kind: Runbook\n    metadata:\n      name: database-alert\n    spec:\n      alertName: \"DatabaseDown\"\n      severity: \"critical\"\n      team: \"database\"\n      content:\n        impact: \"Database is unavailable, affecting all services\"\n        investigation:\n          - description: \"Check database pod status\"\n            command: \"kubectl get pods -l app=database\"\n            expected: \"All pods should be Running\"\n        remediation:\n          - description: \"Restart database service\"\n            command: \"kubectl rollout restart deployment/database\"\n            risk: \"medium\"\n            automated: false\n        prevention: \"Implement database health monitoring\"\n      outputs:\n        - format: \"markdown\"\n          destination: \"/tmp/runbooks\"\n        - format: \"html\"\n          destination: \"/tmp/runbooks/html\"\n```\n### Output Formats\n\nThe operator supports multiple output formats:\n\n- **Markdown**: Standard markdown files for documentation\n- **HTML**: Web-ready HTML with styling\n- **API**: Send to external systems via REST APIs\n\n### Template System\n\nCreate custom templates for different alert types:\n```yaml\n    apiVersion: runbook.runbook.io/v1alpha1\n    kind: RunbookTemplate\n    metadata:\n      name: database-template\n    spec:\n      name: \"database-incidents\"\n      description: \"Template for database-related incidents\"\n      template: |\n        # Database Alert: {{ .Spec.AlertName }}\n        \n        **Severity**: {{ .Spec.Severity }}\n        **Team**: {{ .Spec.Team }}\n        \n        ## Database-Specific Checks\n        - Connection pool status\n        - Replication lag\n        - Query performance\n```\n## Development\n\n### Local Development Setup\n\n1. **Clone and setup:**\n```bash\n       git clone https://github.com/guibes/runbook-operator.git\n       cd runbook-operator\n```\n2. **Install dependencies:**\n```bash\n       # Install Air for hot reload\n       go install github.com/cosmtrek/air@latest\n       \n       # Setup development environment\n       ./scripts/setup-dev.sh\n```\n3. **Start development with hot reload:**\n\n   Terminal 1 - Start the operator:\n```bash\n       air\n```\n   Terminal 2 - Test with samples:\n```bash\n       kubectl apply -f config/samples/runbook_v1alpha1_runbook.yaml\n       kubectl get runbooks\n```\n### Project Structure\n```\n    runbook-operator/\n    ├── api/v1alpha1/           # Custom Resource Definitions\n    ├── internal/controller/    # Controller implementations\n    ├── pkg/\n    │   ├── generator/         # Runbook content generation\n    │   ├── outputs/           # Output format handlers\n    │   ├── validator/         # Runbook validation\n    │   └── templates/         # Template management\n    ├── config/\n    │   ├── crd/              # CRD manifests\n    │   ├── samples/          # Example resources\n    │   └── default/          # Default deployment config\n    └── scripts/              # Development scripts\n```\n### Running Tests\n```bash\n    # Run unit tests\n    make test\n    \n    # Run integration tests\n    make test-integration\n    \n    # Run with coverage\n    make test-coverage\n```\n### Building and Deployment\n```bash\n    # Build locally\n    make build\n    \n    # Build and push Docker image\n    make docker-build docker-push IMG=your-registry/runbook-operator:tag\n    \n    # Deploy to cluster\n    make deploy IMG=your-registry/runbook-operator:tag\n```\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `RECONCILE_INTERVAL` | How often to reconcile resources | `30s` |\n| `OUTPUT_BASE_PATH` | Base path for file outputs | `/tmp/runbooks` |\n| `ENABLE_VALIDATION` | Enable runbook validation | `true` |\n\n### ConfigMap Configuration\n```yaml\n    apiVersion: v1\n    kind: ConfigMap\n    metadata:\n      name: runbook-operator-config\n    data:\n      config.yaml: |\n        generator:\n          defaultTemplate: \"standard-runbook\"\n          outputFormats: [\"markdown\", \"html\"]\n        validation:\n          enabled: true\n          checkLinks: true\n        outputs:\n          markdown:\n            enabled: true\n            basePath: \"/tmp/runbooks\"\n          html:\n            enabled: true\n            basePath: \"/tmp/runbooks/html\"\n```\n## Roadmap\n\n- [ ] Integration with Confluence and Notion\n- [ ] Advanced template engine with conditionals\n- [ ] Runbook execution automation\n- [ ] Metrics and monitoring dashboard\n- [ ] Multi-language support\n- [ ] Plugin architecture for custom outputs\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Process\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Ensure all tests pass: `make test`\n5. Submit a pull request\n\n### Code Standards\n\n- Follow Go conventions and best practices\n- Add tests for new functionality\n- Update documentation for API changes\n- Use conventional commit messages\n\n## Uninstallation\n```bash\n    # Delete sample resources\n    kubectl delete -k config/samples/\n    \n    # Remove the operator\n    make undeploy\n    \n    # Remove CRDs\n    make uninstall\n```\n## License\n\nCopyright 2025 Geovane Guibes.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguibes%2Frunbook-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguibes%2Frunbook-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguibes%2Frunbook-operator/lists"}