Skip to content

AGENTS.md

Latest commit

 

History

History
47 lines (34 loc) · 3.38 KB

AGENTS.md

File metadata and controls

47 lines (34 loc) · 3.38 KB
Raw

AGENTS.md

Guidance for AI coding agents working in this repository. Human contributors should also read docs/contributing.md, docs/development.md, and docs/testing.md, which are the source of truth.

Project summary

Config Sync synchronizes configurations and policies from a source of truth (Git repository, OCI image, or Helm chart) to a Kubernetes cluster, ensuring consistency at scale. It simplifies and automates configuration management across single or multi-cluster environments, managing both cluster-scoped and namespace-scoped resources.

Key Technologies & Architecture:

  • Language & Frameworks: Go, Kubernetes, Kubebuilder / Controller Runtime, Kustomize.
  • Core Custom Resources: RootSync (cluster-scoped synchronization) and RepoSync (namespace-scoped synchronization).
  • Reconciler Manager: Controller component that manages the lifecycle of individual reconciler deployments.
  • Reconcilers: Specialized controllers spawned for each sync target that watch the upstream source and apply manifests to the cluster.
  • Admission Webhook: Validates configuration and state changes for Config Sync custom resources.
  • Nomos CLI: Command-line interface for inspecting status, troubleshooting, and interacting with Config Sync deployments.

Repository layout

Path What lives there
cmd/ Main entrypoints for controllers (reconciler-manager, reconciler, admission-webhook) and the nomos CLI.
pkg/ Core implementation logic: reconcilers, git/OCI sync logic, manifest parsers, validation logic, and webhook handlers.
manifests/ Base Kubernetes manifests and Kustomize configurations used to deploy Config Sync components.
e2e/ End-to-end test framework and test suites (Go-driven, runnable against kind or GKE).
docs/ Documentation for usage, installation, contributing, development, and testing.
examples/ Sample Git repositories and configurations used for tutorials and verification.
scripts/ Shell scripts for CI, verification, and auxiliary build tasks.
build/ Build setups, container entrypoints, base Dockerfiles, and build dependencies.

When in doubt about ownership or review requirements, check the nearest OWNERS file.

Build, test, lint

All primary build and testing workflows run through the Makefile. Prefer using make targets over invoking native tools directly to maintain consistency with CI.

  • make build-cli — Compiles the nomos CLI binary.
  • make build-manifests — Generates deployment manifests into .output/staging/oss.
  • make build-images — Builds required Docker container images for Config Sync controllers.
  • make config-sync-manifest — Builds images and manifests from source in a single step.
  • make test — Runs fast Go unit tests.
  • make test-e2e-kind — Runs end-to-end validation against a local kind cluster (requires pre-installing kind via make install-kind).

For detailed testing parameters (including running targeted E2E test regexes or reusing test cluster environments), consult docs/testing.md.

Agent Skills

Shared agent skills and custom automations for working in this repository should be organized within an .agents/ directory following emerging repository standards.