kubevirt.core/AGENTS.md

# AGENTS.MD - kubevirt.core
## Strict rules
- Always make sure Apache 2.0 headers are present.
- Always run `make format`, `make test-unit`, `make test-sanity`, `make test-integration` before pushing.

## Project Overview
`kubevirt.core` is an Ansible collection that provides modules and plugins for managing KubeVirt virtual machines on Kubernetes clusters. It includes modules to create, delete, and query VirtualMachines and VirtualMachineInstances (`kubevirt_vm`, `kubevirt_vm_info`, `kubevirt_vmi_info`), as well as a dynamic inventory plugin (`kubevirt`) that discovers running VMs for use as Ansible targets. The collection depends on `kubernetes.core` and the Python `kubernetes` client library to interact with the Kubernetes API.

## Architecture
Ansible collection project with three main plugins:

* `kubevirt`: Inventory source for KubeVirt VirtualMachines
* `kubevirt_vm`: Create or delete KubeVirt VirtualMachines
* `kubevirt_vm_info`: Describe KubeVirt VirtualMachines
* `kubevirt_vmi_info`: Describe KubeVirt VirtualMachineInstances

The key directories are:

* `plugins/` — Contains all Ansible plugin code.
  * `plugins/modules/` — Ansible modules (`kubevirt_vm`, `kubevirt_vm_info`, `kubevirt_vmi_info`) that implement the CRUD operations against the KubeVirt API.
  * `plugins/inventory/` — Dynamic inventory plugin (`kubevirt.py`) that discovers KubeVirt VMs and exposes them as Ansible hosts.
  * `plugins/module_utils/` — Shared Python helpers (`diff.py`, `info.py`) used by the modules to handle resource diffing and info retrieval.
  * `plugins/doc_fragments/` — Reusable documentation fragments (e.g., `kubevirt_auth_options.py`) included in module docs.
* `tests/` — All test suites for the collection.
  * `tests/unit/` — Unit tests for plugin logic.
  * `tests/integration/` — Integration tests that run against a live KubeVirt cluster.
  * `tests/sanity/` — Ansible sanity test ignore files per Ansible version.
* `meta/` — Collection metadata (`runtime.yml`) defining the minimum supported Ansible version (`requires_ansible`).
* `docs/` — Project documentation sources (`developing.md` for code conventions, `testing.md` for test setup, `releasing.md` for versioning strategy).
* `examples/` — Sample playbooks and inventory files demonstrating collection usage.
* `changelogs/` — Changelog configuration and release fragments used by `antsibull-changelog`.
* `hack/` — Helper scripts for CI/dev environments (e.g., `e2e-setup.sh` for end-to-end cluster setup).
* `bin/` — Vendored tool wrappers (`kind`, `kubectl`) used by CI and local development.

