From e82ad98adc20f88d2ce47d2df2c744e182182bf8 Mon Sep 17 00:00:00 2001 From: Hongyi Wu Date: Fri, 15 May 2026 00:19:36 +0000 Subject: [PATCH] docs: rename GEMINI.md to AGENTS.md with updated guidelines --- AGENTS.md | 47 ++++++++++++++++++++++++ GEMINI.md | 107 ------------------------------------------------------ 2 files changed, 47 insertions(+), 107 deletions(-) create mode 100644 AGENTS.md delete mode 100644 GEMINI.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..e8d6522252 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. Human contributors should also read [docs/contributing.md](docs/contributing.md), [docs/development.md](docs/development.md), and [docs/testing.md](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/](cmd/) | Main entrypoints for controllers (`reconciler-manager`, `reconciler`, `admission-webhook`) and the `nomos` CLI. | +| [pkg/](pkg/) | Core implementation logic: reconcilers, git/OCI sync logic, manifest parsers, validation logic, and webhook handlers. | +| [manifests/](manifests/) | Base Kubernetes manifests and Kustomize configurations used to deploy Config Sync components. | +| [e2e/](e2e/) | End-to-end test framework and test suites (Go-driven, runnable against kind or GKE). | +| [docs/](docs/) | Documentation for usage, installation, contributing, development, and testing. | +| [examples/](examples/) | Sample Git repositories and configurations used for tutorials and verification. | +| [scripts/](scripts/) | Shell scripts for CI, verification, and auxiliary build tasks. | +| [build/](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](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](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. \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 99891b31be..0000000000 --- a/GEMINI.md +++ /dev/null @@ -1,107 +0,0 @@ -# Config Sync GEMINI.md - -## Project Overview - -This directory contains the source code for Config Sync, a tool designed to enable cluster operators and platform administrators to deploy consistent configurations and policies across multiple Kubernetes clusters. It is part of Google Kubernetes Engine (GKE) but can also be installed as open source. - -Config Sync synchronizes configurations from a Git repository (or OCI images, Helm charts) to a Kubernetes cluster. It manages both cluster-scoped and namespace-scoped resources. - -**Key Technologies:** - -* **Go:** The primary programming language. -* **Kubernetes:** The target platform for configuration deployment. -* **Kubebuilder/Controller Runtime:** Framework for building Kubernetes controllers. -* **Kustomize:** Used for Kubernetes manifest management. -* **Docker:** Used for packaging and running components. -* **Make:** Used as the primary build and task runner. - -**Architecture:** - -Config Sync typically runs as a set of controllers within a Kubernetes cluster. Key components include: - -* **Reconciler Manager:** Manages the lifecycle of reconcilers. -* **Reconcilers:** Separate controllers for root-sync (cluster-scoped) and repo-sync (namespace-scoped) that watch the source (e.g., Git) and apply changes to the cluster. -* **Admission Webhook:** Provides validation for Config Sync CRDs. -* **Nomos CLI:** A command-line tool for interacting with Config Sync, checking status, and troubleshooting. - -Configurations are declared using custom resources like `RootSync` and `RepoSync`. - -## Building and Running - -**Prerequisites:** - -* Go (version specified in `go.mod`) -* Git -* Make -* Docker -* gcloud CLI -* gsutil - -**Common Commands (from Makefile):** - -* **Build everything and generate manifests:** - ```bash - make config-sync-manifest - ``` - Artifacts are placed in `.output/staging/oss`. - -* **Build Docker images:** - ```bash - make build-images - ``` - -* **Push Docker images (defaults to GCR in current `gcloud` project):** - ```bash - make push-images - ``` - (Variables like `REGISTRY` and `IMAGE_TAG` can be overridden). - -* **Build the `nomos` CLI:** - ```bash - make build-cli - ``` - Binary will be in `.output/go/bin/linux_amd64/nomos`. - -* **Run all tests:** - ```bash - make test - ``` - -* **Run unit tests:** - ```bash - make test-unit - ``` - -* **Run end-to-end tests:** - ```bash - make test-e2e - ``` - (Requires a Kubernetes cluster, often set up using `kind`). - -* **Deploy to current `kubectl` context:** - ```bash - # Build and deploy - make run-oss - - # Apply from existing artifacts - kubectl apply -f .output/staging/oss - ``` - -* **Format Go code:** - ```bash - make fmt-go - ``` - -* **Clean build artifacts:** - ```bash - make clean - ``` - -## Development Conventions - -* **Code Style:** Standard Go formatting enforced by `gofmt` and `goimports` (use `make fmt-go`). Linting is done with `golangci-lint` (config in `.golangci.yaml`, run via `make lint-go`). -* **Licensing:** Apache 2.0. License headers are checked and added using `addlicense` (run via `make license-headers` or `make lint-license-headers`). -* **Dependencies:** Managed with Go Modules (`go.mod` and `go.sum`). Vendored dependencies are in the `vendor` directory. -* **Testing:** Unit tests are co-located with the code in `_test.go` files. End-to-end tests are in the `e2e` directory. -* **Build Environment:** Many `make` targets run inside a Docker container defined by `build/buildenv` to ensure a consistent environment. -* **Manifests:** Base manifests are in the `manifests` directory, often processed with Kustomize.