Merge #110: Convert firewall template to centralized variables pattern

73845dc fix: [#106] mark doctest as no_run to prevent ansible-playbook dependency (copilot-swe-agent[bot])
9a7d40e style: [#106] apply cargo fmt formatting (copilot-swe-agent[bot])
e71f865 docs: [#106] update documentation for centralized variables pattern (copilot-swe-agent[bot])
18a0514 feat: [#106] delete firewall renderer and wrapper modules (~675 lines) (copilot-swe-agent[bot])
e5bfba3 feat: [#106] remove firewall template rendering and delete old .tera file (copilot-swe-agent[bot])
ed71281 feat: [#106] convert firewall template to static with vars_files and update API (copilot-swe-agent[bot])
153011e Initial plan (copilot-swe-agent[bot])

Pull request description:

  ## ✅ Complete Vertical Slice: Convert Firewall Template to Variables Pattern

  This PR successfully implements a complete vertical slice to convert the `configure-firewall.yml.tera` template to use the centralized variables pattern, following issue #106 specification.

  ### 🎯 All Phases Complete

  - [x] Phase 1: Convert template file to static with vars_files
  - [x] Phase 2: Register static template in copy_static_templates()
  - [x] Phase 3: Update AnsibleClient signature to accept extra_args
  - [x] Phase 4: Update all AnsibleClient call sites
  - [x] Phase 5: Update ConfigureFirewallStep to use variables file
  - [x] Phase 6: Remove old firewall template rendering
  - [x] Phase 7: Delete old .tera template file
  - [x] Phase 8: Clean up firewall renderer/wrapper code (~675 lines removed)
  - [x] Phase 9: Update documentation
  - [x] Phase 10: Final validation (tests, linters, build verification)
  - [x] Fix doctest failure

  ### 📋 Changes Summary

  #### Template Conversion
  - ✅ Created static `configure-firewall.yml` (no `.tera` extension)
  - ✅ Added `vars_files: [variables.yml]` directive to playbook
  - ✅ Fixed variable syntax: `{{ssh_port}}` → `{{ ssh_port }}` (proper spacing)
  - ✅ Deleted old `configure-firewall.yml.tera`

  #### API Updates
  - ✅ Updated `AnsibleClient::run_playbook()` signature to accept `extra_args: &[&str]`
  - ✅ Updated all 5 call sites for backward compatibility
  - ✅ Added comprehensive rustdoc with examples
  - ✅ Fixed doctest to use `no_run` attribute (prevents ansible-playbook requirement in CI)

  #### Static Registration
  - ✅ Added `configure-firewall.yml` to static playbooks list in `copy_static_templates()`
  - ✅ Updated file count in debug log: 6 → 7

  #### Rendering Cleanup
  - ✅ Removed `firewall_playbook_renderer` field from `AnsibleTemplateRenderer`
  - ✅ Removed renderer initialization in constructor
  - ✅ Removed firewall rendering call from `render()` method
  - ✅ Removed `create_firewall_context()` helper method
  - ✅ Removed `FirewallPlaybookRenderingFailed` error variant
  - ✅ Removed `FirewallPlaybookTemplateRenderer` from public exports

  #### Code Cleanup (~675 lines removed)
  - ✅ Deleted `src/infrastructure/external_tools/ansible/template/renderer/firewall_playbook.rs` (347 lines)
  - ✅ Deleted `src/infrastructure/external_tools/ansible/template/wrappers/firewall_playbook/` directory (328 lines)
  - ✅ Removed module exports from `wrappers/mod.rs`
  - ✅ Removed module exports from `renderer/mod.rs`
  - ✅ Verified zero remaining references in codebase

  #### Documentation Updates
  - ✅ Updated `docs/technical/template-system-architecture.md`
  - ✅ Updated `docs/contributing/templates.md`
  - ✅ Updated `templates/ansible/README.md`

  ### ✅ Validation Complete

  **Tests**:
  - ✅ All unit tests pass: `cargo test` (1065 tests, 0 failures)
  - ✅ All doc tests pass: `cargo test --doc` (233 tests, 0 failures)
  - ✅ Build succeeds: `cargo build --release`

  **Linters**:
  - ✅ All linters pass: `cargo run --bin linter all`
  - ✅ No unused dependencies: `cargo machete`

  **Template Verification**:
  - ✅ Static `configure-firewall.yml` copied to build directory
  - ✅ Playbook contains `vars_files: [variables.yml]`
  - ✅ `variables.yml` generated with correct SSH port

  ### 📊 Impact

  - **Net change**: +184 insertions, -765 deletions
  - **Complexity reduced**: No per-playbook renderer/wrapper/context needed
  - **Pattern established**: Future playbooks can follow this simpler approach
  - **Maintainability improved**: Centralized variable management

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  >
  > ----
  >
  > *This section details on the original issue you should resolve*
  >
  > <issue_title>Convert Firewall Template to Variables Pattern (Complete Vertical Slice)</issue_title>
  > <issue_description>**Parent Epic**: #19 - Refactor Ansible Templates to Variables Pattern
  > **Depends On**: #105 - Create Variables Template Infrastructure
  >
  > ## Overview
  >
  > Convert the `configure-firewall.yml.tera` template to a static `configure-firewall.yml` playbook that loads variables from the centralized `variables.yml` file. This is a **complete vertical slice** that includes implementation, cleanup of old code, documentation updates, and full validation.
  >
  > ## Goals
  >
  > - [ ] **Template Conversion**: Convert `.tera` template to static `.yml` playbook
  > - [ ] **Variables Integration**: Add `vars_files: [variables.yml]` to load centralized variables
  > - [ ] **Static Registration**: Register playbook in `copy_static_templates()` method
  > - [ ] **AnsibleClient Enhancement**: Make generic to accept optional extra arguments
  > - [ ] **Call Site Updates**: Update all AnsibleClient call sites for new signature
  > - [ ] **Cleanup**: Remove old firewall renderer/wrapper code (~500 lines)
  > - [ ] **Documentation**: Update architecture docs, contributing guide, templates README
  > - [ ] **Validation**: Full test suite, build verification, E2E preparation
  >
  > ## 🏗️ Architecture Requirements
  >
  > **DDD Layer**: Infrastructure (template system) + Adapters (AnsibleClient)
  >
  > **Pattern**: Static template copying + Ansible vars_files
  >
  > ## Time Estimate
  >
  > **4.5 days** - Complete vertical slice (11 phases):
  > - Phases 1-8: Template conversion and API updates (2.75 days)
  > - Phase 9: Clean up old architecture (2-3 hours)
  > - Phase 10: Update documentation (1-2 hours)
  > - Phase 11: Final integration validation (0.5-1 hour)
  >
  > ## Documentation
  >
  > Full implementation details: [`docs/issues/19.2-convert-firewall-template-to-static.md`](https://github.com/torrust/torrust-tracker-deployer/blob/copilot/configure-ufw-firewall/docs/issues/19.2-convert-firewall-template-to-static.md)
  >
  > ## Acceptance Criteria
  >
  > ### Template Conversion
  > - [ ] `configure-firewall.yml` is static (no `.tera` extension)
  > - [ ] Playbook contains `vars_files: [variables.yml]`
  > - [ ] Old `.tera` template deleted
  >
  > ### API Updates
  > - [ ] `AnsibleClient::run_playbook()` accepts `extra_args` parameter
  > - [ ] All call sites updated to new signature
  > - [ ] Firewall step passes `&["-e", "@variables.yml"]`
  >
  > ### Cleanup (~500 lines removed)
  > - [ ] `firewall_playbook.rs` renderer deleted (~350 lines)
  > - [ ] `wrappers/firewall_playbook/` directory deleted (~150 lines)
  > - [ ] Module exports removed
  > - [ ] No remaining references in codebase
  >
  > ### Documentation
  > - [ ] Template system architecture updated
  > - [ ] Contributing templates guide updated
  > - [ ] Templates README updated
  > - [ ] Examples for future developers
  >
  > ### Testing & Validation
  > - [ ] Unit tests pass: `cargo test`
  > - [ ] Config tests pass: `cargo run --bin e2e-config-tests`
  > - [ ] Linters pass: `cargo run --bin linter all`
  > - [ ] Build directory structure verified
  > - [ ] Template contents verified
  >
  > ## Related
  >
  > - Parent Epic: #19
  > - Previous Task: #105 (must complete first)
  > - [Ansible vars_files Documentation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-in-files)</issue_description>
  >
  > ## Comments on the Issue (you are @copilot in this section)
  >
  > <comments>
  > </comments>
  >

  </details>

  - Fixes #106

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

ACKs for top commit:
  josecelano:
    ACK 73845dc

Tree-SHA512: e222988a51dee9c465c83276faeeee611febf8e61649e7b390cf1cf60957b7fcb00348446cfd18a74e0562ff5f14d9684727b9bd22e0c8eb35bb8819f91a97ca

Author: josecelano

docs/contributing/templates.md

@@ -274,6 +274,72 @@ When adding a static Ansible playbook:
 - [ ] Create application step to execute the playbook
 - [ ] Verify playbook appears in `build/` directory during execution
 
+## 🎯 Using Centralized Variables in Ansible Playbooks
+
+When creating new Ansible playbooks that need dynamic variables (ports, paths, etc.), use the **centralized variables pattern** instead of creating new Tera templates.
+
+### DO ✅
+
+**Add variables to `templates/ansible/variables.yml.tera`:**
+
+```yaml
+# System Configuration
+ssh_port: {{ ssh_port }}
+my_service_port: {{ my_service_port }}  # ← Add your new variable
+```
+
+**Reference variables in static playbook using `vars_files`:**
+
+```yaml
+# templates/ansible/my-new-service.yml (static playbook, no .tera extension)
+---
+- name: Configure My Service
+  hosts: all
+  vars_files:
+    - variables.yml  # Load centralized variables
+  
+  tasks:
+    - name: Configure service port
+      ansible.builtin.lineinfile:
+        path: /etc/myservice/config
+        line: "port={{ my_service_port }}"
+```
+
+**Register playbook in `copy_static_templates()` method:**
+
+```rust
+for playbook in &[
+    "update-apt-cache.yml",
+    "install-docker.yml",
+    "my-new-service.yml",  // ← Add here
+] {
+    // ...
+}
+```
+
+### DON'T ❌
+
+- ❌ Create a new `.tera` template for the playbook
+- ❌ Create a new renderer/wrapper/context for each playbook
+- ❌ Add variables directly in `inventory.yml.tera` (unless inventory-specific)
+
+### Benefits
+
+1. **Minimal Code**: No Rust boilerplate (renderer, wrapper, context) needed
+2. **Centralized Management**: All variables in one place
+3. **Runtime Resolution**: Variables resolved by Ansible, not at template rendering
+4. **Easy Maintenance**: Adding new variables requires minimal changes
+
+### When to Create a New Tera Template
+
+Only create a new `.tera` template if:
+
+1. The file **cannot** use Ansible's `vars_files` directive (e.g., inventory files)
+2. The file requires **complex logic** that Tera provides but Ansible doesn't
+3. The file needs **different variable scopes** than what centralized variables provide
+
+Otherwise, use the centralized variables pattern for simplicity.
+
 ### Related Documentation
 
 - **Architecture**: [`docs/technical/template-system-architecture.md`](../technical/template-system-architecture.md) - Understanding the two-phase template system

docs/technical/template-system-architecture.md

@@ -52,6 +52,50 @@ The system operates through two levels of indirection to balance portability wit
 - **Use Case**: Configuration files requiring runtime parameters (IPs, usernames, paths)
 - **Registration**: Automatically discovered by `.tera` extension
 
+## 🎨 Ansible Variables Pattern
+
+For Ansible templates, the system uses a **hybrid approach** combining static playbooks with centralized variables:
+
+### Tera Templates (2 templates)
+
+1. `inventory.yml.tera` - Inventory requires direct variable substitution (Ansible inventories don't support vars_files)
+2. `variables.yml.tera` - Centralized variables for all playbooks
+
+### Static Playbooks
+
+- All playbooks are static YAML files (no `.tera` extension)
+- Playbooks reference variables via `vars_files: [variables.yml]`
+- Variables are resolved at Ansible runtime, not at template rendering time
+
+### Benefits
+
+- **Reduced Rust Boilerplate**: No per-playbook renderer/wrapper/context needed
+- **Centralized Variable Management**: All playbook variables in one place
+- **Consistency**: Follows the same pattern as OpenTofu's `variables.tfvars.tera`
+- **Maintainability**: Adding new playbooks requires minimal code changes
+
+### Example
+
+```yaml
+# templates/ansible/configure-firewall.yml (static playbook)
+---
+- name: Configure UFW firewall
+  hosts: all
+  vars_files:
+    - variables.yml  # Load centralized variables
+  
+  tasks:
+    - name: Allow SSH access
+      community.general.ufw:
+        port: "{{ ssh_port }}"  # Variable from variables.yml
+```
+
+```yaml
+# templates/ansible/variables.yml.tera (rendered once)
+---
+ssh_port: {{ ssh_port }}
+```
+
 ## 🔧 Key Components
 
 ### Template Manager

src/adapters/ansible/mod.rs

@@ -45,11 +45,12 @@ impl AnsibleClient {
         }
     }
 
-    /// Run an Ansible playbook
+    /// Run an Ansible playbook with optional extra arguments
     ///
     /// # Arguments
     ///
     /// * `playbook` - Name of the playbook file (without .yml extension)
+    /// * `extra_args` - Optional extra arguments to pass to ansible-playbook
     ///
     /// # Returns
     ///
@@ -62,7 +63,23 @@ impl AnsibleClient {
     /// * The Ansible playbook execution fails
     /// * The playbook file does not exist in the working directory
     /// * There are issues with the inventory or configuration
-    pub fn run_playbook(&self, playbook: &str) -> Result<String, CommandError> {
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # use torrust_tracker_deployer_lib::adapters::ansible::AnsibleClient;
+    /// # let client = AnsibleClient::new("/path/to/config");
+    /// // Run without extra args (backward compatible)
+    /// client.run_playbook("install-docker", &[]).unwrap();
+    ///
+    /// // Run with extra variables
+    /// client.run_playbook("configure-firewall", &["-e", "@variables.yml"]).unwrap();
+    /// ```
+    pub fn run_playbook(
+        &self,
+        playbook: &str,
+        extra_args: &[&str],
+    ) -> Result<String, CommandError> {
         info!(
             "Running Ansible playbook '{}' in directory: {}",
             playbook,
@@ -71,14 +88,14 @@ impl AnsibleClient {
 
         let playbook_file = format!("{playbook}.yml");
 
+        // Build command arguments: -v flag + playbook + extra args
+        let mut args = vec!["-v", &playbook_file];
+        args.extend_from_slice(extra_args);
+
         // Use -v flag for verbose output showing task progress
         // This helps track progress during long-running operations like Docker installation
         self.command_executor
-            .run_command(
-                "ansible-playbook",
-                &["-v", &playbook_file],
-                Some(&self.working_dir),
-            )
+            .run_command("ansible-playbook", &args, Some(&self.working_dir))
             .map(|result| result.stdout)
     }
 
@@ -140,7 +157,7 @@ mod tests {
 
         // This tests the structure - we expect the method to exist and accept a &str
         // The actual execution would fail without Ansible, but we're testing the interface
-        let result = client.run_playbook("install-docker");
+        let result = client.run_playbook("install-docker", &[]);
 
         // We expect it to fail because ansible-playbook is not available in test environment
         // But this confirms the method signature and basic functionality works

src/application/steps/software/docker.rs

@@ -66,7 +66,7 @@ impl InstallDockerStep {
             "Installing Docker via Ansible"
         );
 
-        self.ansible_client.run_playbook("install-docker")?;
+        self.ansible_client.run_playbook("install-docker", &[])?;
 
         info!(
             step = "install_docker",

src/application/steps/software/docker_compose.rs

@@ -65,7 +65,8 @@ impl InstallDockerComposeStep {
             "Installing Docker Compose via Ansible"
         );
 
-        self.ansible_client.run_playbook("install-docker-compose")?;
+        self.ansible_client
+            .run_playbook("install-docker-compose", &[])?;
 
         info!(
             step = "install_docker_compose",

src/application/steps/system/configure_firewall.rs

@@ -95,11 +95,16 @@ impl ConfigureFirewallStep {
         warn!(
             step = "configure_firewall",
             action = "configure_ufw",
-            "Configuring UFW firewall - CRITICAL: SSH access will be restricted to configured port"
+            "Configuring UFW firewall with variables from variables.yml"
         );
 
-        // Run Ansible playbook (SSH port already resolved during template rendering)
-        match self.ansible_client.run_playbook("configure-firewall") {
+        // Run Ansible playbook with variables file
+        // Note: The @ symbol in Ansible means "load variables from this file"
+        // Equivalent to: ansible-playbook -e @variables.yml configure-firewall.yml
+        match self
+            .ansible_client
+            .run_playbook("configure-firewall", &["-e", "@variables.yml"])
+        {
             Ok(_) => {
                 info!(
                     step = "configure_firewall",

src/application/steps/system/configure_security_updates.rs

@@ -71,7 +71,7 @@ impl ConfigureSecurityUpdatesStep {
         );
 
         self.ansible_client
-            .run_playbook("configure-security-updates")?;
+            .run_playbook("configure-security-updates", &[])?;
 
         info!(
             step = "configure_security_updates",

src/application/steps/system/wait_cloud_init.rs

@@ -56,7 +56,7 @@ impl WaitForCloudInitStep {
             "Waiting for cloud-init completion"
         );
 
-        self.ansible_client.run_playbook("wait-cloud-init")?;
+        self.ansible_client.run_playbook("wait-cloud-init", &[])?;
 
         info!(
             step = "wait_cloud_init",