From c8e12ac4cec3f2f64fa8587ce48a515856c9ebe8 Mon Sep 17 00:00:00 2001 From: Leos Stejskal Date: Thu, 23 Apr 2026 08:40:01 +0200 Subject: [PATCH 1/2] Initialize files & dirs for Agentic AI development - AGENTS.md - .agents dirs - settings example file - links for Claude files --- .agents/agents/.gitkeep | 0 .agents/rules/.gitkeep | 0 .agents/settings.json.EXAMPLE | 13 +++ .agents/skills/.gitkeep | 0 .claude | 1 + .gitignore | 4 + AGENTS.md | 193 ++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 8 files changed, 212 insertions(+) create mode 100644 .agents/agents/.gitkeep create mode 100644 .agents/rules/.gitkeep create mode 100644 .agents/settings.json.EXAMPLE create mode 100644 .agents/skills/.gitkeep create mode 120000 .claude create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.agents/agents/.gitkeep b/.agents/agents/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.agents/rules/.gitkeep b/.agents/rules/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.agents/settings.json.EXAMPLE b/.agents/settings.json.EXAMPLE new file mode 100644 index 000000000..866fd757e --- /dev/null +++ b/.agents/settings.json.EXAMPLE @@ -0,0 +1,13 @@ +{ + "permissions": { + "allow": [ + "Bash(obsah)", + "Bash(find)", + "Bash(grep)", + "Bash(ansible-lint)", + "Bash(pytest)", + "Bash(make)", + "Bash(git diff)", + ] + } +} diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.claude b/.claude new file mode 120000 index 000000000..c0ca46856 --- /dev/null +++ b/.claude @@ -0,0 +1 @@ +.agents \ No newline at end of file diff --git a/.gitignore b/.gitignore index b40884fe1..c569a7377 100644 --- a/.gitignore +++ b/.gitignore @@ -47,3 +47,7 @@ foremanctl-*.tar.gz .var .tmp + +# AI +.agents/settings.local.json +.agents/settings.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..4b086d6f5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,193 @@ +# AI Development Guide + +This file provides guidance to AI tools and agents when working with code in this repository. It is intentionally tool-agnostic -- it works with Claude Code, Cursor, GitHub Copilot, and any other AI assistant. + +## Project Overview + +foremanctl is a deployment tool for Foreman and Katello using Podman quadlets and Ansible. It provides a command-line interface built on top of `obsah` (an Ansible wrapper) for managing containerized Foreman deployments. + +The repository contains two main wrapper scripts: + +- `foremanctl` - Production deployment and management +- `forge` - Development environment management and testing + +Both scripts wrap `obsah`, which provides a structured way to run Ansible playbooks with parameter validation and persistence. + +## AI Specifications + +Detailed agent, command, rule, and skill specifications live under `.agents/`. These are tool-agnostic Markdown files with YAML frontmatter that any AI tool can parse or ignore. + +### Directory Structure + +```shell +.agents/ + agents/ # Specialist agent personas with defined scopes + rules/ # Coding standards and constraints (all agents must follow) + skills/ # Domain knowledge references +``` + +### Workflow Chains + +These pipelines connect skills into end-to-end workflows. Individual skill files don't describe these relationships. + +TODO + +## Development Setup + +See [Development Guide](DEVELOPMENT.md) for the instructions. + +This creates a virtualenv and installs all dependencies including ansible-core 2.16+. + +## Common Commands + +### Development Environment + +```bash +# Start development VM +./forge vms start + +# Deploy Foreman in development mode +./foremanctl deploy --foreman-initial-admin-password=changeme --tuning development + +# Stop development VM +./forge vms stop +``` + +### Testing + +```bash +# Run all tests (requires a deployed environment) +./forge test + +# Run smoker tests +./forge smoker + +# Run specific test file +python -m pytest tests/foreman_test.py -vv + +# Run tests with specific configuration +python -m pytest --certificate-source=installer --database-mode=external +``` + +Tests use pytest with testinfra and connect to VMs via SSH. The test playbook (`development/playbooks/test/test.yaml`) generates `.tmp/ssh-config` from the Ansible inventory before running pytest. + +See [docs/developer/testing.md](docs/developer/testing.md) for the full testing guide. + +### Linting + +```bash +# Run ansible-lint (configured in .ansible-lint) +cd src; ansible-lint +cd development; ansible-lint +``` + +## Architecture + +### obsah Integration + +Both `foremanctl` and `forge` are bash wrappers that set environment variables and execute `obsah`. + +The key difference: + +- `foremanctl`: Uses `src/` as data directory, targets production deployment +- `forge`: Uses `development/` as data directory, includes development-specific playbooks + +obsah playbooks are discovered via `metadata.obsah.yaml` files which define: + +- Command-line parameters and validation +- Help text +- Variable definitions with choices and types +- Included sub-playbooks + +See [docs/developer/playbooks-and-roles.md](docs/developer/playbooks-and-roles.md) for the full playbook and role guide. + +### Playbook Organization + +**Production playbooks** (`src/playbooks/`): + +- `deploy/` - Main deployment playbook +- `checks/` - System requirement checks +- `features/` - Feature management +- `pull-images/` - Container image pulling +- Prefixed with `_` - Internal/included playbooks (e.g., `_certificate_source`, `_database_mode`, `_tuning`, `_flavor_features`) + +**Development playbooks** (`development/playbooks/`): + +- `vms/` - VM lifecycle management +- `test/` - Test execution +- `smoker/` - Smoker test execution +- `deploy-dev/` - Development deployment variations +- `security/`, `sos/`, `lock/` - Utilities + +### Roles + +Roles in `src/roles/` correspond to services and deployment stages: + +- Service roles: `foreman`, `pulp`, `candlepin`, `postgresql`, `redis`, `httpd` +- Feature roles: `hammer`, `foreman_proxy` +- Infrastructure: `certificates`, `systemd_target` +- Checks: `check_hostname`, `check_database_connection`, `check_system_requirements`, `check_subuid_subgid` +- Lifecycle: `pre_install`, `post_install` + +### Configuration System + +Configuration is managed through: + +1. **Vars files** (`src/vars/`): + - `defaults.yml` - Base defaults + - `flavors/` - Deployment flavors (currently only `katello.yml`) + - `tuning/` - Resource profiles (default, development, medium, large, extra-large, extra-extra-large) + - `images.yml` - Container image references + - `database.yml`, `foreman.yml` - Service-specific configuration + +2. **Podman secrets**: See the `Service Configuration` section in the `DEPLOYMENT.md` file. + +### Custom Plugins + +- `src/callback_plugins/foremanctl.py` - Ansible callback plugin for foremanctl-specific output +- `src/filter_plugins/foremanctl.py` - Custom Jinja2 filters + +### Features and Flavors + +Features are modular capabilities that can be enabled. See [docs/developer/how-to-add-a-feature.md](docs/developer/how-to-add-a-feature.md) for the complete feature development guide. + +Current features: + +- `hammer` - CLI tool +- `foreman-proxy` - Smart proxy functionality +- `remote-execution` - Remote execution via SSH +- `google` - Google Compute Engine integration +- `azure-rm` - Azure Resource Manager integration +- `katello` - Content and subscription management + +Flavors define the base feature set: + +- `katello` - Currently the only flavor (Foreman 3.18 + Katello 4.20 + Pulp 3.85 + Candlepin 4.6) + +The `enabled_features` variable is computed as: `flavor_features + features` + +### Deployment Variables + +## Testing Architecture + +Tests use pytest with testinfra for infrastructure testing. Key fixtures in `tests/conftest.py`: + +- `server_hostname`, `server_fqdn` - Default to `quadlet` / `quadlet.example.com` +- `client_hostname`, `client_fqdn` - Default to `client` / `client.example.com` +- `certificates` - Certificate configuration based on `--certificate-source` +- SSH configuration generated from Ansible inventory at `.tmp/ssh-config` + +Test files follow the pattern `tests/_test.py` and use testinfra's server fixture to execute commands and check system state. + +## Developer Documentation + +- [How to Add a Feature](docs/developer/how-to-add-a-feature.md) - end-to-end feature development +- [Playbooks and Roles](docs/developer/playbooks-and-roles.md) - playbook structure, naming, metadata +- [Testing](docs/developer/testing.md) - test infrastructure, fixtures, patterns +- [Deployment Design](docs/developer/deployment.md) -- deployment architecture +- [Container Image Builds](docs/developer/container-image-builds.md) - image naming, registries +- [Development Environment](docs/developer/development-environment.md) - dev setup with git Foreman + +## Git Workflow + +Main branch: `master` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From a262f5e67e907dcd3e1b2cd465d1112170d67b92 Mon Sep 17 00:00:00 2001 From: Leos Stejskal Date: Tue, 5 May 2026 15:39:36 +0200 Subject: [PATCH 2/2] Point AGENTS.md to other files in the codebase --- AGENTS.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4b086d6f5..408db95d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -151,18 +151,9 @@ Configuration is managed through: Features are modular capabilities that can be enabled. See [docs/developer/how-to-add-a-feature.md](docs/developer/how-to-add-a-feature.md) for the complete feature development guide. -Current features: +For the list of current features, read the `src/features.yaml` file. -- `hammer` - CLI tool -- `foreman-proxy` - Smart proxy functionality -- `remote-execution` - Remote execution via SSH -- `google` - Google Compute Engine integration -- `azure-rm` - Azure Resource Manager integration -- `katello` - Content and subscription management - -Flavors define the base feature set: - -- `katello` - Currently the only flavor (Foreman 3.18 + Katello 4.20 + Pulp 3.85 + Candlepin 4.6) +Flavors define the base feature set, see the flavor files in the `src/vars/flavors` directory. The `enabled_features` variable is computed as: `flavor_features + features`