raucao
87d4305c0d
One-shot, idempotent helper that prepares an existing (Chef) node for Cinc Workstation management: installs Cinc Client, points /etc/cinc at the existing /etc/chef config, drops the deprecated attribute lists, and pre-seeds the allowed_* attribute lists so the first converge does not filter node attributes (e.g. vm_host). The node can then be converged as usual. Verified against drone-1.
43 lines
3.7 KiB
Markdown
43 lines
3.7 KiB
Markdown
# 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. Nodes run the community **Cinc Client** distribution (the license-free Chef Infra Client) instead of Chef Infra Client, and everything is driven by **Cinc Workstation** (the community fork of Chef Workstation). On-node configuration lives in `/etc/cinc`, and the repo's knife config lives in `.cinc/`.
|
|
|
|
## 📂 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 `.cinc/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.
|
|
* **`.cinc/`**: Local knife configuration (`config.rb`, `encrypted_data_bag_secret`). Untracked; `.cinc/config.rb.example` is the template.
|
|
* **`kitchen.yml` / `.kitchen/`**: Test Kitchen integration suites. They run against Cinc Client via Cinc Workstation's `kitchen-dokken` plugin, so invoke them with `kitchen` (see `README.md`).
|
|
|
|
## 🛠️ 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`
|
|
- To migrate an existing (Chef) node to Cinc Client: `scripts/knife/migrate_node_to_cinc.sh <node>`, then converge as usual.
|
|
|
|
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`. |