From 175a6818480d2da149552e395520d0de0e9e1034 Mon Sep 17 00:00:00 2001 From: Jesse Jaggars Date: Thu, 18 Sep 2025 11:22:24 -0400 Subject: [PATCH 1/2] Add CLAUDE.md documentation Generated using Claude Code automation to enhance AI-assisted development capabilities. --- CLAUDE.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..f10dcc294 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,71 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Essential Commands + +### Development +- `make tools` - Install all required project dependencies to `tmp/bin` +- `make test-unit` - Run unit tests for cmd/ and pkg/ directories +- `make lint` - Run both golang and shell linting +- `make lint-golang` - Run golangci-lint with auto-fix +- `make generate` - Generate CRDs, deepcopy, kustomize configs, and docs + +### Building +- `make operator` - Generate manifests and build operator binary (default target) +- `make build` - Build operator binary to `./tmp/operator` +- `make operator-image` - Build operator container image +- `go run ./cmd/operator/... --zap-devel --zap-log-level=100 --kubeconfig ~/.kube/config` - Run operator locally + +### Testing +- `make test-e2e` - Run end-to-end tests +- `./test/run-e2e.sh` - Run E2E tests against local kind cluster +- `./hack/setup-e2e-env.sh` - Setup local development environment with kind cluster + +### Environment Setup +1. `make tools` - Install project tools +2. `./hack/setup-e2e-env.sh` - Setup complete development environment + +## Architecture Overview + +The Observability Operator is a Kubernetes operator that manages monitoring/alerting stacks through CRDs, built on controller-runtime. + +### Key Components + +**Core APIs** (pkg/apis/): +- `monitoring.rhobs/v1alpha1` - MonitoringStack CRD for complete monitoring stacks +- `observability.rhobs/v1alpha1` - Core observability APIs including OpenTelemetry/tracing +- `uiplugin.rhobs/v1alpha1` - OpenShift console UI plugin integration + +**Controllers** (pkg/controllers/): +- `monitoring/monitoring-stack/` - Manages Prometheus, Alertmanager, and monitoring components +- `monitoring/thanos-querier/` - Handles Thanos querier deployments +- `uiplugin/` - Manages OpenShift console plugins and UI components +- `operator/` - Core operator lifecycle management + +**Key Dependencies**: +- Uses forked prometheus-operator (`github.com/rhobs/obo-prometheus-operator`) for compatibility +- Integrates with OpenShift APIs for console UI plugins +- Built on controller-runtime v0.21.0 + +### Deployment Structure + +- `deploy/crds/` - CRD manifests (common + kubernetes-specific) +- `deploy/dependencies/` - Required dependency resources +- `deploy/operator/` - Operator deployment manifests +- `deploy/olm/` - OLM bundle configuration + +## Development Notes + +- Requires OLM (Operator Lifecycle Manager) for proper operation +- Generate manifests with `make generate` after modifying Go types in `pkg/apis/` +- Use conventional commits for automatic changelog/release management +- The operator can run locally while dependencies (prometheus-operator) run in-cluster + +## Testing Specific Files + +To run tests for a specific package: +```bash +go test ./pkg/controllers/monitoring/monitoring-stack/... +go test ./pkg/controllers/uiplugin/... +``` \ No newline at end of file From 3ae23722e35173ae7f2b6f617caa93416937132a Mon Sep 17 00:00:00 2001 From: Jesse Jaggars Date: Wed, 24 Sep 2025 08:00:27 -0400 Subject: [PATCH 2/2] Fix CLAUDE.md based on reviewer feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address PR review comments: - Replace abstract "go run" instruction with complete 5-step process - Add exact commands for building, deploying, and running operator locally - Remove hardcoded controller-runtime version (v0.21.0) - Clarify that OLM is commonly used but not strictly required - Include proper kubeconfig flag and output redirection in go run command The original single-line go run command failed without prerequisites. Now provides copy-pasteable commands that actually work. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f10dcc294..f7f92a0e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - `make operator` - Generate manifests and build operator binary (default target) - `make build` - Build operator binary to `./tmp/operator` - `make operator-image` - Build operator container image -- `go run ./cmd/operator/... --zap-devel --zap-log-level=100 --kubeconfig ~/.kube/config` - Run operator locally +- Run operator locally (requires prometheus-operator dependencies): + 1. `./hack/setup-e2e-env.sh` - Setup development environment with Kind cluster + 2. Build and push operator images: + ```bash + make operator-image bundle-image operator-push bundle-push \ + IMAGE_BASE="local-registry:30000/observability-operator" \ + VERSION=0.0.0-dev \ + PUSH_OPTIONS=--tls-verify=false + ``` + 3. Deploy operator bundle: + ```bash + ./tmp/bin/operator-sdk run bundle \ + local-registry:30000/observability-operator-bundle:0.0.0-dev \ + --install-mode AllNamespaces \ + --namespace operators --skip-tls + ``` + 4. Scale down cluster operator: `kubectl scale --replicas=0 -n operators deployment/observability-operator` + 5. Run locally: `go run ./cmd/operator/... --zap-devel --zap-log-level=100 --kubeconfig ~/.kube/config 2>&1 | tee tmp/operator.log` ### Testing - `make test-e2e` - Run end-to-end tests @@ -46,7 +63,7 @@ The Observability Operator is a Kubernetes operator that manages monitoring/aler **Key Dependencies**: - Uses forked prometheus-operator (`github.com/rhobs/obo-prometheus-operator`) for compatibility - Integrates with OpenShift APIs for console UI plugins -- Built on controller-runtime v0.21.0 +- Built on controller-runtime ### Deployment Structure @@ -57,7 +74,7 @@ The Observability Operator is a Kubernetes operator that manages monitoring/aler ## Development Notes -- Requires OLM (Operator Lifecycle Manager) for proper operation +- Commonly deployed using OLM (Operator Lifecycle Manager), though manual installation is also supported - Generate manifests with `make generate` after modifying Go types in `pkg/apis/` - Use conventional commits for automatic changelog/release management - The operator can run locally while dependencies (prometheus-operator) run in-cluster