## Build and Development
### Prerequisites
- Python (check [README.md](README.md) Section [Ansible and Python version compatibility](README.md#ansible-and-python-version-compatibility) for required version).
- Ansible (check [README.md](README.md) Section [Ansible and Python version compatibility](README.md#ansible-and-python-version-compatibility) for required version).
- `kubernetes.core` Ansible collection (see `requirements.yml` for version constraints). Install with `ansible-galaxy collection install -r requirements.yml`.
- Python libraries: `jsonpatch`, `kubernetes`, `PyYAML` (see `requirements.txt` for version constraints). Install with `pip install -r requirements.txt`.
- Test dependencies: `pytest`, `pytest-ansible`, `pytest-mock`, `pytest-xdist`, `ansible-compat`, `typing-extensions` (see `test-requirements.txt`). Install with `pip install -r test-requirements.txt`.
- Formatting: `black` (installed automatically by `tox` when running `make format`).
- `tox` and `tox-ansible` for running tests and managing virtualenvs.

### Key make targets
- `make build-venv` — Create a development virtualenv (via tox) and symlink it to `.venv`.
- `make format` — Run `black` code formatter.
- `make test-unit` — Run unit tests across supported Ansible versions.
- `make test-sanity` — Run Ansible sanity tests across supported Ansible versions.

### Cluster development
- `make test-integration` — Run integration tests (requires a running KubeVirt cluster).
- `make cluster-up` — Spin up a local Kind cluster with KubeVirt installed. 
- `make cluster-down` — Tear down the local Kind cluster. 

### Building collection
In order to build the collection and install it locally, run:

```bash
ansible-galaxy collection build .
ansible-galaxy collection install kubevirt-kubevirt.core-*.tar.gz
```
### Contributor's guidelines 
Check [developing.md](docs/developing.md) to get code and naming style conventions.

## Testing
- **Unit tests:** pytest is used. Run with `make test-unit`.
- **Integration tests:** Tests ran in a live Kubernetes cluster. These tests are collections of ansible playbooks crafted to deploy, fetch and assert certain actions.
- **Sanity tests:** Built-in `ansible-test sanity` checks (PEP 8, import validation, documentation, etc.). Run with `make test-sanity`. Per-version ignore files live in `tests/sanity/`, in this directory, a per-version ignore file need to be added everytime there is a new version of ansible-core..
- **Module unit tests:** Located in `tests/unit/plugins/modules/`. These tests invoke each module's `main()` entry point with patched `AnsibleModule` args and mocked API clients, verifying argument validation, expected API calls, and exit/fail outcomes without hitting a real cluster.
- **Blackbox unit tests:** Located in `tests/unit/plugins/inventory/blackbox/`. These tests call `_populate_inventory` with crafted VM, VMI, and service data, then assert the resulting inventory state (host vars, groups, connections). They verify user-facing inventory behaviour end-to-end without hitting a real cluster.

Follow instructions in [testing.md](docs/testing.md) to set up development environments. Use the `make` targets for running the tests.
Before running a test that makes use of `ansible-test` command such as `make test-integration`, it is required to spam a Kubernetes cluster using `make cluster-up` and to bind mount the repository as described in [testing.md](docs/testing.md) section "Running tests with ansible-test".
Moreover, the Kubernetes cluster can be used to do quick tests such as running a test Ansible inventory, Ansible playbook, etc. In directory, `bin` the tool `kubectl` can be found to work with the cluster directly. Nevertheless, in this project, ansible commands are preferred.

### Test patterns

#### Naming conventions
- Test files are named `test_<function_name>.py`, one per function under test.
- Test functions are named `test_<function>_<scenario>` (e.g., `test_fetch_objects_early_return`).

#### Unit test conventions
- Unit tests must assert and test each and every code branch.
- Unit tests use `mocker.patch` / `mocker.patch.object` (from `pytest-mock`) for patching, and `monkeypatch` when simpler attribute replacement suffices.
- Unit test must use `@pytest.mark.parametrize` as much as possible.
- When parametrize arguments become too complex or definitions could be reused across tests, define them as module-level dict constants and combine variants using the `|` (dict union) operator.
- Use `pytest.raises(Exception, match=pattern)` for exception message validation.

#### Shared fixtures and utilities
- `tests/unit/plugins/inventory/conftest.py` provides shared fixtures (`inventory`, `groups`, `hosts`, `client`) all scoped to `function` for test isolation.
- Test files may define local fixtures when scenarios require specific setup (e.g., `test_kubevirt_format_dynamic_api_exc.py`).
- `tests/unit/utils/ansible_module_mock.py` provides the `patch_module_args()` context manager and `AnsibleExitJson`/`AnsibleFailJson` exception classes used across module tests.
- `tests/unit/plugins/inventory/constants.py` provides shared constants (`DEFAULT_NAMESPACE`, `DEFAULT_BASE_DOMAIN`) and a `merge_dicts()` helper for deep dictionary merging.
- `request.getfixturevalue()` is used for dynamic fixture lookup when tests need to select fixtures at runtime.

#### Integration test structure
- Integration tests are located inside each `target` directory depending on which plugin is being tested (`tests/integration/targets/`).
- Each target contains: `runme.sh` (entry point), `generate.yml` (generates test files from Jinja2 templates), and `*.yml.j2` templates.
- Tests follow a Generate -> Run -> Verify -> Cleanup lifecycle with bash trap handlers for cleanup on failure.
- Namespace isolation is achieved via random suffixes to prevent conflicts between test runs.

## Plugin Design

### Inventory plugin — `plugins/inventory/kubevirt.py`
Dynamic inventory plugin that extends Ansible's `BaseInventoryPlugin`, `Constructable`, and `Cacheable`. Config files must end in `*.kubevirt.yml` or `*.kubevirt.yaml`.

The plugin follows a fetch-then-populate pipeline:
1. Parse the user config and build an options dataclass.
2. Check the inventory cache or fetch VMs, VMIs, and Services from the Kubernetes API via the `kubernetes.core` dynamic client.
3. Populate the inventory by creating groups (by cluster name and namespace) and adding hosts with variables derived from VM/VMI metadata and status.

Key design details:
- Host naming is configurable via `host_format` (default: `{namespace}-{name}`).
- Host vars are prefixed with `vm_` or `vmi_` depending on the source object. Status fields are converted from camelCase to snake_case.
- Connection address resolution follows a priority order: `kube_secondary_dns` derived hostname, LoadBalancer/NodePort service host+port, or the VMI's primary interface IP.
- Windows VMs are auto-detected (via `guestOSInfo`, preference annotations, or `vm.kubevirt.io/os` annotation) and set `ansible_connection=winrm` with WinRM service port lookup.
- Supports Ansible `constructed` features (`compose`, `groups`, `keyed_groups`).
- Includes backwards-compatible handling for a deprecated `connections` parameter (removed in 3.0.0).

### Module — `plugins/modules/kubevirt_vm.py`
Creates, patches, or deletes KubeVirt VirtualMachines. The module:
1. Defines its argument spec by merging module-specific args with auth and common specs from `kubernetes.core`.
2. Constructs a VM resource definition from module params, translating Ansible-style snake_case params into the KubeVirt API spec (camelCase).
3. Sets a wait condition based on `running`/`run_strategy` params to determine expected VM state.
4. Delegates execution to `kubernetes.core`'s runner.

Supports `name` or `generate_name` (mutually exclusive), `running` or `run_strategy` (mutually exclusive), instancetype/preference matchers, data volume templates, and `hidden_fields` for filtering noisy metadata from results.

### Module — `plugins/modules/kubevirt_vm_info.py`
Read-only module to describe KubeVirt VirtualMachines. Builds its arg spec from a shared info spec (defined in `module_utils/info.py`) plus auth args, adds a `running` parameter to control the wait condition, and delegates to a shared info execution function.

### Module — `plugins/modules/kubevirt_vmi_info.py`
Read-only module to describe KubeVirt VirtualMachineInstances. Structurally identical to `kubevirt_vm_info` but queries `VirtualMachineInstance` resources and has no `running` parameter (always waits for Ready=True).

### Shared utilities — `plugins/module_utils/`
- `info.py` — Shared argument spec and execution logic for the info modules. Instantiates a `K8sService`, performs the resource lookup, and exits with results.
- `diff.py` — Monkey-patches `kubernetes.core`'s diff logic to ignore metadata-only changes (`generation`, `resourceVersion`), fixing false-positive "changed" results.


## Conventions

### Code
- All source files must carry Apache 2.0 license headers.
- Code style and naming conventions are documented in [developing.md](docs/developing.md).
- Always use strong typing in the function headers. This applies to parameters and return values.

### Commits
- Commit messages follow conventional commits with scope, e.g. `feat(vm_info): ...`, `fix(tests): ...`, `chore(deps): ...`.
- Commits must be signed off (`git commit -s`).
- If an AI agent assisted the developer, the commit must add `assisted-by` and the AI agent signature.

### Pull requests and issues
- PRs must follow `.github/PULL_REQUEST_TEMPLATE.md`. Key sections: what the PR does, which issue(s) it fixes, reviewer notes, and a release note block.
- Issues must follow the templates in `.github/ISSUE_TEMPLATE/` (`bug_report.md`, `feature_request.md`).
- Always read the relevant template before creating a PR or issue and fill in all sections.
- PRs must pass CI (linter, sanity, unit, and integration tests) before merge.

### Versioning and releases
- The project follows [Semantic Versioning 2.0.0](https://semver.org/) as documented in [releasing.md](docs/releasing.md).
- Releases are triggered by annotated git tags. The CI workflow (`.github/workflows/release.yml`) builds the collection, publishes to Ansible Galaxy, and creates a GitHub release.
- Changelog entries are managed by `antsibull-changelog` using fragments in `changelogs/fragments/`.

### CI
- Main CI workflow (`.github/workflows/ci.yml`) runs: tree-clean check, ansible-lint, sanity tests, and unit tests across a matrix of Ansible and Python versions.
- Integration tests run in a separate workflow (`.github/workflows/integration.yml`) against a Kind cluster with KubeVirt.
- Docs linting validates Ansible documentation format via `antsibull-docs` (`.github/workflows/extra-docs-linting.yml`).
- Dependency updates are automated via Renovate (`renovate.json`), which manages e2e-setup tool versions, GitHub Actions, and collection dependencies.