Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (52 loc) · 3.41 KB

AGENTS.md

File metadata and controls

63 lines (52 loc) · 3.41 KB

AGENTS instructions

For detailed information on source code structure and development guidelines, refer to the project's CONTRIBUTING.md file.

Project Overview

This project is a Kubernetes operator for managing the lifecycle of Flux CD. It provides a declarative API for installing, configuring, and upgrading the Flux distribution. The operator extends Flux with self-service capabilities, deployment windows, and preview environments.

The project is structured as a Go module with the following components:

  • Flux Operator Kubernetes Controller: The main component of the project. It is built using the Kubernetes controller-runtime managing the following CRDs:
    • FluxInstance CRD: Manages the Flux controllers installation and configuration
    • FluxReport CRD: Reflects the state of a Flux installation
    • ResourceSet CRD: Manages groups of Kubernetes and Flux resources based on input matrices
    • ResourceSetInputProvider CRD: Fetches input values from external services (GitHub, GitLab, Azure DevOps, Container Registries)
  • Flux Operator CLI: A command-line interface for interacting with the Flux Operator. It is built using the Cobra library.
  • Flux Operator MCP Server: A server that connects AI assistants to Kubernetes clusters running the operator. It is built using the mcp-go library.
  • Flux Status Page: A web UI for displaying the status of the Flux GitOps pipelines. It is built using Preact, Vite, and Tailwind CSS.

Repository Structure

├── api/            # Go API definitions for Kubernetes CRDs
├── cmd/            # Main entrypoint for the binaries
│   ├── cli/        # Flux Operator CLI
│   ├── mcp/        # Flux Operator MCP Server
│   └── operator/   # Flux Operator Kubernetes Controller
├── config/         # Kubernetes manifests for deploying the operator
├── docs/           # Kubernetes APIs and MCP tools documentation
├── hack/           # Scripts for development, building, and releases
├── internal/       # Internal Go packages
│   ├── controller/ # Controller reconciliation logic
│   └── web/        # Backend for the Flux Status Page
├── test/           # End-to-end tests with Kubernetes Kind
└── web/            # Preact frontend for the Flux Status Page

Rules of Engagement for AI Agents

  • Do not deviate from the established patterns in the codebase
  • New files must have a license header matching existing files
  • All new features must have associated documentation and tests
  • Never run git tag and never push tags
  • Follow the Go code style used in the project
  • Add proper doc comments for new functions and types
  • After modifying a function or type, update its doc comment
  • Add comments for complex logic but don't comment obvious code
  • Read existing tests before writing new ones
  • Run individual tests when debugging, run the full test suite when done
  • Replace interface{} with any type alias
  • Use go doc to read func signatures in external packages

Development Commands for AI Agents

  • Run make generate after modifying types in the api dir
  • Run make fmt lint after completing a task and fix lint errors
  • Run make test to execute all Go tests
  • Run make cli-test for Flux Operator CLI specific tests
  • Run make mcp-test for Flux Operator MCP server specific tests
  • Run make web-test for Flux Status Page frontend tests