Skip to content

AGENTS.md

Latest commit

 

History

History
470 lines (330 loc) · 17 KB

AGENTS.md

File metadata and controls

470 lines (330 loc) · 17 KB
Raw

OpenShift Monitoring Plugin - AI Agent Guide

Quick Start (30-second overview)

  • What: Dual frontend plugins for OpenShift observability (monitoring-plugin + monitoring-console-plugin)
  • Purpose: Alerts, Metrics, Targets, Dashboards + Perses, Incidents, ACM integration
  • Tech Stack: React + TypeScript + Webpack + i18next + Go
  • Key Files: config/*.patch.json, web/src/features/, web/src/shared/

Common Tasks & Workflows

Adding a New Feature

  1. Check if it belongs in monitoring-plugin (core) or monitoring-console-plugin (extended)
  2. Add or update the relevant patch file in config/ (e.g. config/alerting.patch.json)
  3. Add React components in web/src/features/ (feature-specific) or web/src/shared/ (shared)
  4. Add translations in public/locales/
  5. Test with make lint-frontend && make test-backend

Debugging Issues

  • Build failures: Check Makefile targets
  • Console integration: Verify the relevant config/*.patch.json patch file
  • Plugin loading: Check OpenShift Console logs
  • Perses dashboards: Debug at web/src/features/perses-dashboards/

Development Setup

Development Context

When working on Alerts:

  • Files: web/src/features/alerts/
  • Integration: Alertmanager API
  • Testing: Cypress tests in web/cypress/

When working on Dashboards:

When working on ACM:

  • Multi-cluster observability
  • Hub cluster aggregation
  • Thanos/Alertmanager integration

When working on Incidents Cypress tests:

Before editing incident specs, the incidents page object, incident fixtures, or their schema/mock support code, read .agents/references/incidents-testing-guidelines.md. This applies to:

  • web/cypress/e2e/incidents/
  • web/cypress/views/incidents-page.ts
  • web/cypress/fixtures/incident-scenarios/
  • web/cypress/support/incidents_prometheus_query_mocks/

Important Decision Points

Choosing Between Plugins:

  • monitoring-plugin: Core observability (always available)
  • monitoring-console-plugin: Optional features (COO required)

Adding Dependencies:

  • Check compatibility with OpenShift Console versions
  • Verify i18next translation support
  • Consider CMO vs COO deployment differences

Frontend Source Layout

The web/src/ directory is organized into two top-level areas:

  • web/src/features/ — Feature-specific code, one subdirectory per feature. Each feature directory contains sub-folders as needed: components/, pages/, hooks/, utils/, types/, assets/.
  • web/src/shared/ — Code used by more than one feature, organized by kind.
Feature Directory
Alerting (alerts, silences, alert rules) features/alerts/
Incidents features/incidents/
Legacy Dashboards features/legacy-dashboards/
Metrics / PromQL features/metrics/
Perses Dashboards features/perses-dashboards/
Targets features/targets/
Shared Directory Contents
shared/components/ Reusable UI components (labels.tsx, format.tsx, query-browser/)
shared/hooks/ Shared React hooks (useAlerts.ts, usePerspective.tsx)
shared/store/ Redux store, actions, reducers, thunks, alert fetching
shared/contexts/ React contexts (MonitoringContext.tsx)
shared/constants/ Shared constants (data-test.ts, query-params.ts)
shared/types/ Shared TypeScript types (types.ts)
shared/utils/ Shared pure utility functions (utils.ts)
shared/assets/ Static assets such as fonts (codicon.ttf)
shared/console/ Vendored/adapted OpenShift Console internals

Placement rules:

  • If a file is only used within one feature, it belongs in that feature's directory.
  • If a component or utility is only used by a single page, co-locate it inside that page's own subdirectory (e.g. features/alerts/pages/alerts-page/AggregateAlertTableRow.tsx).
  • If a file is used across multiple features, it belongs in shared/.

Note: web/src/components/ no longer exists. Do not create files there.

External Dependencies & Operators

System Repository Purpose
CMO https://github.com/openshift/cluster-monitoring-operator Manages monitoring-plugin
COO https://github.com/rhobs/observability-operator Manages monitoring-console-plugin
Perses https://github.com/perses/perses Dashboard engine
Console SDK https://github.com/openshift/console Plugin framework

Technical Documentation

Console Plugin Framework

Operator Integration

  • CMO (monitoring-plugin): Integrated with cluster monitoring stack
  • COO (monitoring-console-plugin): Optional operator for extended features
  • UIPlugin CR example:
apiVersion: observability.openshift.io/v1alpha1
kind: UIPlugin
metadata:
  name: monitoring
spec:
  type: Monitoring
  monitoring:
    acm:
      enabled: true
      alertmanager:
        url: "https://alertmanager.open-cluster-management-observability.svc:9095"
      thanosQuerier:
        url: "https://rbac-query-proxy.open-cluster-management-observability.svc:8443"
    perses:
      enabled: true
    clusterHealthAnalyzer:
      enabled: true

Perses Integration Details

ACM Observability

  • Multi-cluster monitoring: Centralized observability across managed clusters
  • Components: Hub cluster Thanos, Grafana, Alertmanager + endpoint operators
  • Integration: COO provides unified alerting UI for ACM environments
  • Features: Cross-cluster silences, cluster-labeled alerts, centralized metrics

Release & Testing

Before submitting a PR run the following and address any errors:

make lint-frontend
make lint-backend
make test-translations
make test-backend
make test-frontend
# future slash command for test execution

PR Requirements:

  • Title format: [JIRA_ISSUE]: Description
  • Testing: All linting and tests must pass
  • Translations: Ensure i18next keys are properly added

Unit Testing

Overview

The Monitoring Plugin uses a dual testing approach for unit tests:

  • Frontend Unit Tests: Vitest + TypeScript for React components and utilities
  • Backend Unit Tests: Go's built-in testing framework for server functionality

Unit tests focus on isolated function testing and run quickly in CI/CD pipelines, while E2E tests (Cypress) validate full user workflows.

Test File Structure

Frontend Tests:

  • Location: Co-located with source files in web/src/
  • Naming: *.spec.ts (e.g., format.spec.ts, utils.spec.ts)
  • Framework: Vitest 4.1.11
  • Configuration: web/vitest.config.mts

Backend Tests:

  • Location: Co-located with source files in pkg/ (sub-packages: pkg/server/, pkg/monitoring/)
  • Naming: *_test.go (e.g., server_test.go)
  • Framework: Go testing package + testify/require
  • Configuration: Standard Go test conventions

Running Unit Tests

# Run all tests (backend + frontend)
make test-backend
make test-frontend

# Run individually from web directory
cd web && npm run test:unit

# Run with coverage
cd web && npm run test:unit:coverage

# Run Go tests directly
go test ./pkg/... -v

When to Create Unit Tests

Create unit tests when:

  1. Adding utility functions: Pure functions, formatters, data transformations
  2. Adding business logic: Data processing, calculations, validations
  3. Fixing bugs: Regression tests to prevent bug recurrence
  4. Adding API handlers: Backend endpoint logic (Go tests)

Key Testing Libraries

Frontend:

  • vitest (v4.1.11) - Test runner and assertions
  • @vitest/coverage-v8 (v4.1.11) - Code coverage (v8 provider)

Backend:

  • testing (stdlib) - Go testing framework
  • github.com/stretchr/testify (v1.9.0) - Assertions and test utilities

Frontend Unit Testing Structure

Testing Framework & Configuration Test Framework: Vitest Configuration File: web/vitest.config.mts

Test File Location & Naming Convention Pattern: *.spec.ts files co-located with source code

Test Coverage Areas

  • Edge cases (null, undefined, empty values)
  • Normal behavior and expected outputs
  • Boundary conditions
  • Complex scenarios and integration
  • Data transformations and formatting

Backend Unit Testing Structure

Testing Framework & Configuration Test Framework: Go's built-in testing package Assertion Library: github.com/stretchr/testify v1.9.0

Test File Location & Naming Convention Pattern: *_test.go files in the same directory as source code

Test Helper Functions

  • startTestServer() - Starts server for testing
  • prepareServerAssets() - Sets up test environment
  • generateCertificate() - Creates TLS certificates for tests
  • checkHTTPReady() - Waits for server to be ready
  • getRequestResults() - Makes HTTP requests

Test Coverage Areas

  • HTTP server functionality
  • HTTPS/TLS configuration
  • Certificate handling
  • Security settings (TLS versions, cipher suites)
  • Endpoint availability

Cypress E2E Testing

Overview

The Monitoring Plugin uses Cypress for comprehensive End-to-End (E2E) testing to ensure functionality across both the core monitoring-plugin (managed by CMO) and the monitoring-console-plugin (managed by COO). Our test suite covers test scenarios including alerts, metrics, dashboards, and integration with Virtualization and Fleet Management (ACM).

Key Testing Documentation:

  • Setup & Configuration: web/cypress/README.md - Environment variables, installation, troubleshooting
  • Testing Guide: web/cypress/CYPRESS_TESTING_GUIDE.md - Test architecture, creating tests, workflows
  • Test Catalog: web/cypress/E2E_TEST_SCENARIOS.md - Complete list of all test scenarios

When to Create New Cypress Tests

You should create new Cypress tests when:

  1. Adding New Features: Any new UI feature requires corresponding E2E tests
  2. Fixing Bugs: Bug fixes should include tests to prevent regression
  3. Modifying Existing Features: Changes to existing functionality require test updates

Quick Test Commands

cd web/cypress

# Run all regression tests
npm run cypress:run --spec "cypress/e2e/**/regression/**"

# Run BVT (Build Verification Tests)
npm run cypress:run --spec "cypress/e2e/monitoring/00.bvt_admin.cy.ts"

# Run COO tests
npm run cypress:run --spec "cypress/e2e/coo/*.cy.ts"

# Interactive mode
npm run cypress:open

For detailed testing instructions, see web/cypress/CYPRESS_TESTING_GUIDE.md

Vitest Browser Component Testing

Overview

Vitest Browser Mode mounts individual React components in Playwright Chromium without a cluster. Use Jest-style Vitest assertions and vitest-browser-react rendering.

  • Test location: Co-located *.browser.spec.tsx files in web/src/
  • Support file: web/vitest.browser.setup.ts
  • Config: web/vitest.browser.config.mts

When to Create Component Tests

  • Testing a component's rendering logic (conditional display, empty states)
  • Verifying props are handled correctly
  • Validating user interactions within a single component
  • When E2E tests would be overkill for the behavior under test

Quick Test Commands

cd web

npx playwright install chromium

# Headless mode - all component tests
npm run test:component

# Run a single component test file
npm run test:component -- Labels.browser.spec.tsx

Writing a Component Test

Component test files use .browser.spec.tsx and are co-located with the source:

import { render } from 'vitest-browser-react';

import { MyComponent } from '@/shared/components/MyComponent';

describe('MyComponent', () => {
  it('renders correctly', async () => {
    const screen = await render(<MyComponent prop="value" />);
    await expect.element(screen.getByText('expected text')).toBeVisible();
  });
});

Release Pipeline:

  • Konflux: Handles CI/CD and release automation
  • CMO releases: Follow OpenShift release cycles
  • COO releases: Independent release schedule

Skills

Reusable workflows live under .agents/skills/. Invoke them with $skill-name in Codex or /skill-name in Claude Code and Cursor. If a client does not discover Agent Skills, ask it to read the corresponding .agents/skills/<name>/SKILL.md explicitly.

Skill Purpose
backport Backport a commit with release-branch adaptations.
build-images Build both plugin development images with a unique tag.
run-perses-dev Start the integrated plugin/Perses tmux environment.
cypress-setup Install and configure the Cypress environment.
cypress-run Select and run Cypress tests.
generate-incident-fixture Create a schema-valid incident fixture.
validate-incident-fixtures Validate one or all incident fixtures.
fixture-schema-reference Explain the incident fixture schema.
generate-regression-test Generate an Incidents regression test from documented flows.
refactor-regression-test Refactor an existing Incidents regression test.

Feature Backporting

For backporting features from main to release branches (for example, release-4.x or release-coo-x.y), invoke the shared backport skill:

# Codex
$backport release-4.18 [commit-hash]

# Claude Code or Cursor
/backport release-coo-0.4 [commit-hash]

The canonical workflow is .agents/skills/backport/SKILL.md and handles:

  • PatternFly v6 → v5 component transformations
  • React Router v6 → v5 hook adaptations
  • Console SDK API compatibility
  • Dependency version differences between branches
  • Project structure differences (web/ vs root for older releases)

Security & RBAC

Plugin Security Model:

  • Inherits OpenShift Console RBAC
  • Respects cluster monitoring permissions
  • ACM integration requires appropriate hub cluster access

Development Security:

  • No credentials in code
  • Use cluster service accounts
  • Follow OpenShift security guidelines

Getting Help

Topic Channel/Resource
Console Plugins OpenShift Console SDK documentation
Perses Slack: Cloud Native Computing Foundation >> #perses-dev
COO Slack: Internal Red Hat >> #forum-cluster-observability-operator

Additional Resources

Development Tools & Scripts:

Code Style & Standards:

This guide is optimized for AI agents and developers. For detailed setup instructions, also refer to README.md and Makefile.