From 41e6b29b970bcbbedc1ed3b8b081a34c5c83334d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A2u=20Cao?= Date: Sat, 11 Apr 2026 15:36:54 +0400 Subject: [PATCH] Add AGENTS.md --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a9d2989 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md + +Welcome, AI Agent! This file contains essential context and rules for interacting with the Kosmos Chef repository. Read this carefully before planning or executing any changes. + +## 🏢 Project Overview +This repository contains the infrastructure automation code used by Kosmos to provision and configure bare metal servers (KVM hosts) and Ubuntu virtual machines (KVM guests). + +We use **Chef Infra**, managed locally via **Knife Zero** (agentless Chef), and **Berkshelf** for dependency management. + +## 📂 Directory Structure & Rules + +* **`site-cookbooks/`**: 🟢 **EDITABLE.** This directory contains all custom, internal cookbooks written specifically for Kosmos services (e.g., `kosmos-postgresql`, `kosmos_gitea`, `kosmos-mastodon`). *Active development happens here.* +* **`cookbooks/`**: 🔴 **DO NOT EDIT.** This directory contains third-party/community cookbooks that are vendored. These are managed by Berkshelf. Modifying them directly will result in lost changes. +* **`roles/`**: 🟢 **EDITABLE.** Contains Chef roles written in Ruby (e.g., `base.rb`, `kvm_guest.rb`, `postgresql_primary.rb`). These define run-lists and role-specific default attributes for servers. +* **`environments/`**: Contains Chef environment definitions (like `production.rb`). +* **`data_bags/`**: Contains data bag configurations, often encrypted. Be cautious and do not expose secrets. (Note: Agents should not manage data bag secrets directly unless provided the `.chef/encrypted_data_bag_secret`). +* **`nodes/`**: Contains JSON state files for bootstrapped nodes. *Agents typically do not edit these directly unless cleaning up a deleted node.* +* **`Berksfile`**: Defines community cookbook dependencies. +* **`Vagrantfile` / `.kitchen/`**: Used for local virtualization and integration testing. + +## 🛠️ Tooling & Workflows + +1. **Dependency Management (Berkshelf)** + If a new community cookbook is required: + - Add it to the `Berksfile` at the root. + - Instruct the user to run `berks install` and `berks vendor cookbooks/ --delete` (or run it via the `bash` tool if permitted). + +2. **Provisioning (Knife Zero)** + - Bootstrapping and converging nodes is done using `knife zero`. + - *Example:* `knife zero converge name:server-name.kosmos.org` + +3. **Code Style & Conventions** + - Chef recipes, resources, and roles are written in **Ruby**. + - Follow standard Chef and Ruby (RuboCop) idioms. Look at neighboring files in `site-cookbooks/` or `roles/` to match formatting and naming conventions. + +## 🚨 Core Directives for AI Agents + +1. **Infrastructure as Code**: Manual server configurations are highly discouraged. All changes must be codified in a cookbook or role. +2. **Test Safety Nets**: Look for `.kitchen.yml` within specific `site-cookbooks/` to understand if local integration tests are available. +3. **No Assumptions**: Do not assume standard test commands. Check `README.md` and repository config files first. +4. **Secret Handling**: Avoid hardcoding passwords or API keys in recipes or roles. Assume sensitive information is managed via Chef `data_bags`. \ No newline at end of file