chef/AGENTS.md

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/<name> 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.