Expert guidance for developing with stolostron/kubernetes-dependency-watches, an event-driven Go library for tracking dependencies between Kubernetes objects with caching.
You are an expert in the stolostron/kubernetes-dependency-watches library, an event-driven Go library for tracking dependencies between Kubernetes objects.
This is an event-driven Go library for tracking dependencies between Kubernetes objects. When a Kubernetes object needs to monitor changes to other objects (e.g., a ConfigMap watching a Secret), this library provides an efficient watch mechanism with optional caching. It is designed as an alternative/complement to controller-runtime and can be integrated with controller-runtime as a Channel Source.
**DynamicWatcher** (`client/client.go`): The central interface and implementation
- `watchedToWatchers`: maps watched objects to watchers that care about them
- `watcherToWatches`: maps watcher objects to the objects they watch
- `watches`: maps watched objects to their active API watch requests
**ObjectCache** (`client/cache.go`): Thread-safe caching layer
**ControllerRuntimeSource** (`client/source.go`): Integration adapter
**ObjectIdentifier**: Identifies a Kubernetes object or set of objects
**Watch Lifecycle**:
1. `AddWatcher` or `AddOrUpdateWatcher` creates watches
2. `relayWatchEvents` runs in goroutines, monitoring watch channels
3. On watch events, watchers get added to the reconcile queue
4. Watch automatically restarts if it fails (e.g., resource version expired)
5. `RemoveWatcher` cleans up watches when no longer referenced
**Query Batch Pattern**: For caching use cases
1. `StartQueryBatch` begins a transaction
2. `Get`/`List` calls add watches and return cached objects
3. `EndQueryBatch` removes watches no longer referenced in the batch
When working with this codebase:
1. **Testing**:
- Run all tests: `make test`
- Run with coverage: `make test-coverage`
- Custom test args: `TESTARGS="-v -ginkgo.focus='My Test'" make test`
- Tests use Ginkgo/Gomega with envtest for a real Kubernetes API server
- `ENVTEST_K8S_VERSION` is auto-determined from go.mod (k8s.io/api version)
- See `client_example_test.go` for comprehensive usage examples
2. **Code Quality**:
- Run linters: `make lint`
- Format code: `make fmt`
- Security scan: `make gosec-scan`
3. **Dependencies**:
- Install test dependencies: `make e2e-dependencies`
- Install envtest: `make envtest`
**Watch Restart Behavior** (`client.go:309-422`):
**Concurrency Safety**:
**Error Handling**:
**Standalone Usage**:
```go
dynamicWatcher, _ := client.New(k8sConfig, reconciler, nil)
go dynamicWatcher.Start(ctx)
<-dynamicWatcher.Started()
dynamicWatcher.AddWatcher(watcher, watched)
```
**Controller-Runtime Integration**:
```go
reconciler, sourceChan := client.NewControllerRuntimeSource()
dynamicWatcher, _ := client.New(k8sConfig, reconciler, nil)
go dynamicWatcher.Start(ctx)
ctrl.NewControllerManagedBy(mgr).
For(&MyType{}).
WatchesRawSource(sourceChan).
Complete(myReconciler)
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/kubernetes-dependency-watches/raw