{"id":49052142,"url":"https://github.com/bubustack/kubernetes-impulse","last_synced_at":"2026-04-19T21:01:41.947Z","repository":{"id":352188395,"uuid":"1148069127","full_name":"bubustack/kubernetes-impulse","owner":"bubustack","description":"Kubernetes event Impulse for bobrapet — triggers StoryRuns on pod crashes, deployments, and resource changes.","archived":false,"fork":false,"pushed_at":"2026-04-18T10:02:29.000Z","size":65,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T11:24:01.465Z","etag":null,"topics":["bubustack","events","go","impulse","kubernetes","trigger","watcher"],"latest_commit_sha":null,"homepage":"https://bubustack.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bubustack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","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},"funding":{"github":["bubustack"]}},"created_at":"2026-02-02T14:43:00.000Z","updated_at":"2026-04-18T10:02:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bubustack/kubernetes-impulse","commit_stats":null,"previous_names":["bubustack/kubernetes-impulse"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bubustack/kubernetes-impulse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fkubernetes-impulse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fkubernetes-impulse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fkubernetes-impulse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fkubernetes-impulse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bubustack","download_url":"https://codeload.github.com/bubustack/kubernetes-impulse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bubustack%2Fkubernetes-impulse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32022561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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":["bubustack","events","go","impulse","kubernetes","trigger","watcher"],"created_at":"2026-04-19T21:01:11.638Z","updated_at":"2026-04-19T21:01:41.910Z","avatar_url":"https://github.com/bubustack.png","language":"Go","readme":"# ☸️ Kubernetes Impulse\n\nA BubuStack Impulse that triggers Stories from Kubernetes cluster activity.\n\n## 🌟 Highlights\n\n- **Watch Mode**: React to resource state changes (Add/Update/Delete)\n- **Events Mode**: React to Kubernetes Event objects (warnings, errors)\n- **Flexible Filtering**: By namespace, labels, field selectors, template expressions\n- **Debouncing**: Prevent rapid-fire triggers for the same resource\n- **Event Aggregation**: Batch multiple events before triggering\n\n## 🚀 Quick Start\n\n1. Install the ImpulseTemplate:\n\n```bash\nkubectl apply -f Impulse.yaml\n```\n\n2. Create an Impulse instance (see examples below).\n\n## 🔄 Modes\n\n### Watch Mode\n\nWatches for resource state changes using the Kubernetes Watch API.\n\n```yaml\napiVersion: bubustack.io/v1alpha1\nkind: Impulse\nmetadata:\n  name: pod-crash-watcher\nspec:\n  templateRef:\n    name: kubernetes\n  \n  storyRef:\n    name: pod-crash-analyzer\n  \n  with:\n    mode: watch\n    watch:\n      resources:\n        - apiVersion: v1\n          kind: Pod\n          namespace: production\n          labelSelector: \"tier=backend\"\n      triggers:\n        - Modified\n      filters:\n        condition: 'and (eq .eventType \"Modified\") (eq .object.status.phase \"Failed\")'\n        includeOldObject: true\n        debounceSeconds: 5\n```\n\n**Supported Resources:**\n- Core: Pod, Service, ConfigMap, Secret, Namespace, Node, PersistentVolumeClaim\n- Apps: Deployment, StatefulSet, DaemonSet, ReplicaSet\n- Batch: Job, CronJob\n- Networking: Ingress, NetworkPolicy\n- Custom Resources: Any CRD with apiVersion and kind\n\n### Events Mode\n\nWatches Kubernetes Event objects created by controllers.\n\n```yaml\napiVersion: bubustack.io/v1alpha1\nkind: Impulse\nmetadata:\n  name: cluster-warnings\nspec:\n  templateRef:\n    name: kubernetes\n  \n  storyRef:\n    name: warning-analyzer\n  \n  with:\n    mode: events\n    events:\n      namespaces:\n        - production\n        - staging\n      types:\n        - Warning\n      reasons:\n        - FailedScheduling\n        - Unhealthy\n        - BackOff\n        - FailedMount\n      aggregation:\n        enabled: true\n        windowSeconds: 300\n        minCount: 3\n```\n\n**Common Event Reasons:**\n- `FailedScheduling` - Pod couldn't be scheduled\n- `Unhealthy` - Liveness/readiness probe failed\n- `BackOff` - Container restart backoff\n- `FailedMount` - Volume mount failed\n- `Pulled` - Image pulled successfully\n- `Created` - Container created\n- `Killing` - Container being killed\n- `NodeNotReady` - Node became not ready\n\n## 📥 Story Inputs\n\n### Watch Mode Inputs\n\n```yaml\ninputs:\n  mode: watch\n  eventType: Modified  # Added | Modified | Deleted\n  object:\n    apiVersion: v1\n    kind: Pod\n    metadata:\n      name: my-pod\n      namespace: production\n      labels: {...}\n      annotations: {...}\n    spec: {...}\n    status:\n      phase: Failed\n      containerStatuses:\n        - name: main\n          state:\n            terminated:\n              exitCode: 137\n              reason: OOMKilled\n  oldObject:            # Present when filters.includeOldObject=true and prior state is cached\n    status:\n      phase: Pending\n```\n\n### Events Mode Inputs\n\n```yaml\ninputs:\n  mode: events\n  events:\n    - type: Warning\n      reason: FailedScheduling\n      message: \"0/3 nodes available: insufficient memory\"\n      count: 5\n      firstTimestamp: \"2026-01-20T10:00:00Z\"\n      lastTimestamp: \"2026-01-20T10:05:00Z\"\n      involvedObject:\n        apiVersion: v1\n        kind: Pod\n        name: my-pod\n        namespace: production\n```\n\n## ⚙️ Configuration (`Impulse.spec.with`)\n\n### Watch Configuration\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resources` | array | Resources to watch |\n| `resources[].apiVersion` | string | API version (e.g., v1, apps/v1) |\n| `resources[].kind` | string | Resource kind (e.g., Pod, Deployment) |\n| `resources[].namespace` | string | Namespace (empty = all) |\n| `resources[].labelSelector` | string | Label selector |\n| `resources[].fieldSelector` | string | Field selector |\n| `triggers` | array | Event types: Added, Modified, Deleted |\n| `filters.condition` | string | Template boolean expression; variables: `.object`, `.oldObject`, `.eventType` |\n| `filters.debounceSeconds` | int | Debounce window |\n| `filters.includeOldObject` | bool | Include cached previous state in filter/input as `oldObject` |\n\n### Events Configuration\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `namespaces` | array | Namespaces to watch |\n| `types` | array | Normal, Warning |\n| `reasons` | array | Event reasons to match |\n| `involvedObjectKinds` | array | Filter by object kind |\n| `aggregation.enabled` | bool | Enable aggregation |\n| `aggregation.windowSeconds` | int | Aggregation window |\n| `aggregation.minCount` | int | Minimum events before trigger |\n\n### Session Key Configuration\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `strategy` | string | auto, unique, or custom |\n| `expression` | string | Template expression for custom key (`.object`, `.oldObject`, `.eventType`) |\n\n## 📘 Example Stories\n\n### Pod Crash Notifier\n\n```yaml\napiVersion: bubustack.io/v1alpha1\nkind: Story\nmetadata:\n  name: pod-crash-analyzer\nspec:\n  pattern: batch\n  steps:\n    - name: analyze\n      ref:\n        name: openai-chat\n      with:\n        userPrompt: |\n          A pod crashed in the cluster. Analyze and suggest fixes:\n          \n          Pod: {{ inputs.object.metadata.name }}\n          Namespace: {{ inputs.object.metadata.namespace }}\n          Phase: {{ inputs.object.status.phase }}\n          \n          Container Statuses:\n          {{ inputs.object.status.containerStatuses | tojson }}\n    \n    - name: notify\n      needs: [analyze]\n      ref:\n        name: slack-notifier\n      with:\n        channel: \"#alerts\"\n        text: |\n          🚨 *Pod Crash Alert*\n          \n          *Pod:* {{ inputs.object.metadata.name }}\n          *Namespace:* {{ inputs.object.metadata.namespace }}\n          \n          *AI Analysis:*\n          {{ steps[\"analyze\"].output.text }}\n```\n\n### Deployment Rollout Monitor\n\n```yaml\napiVersion: bubustack.io/v1alpha1\nkind: Impulse\nmetadata:\n  name: deployment-monitor\nspec:\n  templateRef:\n    name: kubernetes\n  storyRef:\n    name: deployment-notifier\n  with:\n    mode: watch\n    watch:\n      resources:\n        - apiVersion: apps/v1\n          kind: Deployment\n      triggers:\n        - Modified\n      filters:\n        condition: |\n          and\n            (eq .object.status.updatedReplicas .object.status.replicas)\n            (eq .object.status.availableReplicas .object.status.replicas)\n```\n\n### Secret Change Audit\n\n```yaml\napiVersion: bubustack.io/v1alpha1\nkind: Impulse\nmetadata:\n  name: secret-audit\nspec:\n  templateRef:\n    name: kubernetes\n  storyRef:\n    name: secret-change-log\n  with:\n    mode: watch\n    watch:\n      resources:\n        - apiVersion: v1\n          kind: Secret\n          labelSelector: \"sensitive=true\"\n      triggers:\n        - Modified\n        - Deleted\n```\n\n## 🔐 RBAC Requirements\n\nThe impulse needs permissions to watch resources:\n\n```yaml\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\n  name: kubernetes-impulse\nrules:\n  # For watch mode\n  - apiGroups: [\"*\"]\n    resources: [\"*\"]\n    verbs: [\"get\", \"list\", \"watch\"]\n  # For events mode\n  - apiGroups: [\"\"]\n    resources: [\"events\"]\n    verbs: [\"get\", \"list\", \"watch\"]\n  # For durable StoryTrigger submission and StoryRun readback\n  - apiGroups: [\"runs.bubustack.io\"]\n    resources: [\"storytriggers\"]\n    verbs: [\"create\", \"get\"]\n  - apiGroups: [\"runs.bubustack.io\"]\n    resources: [\"storyruns\"]\n    verbs: [\"get\"]\n  - apiGroups: [\"runs.bubustack.io\"]\n    resources: [\"storyruns/status\"]\n    verbs: [\"patch\"]\n  - apiGroups: [\"bubustack.io\"]\n    resources: [\"impulses\", \"impulses/status\"]\n    verbs: [\"get\", \"patch\"]\n```\n\n## 🩺 Health Endpoints\n\n- `GET :8080/health` - Liveness probe\n- `GET :8080/ready` - Readiness probe\n\n## 🧪 Local Development\n\n```bash\n# Build binary\nmake build\n\n# Run tests\nmake test\n\n# Build Docker image\nmake docker-build VERSION=v0.1.0\n\n# Push to registry\nmake docker-push VERSION=v0.1.0\n```\n\n\n## 🤝 Community \u0026 Support\n\n- [Contributing](./CONTRIBUTING.md)\n- [Support](./SUPPORT.md)\n- [Security Policy](./SECURITY.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Discord](https://discord.gg/dysrB7D8H6)\n\n## 📄 License\n\nCopyright 2025 BubuStack.\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","funding_links":["https://github.com/sponsors/bubustack"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubustack%2Fkubernetes-impulse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbubustack%2Fkubernetes-impulse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbubustack%2Fkubernetes-impulse/lists"}