Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (60 loc) · 4.43 KB

AGENTS.md

File metadata and controls

87 lines (60 loc) · 4.43 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Operator Does

configure-alertmanager-operator dynamically manages Alertmanager configurations on managed OpenShift (OSD/ROSA) clusters. It watches secrets and configmaps in openshift-monitoring for GoAlert, PagerDuty, and Dead Man's Snitch credentials, then assembles and validates a complete Alertmanager config before writing it to the alertmanager-main secret. Invalid configs are never written -- the operator preserves the last known good state.

Build Commands

make                    # lint + test + build (the default target)
make go-build           # compile the operator binary
make go-test            # unit tests (uses envtest for kubebuilder assets)
make go-check           # golangci-lint (config: boilerplate/openshift/golang-osd-operator/golangci.yml)
make coverage           # code coverage report
make generate           # run code generation (mockgen, kubebuilder)
make validate           # ensure generated/boilerplate code is up to date
make docker-build       # build container image
make boilerplate-update # pull latest boilerplate templates

Running a Single Test

# Run one test by name (regex match)
TESTOPTS="-run TestFunctionName" make go-test

# Or directly with go test (requires envtest assets set up):
go test ./controllers -run TestFunctionName -v

Running Tests in a Container

make container-test     # unit tests in container
make container-all      # lint + generate + coverage + test + validate in container

Architecture

Reconciliation Flow (controllers/secret_controller.go)

The SecretReconciler is the sole controller. It watches:

  • Secrets: goalert-secret, pd-secret, dms-secret, alertmanager-main in openshift-monitoring
  • ConfigMaps: ocm-agent, managed-namespaces, ocp-namespaces in openshift-monitoring
  • ClusterVersion: version (cluster-scoped, for cluster type detection)

On any change to these resources, it:

  1. Detects cluster type (management vs. worker via ext-hypershift.openshift.io/cluster-type infrastructure label)
  2. Checks cluster readiness (osd-cluster-ready Job, with configurable MAX_CLUSTER_AGE_MINUTES)
  3. Extracts receiver URLs/keys from secrets
  4. Builds Alertmanager config with routing rules (namespace-based, severity-based, alert name regex)
  5. Validates using github.com/prometheus/alertmanager/config.Load()
  6. Writes validated config to alertmanager-main secret

Key Packages

  • controllers/ -- Reconciler logic and tests (~1,400 lines controller, ~2,700 lines tests)
  • pkg/types/ -- Custom Alertmanager config structs with YAML marshaling (mirrors upstream Prometheus types)
  • pkg/metrics/ -- 10 Prometheus gauges tracking secret/configmap presence and config validation state
  • pkg/readiness/ -- Cluster readiness check with mockgen-generated mocks
  • config/ -- Operator constants (OperatorName, OperatorNamespace) and FedRAMP detection

Namespace Scoping (main.go)

The manager caches only openshift-monitoring namespace resources to reduce memory ~90%. Cluster-scoped resources (ClusterVersion, Proxy, Infrastructure) are explicitly added to the cache.

Environment Variables

  • FEDRAMP -- Enable FedRAMP-specific behavior
  • SKIP_LEADER_ELECTION -- Skip leader election (for local testing with read-only kubeconfig)
  • MAX_CLUSTER_AGE_MINUTES -- How long to suppress PD alerts during cluster provisioning (default: 120)

Testing

Tests use standard Go testing with controller-runtime/pkg/client/fake for the Kubernetes client. Mocks are generated with go.uber.org/mock/gomock (see //go:generate mockgen in pkg/readiness/cluster_ready.go). Run make generate to regenerate mocks after interface changes.

E2E tests live in test/e2e/ and are gated behind the osde2e build tag -- they are excluded from make go-test.

Boilerplate

This repo consumes openshift/golang-osd-operator and openshift/golang-osd-e2e conventions from openshift/boilerplate. Files marked GENERATED BY BOILERPLATE. DO NOT EDIT. will be overwritten on make boilerplate-update. Project-specific values (operator name, namespace, image) are extracted from config/config.go by boilerplate/openshift/golang-osd-operator/project.mk.

Local Testing

See LOCAL_TESTING.md for running the operator locally against a remote cluster with a read-only ServiceAccount.