Add comprehensive contributor developer guide and link it from README#24
Open
SeanMooney wants to merge 11 commits into
Open
Add comprehensive contributor developer guide and link it from README#24SeanMooney wants to merge 11 commits into
SeanMooney wants to merge 11 commits into
Conversation
This change introduces the first provider workflow for creating ARD DevStack test deployments without Molecule or Vagrant owning the VM lifecycle. The new render, apply, deploy, destroy, and cleanup playbooks dispatch to provider roles and add an initial libvirt implementation based on rendered network and domain XML. The libvirt provider uses Debian 13 genericcloud images, XDG cache and state paths, cloud-init config-drive data, deterministic VM names and addresses, and per-deployment inventory and state files. It creates a two-node devstack-1 deployment with a controller and compute node using the stack user, SSH key injection, password fallback, passwordless sudo, serial console configuration, and persistent console logs. The provider design is updated to describe the deployment workspace, portable image, flavor, and preference model, KubeVirt instancetype defaults, XDG storage layout, and refreshed upstream DevStack and Zuul submodules. Signed-off-by: Sean Mooney <work@seanmooney.info>
The libvirt provider workflow can now drive a full two-node DevStack deployment using the current upstream DevStack roles. The deployment loader now uses stat checks for optional workspace variables, waits for cloud-init bootstrap to complete before running DevStack, and keeps the Ansible runtime dependencies needed by the existing roles. This also refreshes the DevStack service defaults to match current OVN naming by using q-ovn-agent instead of the old metadata-agent service. The controller keeps Horizon enabled for local development while compute nodes only run the services required for the subnode role. Repo cache synchronization no longer preserves host ownership and now excludes generated tox, build, egg, pycache, and pyc artifacts so local caches remain reusable source caches rather than runtime snapshots. Signed-off-by: Sean Mooney <work@seanmooney.info>
Replace incomplete delegated Molecule skeletons for role-level tests with real Podman-backed scenarios. The converted scenarios cover the existing lightweight roles without introducing Vagrant or libvirt requirements, add role-specific verification, and keep top-level deployment Molecule scenarios out of scope. Add Molecule and the Podman plugin to the uv-managed environment, plus root and role-local make targets so role scenarios can be run from either the repository root or individual role directories. Document the role-level Molecule workflow in the README. Signed-off-by: Sean Mooney <work@seanmooney.info>
Replace the Vagrant-backed top-level Molecule scenarios with ARD libvirt-backed workflows that call the provider playbooks directly. The default scenario now deploys a two-node Debian 13 DevStack master topology, and the one-controller-two-compute scenario mirrors that topology with an additional compute node and nova-compute disabled on the controller. Remove obsolete OKD, MicroShift, shift-stack, Train, and Wallaby scenarios. Add a stable-2026.1 scenario using Ubuntu 24.04 cloud images. Document the updated top-level Molecule workflow and ignore generated scenario deployment artifacts. Validated with: - uv run molecule syntax -s default - uv run molecule syntax -s one-controller-two-compute - uv run molecule syntax -s stable-2026.1 - uv run molecule test -s default Signed-off-by: Sean Mooney <work@seanmooney.info>
Local ARD deployments need a reusable workflow that is not tied to Molecule and does not duplicate image and flavor definitions across every rendered workspace. This change adds shared provider defaults, topology rendering, Make targets, and bootstrap documentation for the local libvirt path. The provider defaults move the Debian and Ubuntu image registry, libvirt settings, XDG paths, DevStack flavors, and destroy cleanup knobs into a common role. Rendered deployment workspaces now keep only deployment-specific selections such as topology, image, resource prefix, and management network. The render workflow supports one-controller-one-compute and one-controller-two-compute presets while preserving editable workspace files. The root Makefile exposes render, apply, ping, deploy, verify, destroy, generated-artifact cleanup, and full site targets for named local deployments. The libvirt domain XML uses firmware auto-selection for UEFI boot with secure boot disabled, avoiding hard-coded OVMF and explicit NVRAM paths. Bootstrap now uses bindep plus uv and supports Debian/Ubuntu and Fedora/CentOS Stream style hosts without Vagrant dependencies. Validated with syntax checks for the ARD playbooks, Molecule syntax checks for the top-level scenarios, bootstrap dry-run validation, and local render/apply/ping/destroy smoke tests. Signed-off-by: Sean Mooney <work@seanmooney.info>
Local ARD deployments benefit from a simple way to enter nodes and from a single default rebuild workflow. This change makes the default Make target run the full local sequence of destroy cleanup, render, apply, ping, deploy, and verify. Add an ard-ssh helper that reads the generated deployment inventory and builds the SSH command for a selected node. The Makefile exposes ssh and ssh-print targets so users can either connect directly or print the command for inspection and manual reuse. Document the new default and SSH workflows in the README. Signed-off-by: Sean Mooney <work@seanmooney.info>
The local Make default workflow runs ping immediately after apply. The provider apply phase therefore needs to treat SSH and cloud-init readiness as part of provisioning, otherwise apply can return while the VMs are still booting. Add provider-created nodes to the active Ansible inventory when the libvirt inventory is generated. The apply playbook now follows provider creation with a readiness play that waits for Ansible SSH connectivity and cloud-init completion on all provider nodes before returning. Document that apply waits for node readiness before later ping or deploy steps. Signed-off-by: Sean Mooney <work@seanmooney.info>
The render workflow needs to support reusable deployment intent instead of requiring every concrete deployment file to be committed or edited by hand. This is especially important for Molecule scenarios, where defining platforms and ARD nodes separately makes topology drift easy. This change adds generic render preset catalogs for branches, topologies, service profiles, and provider profiles. The render role composes those presets with optional render overrides and writes generated deployment, node, and DevStack variable files with a generated-file header. Molecule scenarios now define ARD intent once under provisioner.ard in molecule.yml. Their create playbooks derive render variables from that inline configuration, render an ignored deployment workspace, and then apply the ARD provider resources. The previously committed concrete Molecule deployment workspaces are removed so they are generated runtime state instead. The local Make render interface is extended with branch, service, provider profile, render file, and image override inputs. Validated with serial Molecule create, generated-inventory ping, and destroy for the default, one-controller-two-compute, and stable-2026.1 scenarios. Also validated the Make render/apply/ping/destroy-clean-generated/cleanup lifecycle. Signed-off-by: Sean Mooney <work@seanmooney.info>
The render workflow needs to model more than fixed controller and compute counts. Future development environments may include storage, EDPM, Kubernetes, or other node kinds, and those nodes need type-level defaults, pool-level sizing, and per-node overrides without teaching provider roles about topology semantics. This change converts topology presets to generic node pools and adds node type and network preset catalogs. The render role now normalizes node types, node pools, service profiles, network attachments, and node overrides into the existing concrete ard_nodes provider contract. Counted node pools use readable hyphenated names such as compute-1 and compute-2 by default, while singleton pools can keep explicit names such as controller. The documentation describes the new node type, node pool, network, and override model. Validated with syntax checks, serial Molecule create/ping/destroy for the default, one-controller-two-compute, and stable-2026.1 scenarios, a Make render/apply/ping/destroy-clean-generated/cleanup lifecycle, and a full one-controller-two-compute DevStack deployment with Tempest smoke. Signed-off-by: Sean Mooney <work@seanmooney.info>
The provider framework needs clearer seams between workflow runners, render normalization, and provider implementation. The Molecule scenarios were still carrying duplicated create logic, and the libvirt provider only fully supported a single management network even though render intent can now model multiple network attachments. This change moves the shared Molecule create workflow into a reusable playbook and leaves scenario create.yml files as thin imports. Rendered deployments now include an explicit management network and concrete network catalog. Inventory generation uses the named management network instead of assuming the first network attachment. The libvirt provider now renders, starts, records, and destroys all rendered networks. Domains attach every node network as a separate interface, and cloud-init writes deterministic interface configuration for each attachment. The network model also supports an opt-in isolated mode for bridge-only networks with no host-side IP, DHCP, or NAT. A built-in tenant network preset provides this behavior without being attached by default, allowing guests to run their own VLAN, DHCP, or overlay experiments. Validated with syntax checks, a temporary multi-network libvirt deployment, an isolated tenant-network deployment, default Molecule create/ping/destroy, the full serial Molecule create/ping/destroy suite, and a Make lifecycle using a non-conflicting CIDR. Signed-off-by: Sean Mooney <work@seanmooney.info>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Description
developer-guide.mdcontaining a detailed "ARD From Scratch" guide that covers orientation, host prep, render/apply/deploy workflows, provider and DevStack role references, Molecule/test strategy, maintenance, and troubleshooting.README.mdto reference the new guide with a link todeveloper-guide.mdso contributors can find the detailed developer documentation from the top-level README.Testing
Codex Task