refactor: create foundation for instance name parameterization

- Create OpenTofu variables template with instance_name variable
- Update main.tf to use var.instance_name instead of hardcoded 'torrust-vm'
- Refactor OpenTofu client to accept extra_args parameter for reusability
- Update infrastructure steps to pass -var-file=variables.tfvars explicitly
- Fix variable naming: use instance_name instead of container_name for VMs
- Maintain generic client design while supporting variables file functionality

All tests pass and e2e validation successful with new parameterized approach.

Author: josecelano

docs/refactors/instance-name-parameterization.md

@@ -2,9 +2,90 @@
 
 ## Overview
 
-This refactor aims to eliminate the hardcoded "torrust-vm" instance name throughout the codebase and make it configurable from the top-level main function in `src/bin/e2e_tests.rs`.
+This refactor aims t## 🔄 Design Updates
 
-## Motivation
+### Variable Naming Convention
+
+- **Variable name**: `instance_name` (not `container_name`) - since we're provisioning VM instances
+- **Scope**: Focus on instance name parameterization only
+- **Static variables**: Keep `image` and other variables static for now (not Tera templated)
+
+## 🎯 Implementation Plan
+
+### Phase 1: Foundation - OpenTofu Variables Infrastructure
+
+**Goal**: Establish OpenTofu variables file pattern and integration
+
+#### Step 1a: Create OpenTofu variables template ✅
+
+- Create `templates/tofu/lxd/variables.tfvars` template file to define `instance_name` variable
+- Update `TofuTemplateRenderer` to include this file in static template copying
+- Keep `image` variable static (not templated)
+- **Status**: Static variables file created with hardcoded "torrust-vm" value
+- **Validation**: Unit tests + linters + e2e tests must pass
+
+#### Step 1b: Update OpenTofu client for variables file
+
+- Modify OpenTofu client to pass `-var-file` parameter to `tofu` commands
+- Update unit tests for `TofuClient`
+- **Validation**: All OpenTofu commands work with variables file
+
+### Phase 2: Template Parameterization
+
+**Goal**: Convert static variables to dynamic Tera templates
+
+#### Step 2a: Convert variables.tfvars to Tera template
+
+- Transform static `variables.tfvars` into `variables.tfvars.tera` template with `{{instance_name}}` placeholder
+- Update `TofuTemplateRenderer` to render it with context
+- **Validation**: Rendered file contains correct instance name value
+
+#### Step 2b: Update main.tf to use variables
+
+- Modify `templates/tofu/lxd/main.tf.tera` to use `var.instance_name` instead of hardcoded "torrust-vm"
+- Ensure proper OpenTofu variable reference syntax
+- **Validation**: Infrastructure deploys with custom instance names
+
+### Phase 3: Context Integration
+
+#### Step 3: Add instance_name to TofuContext
+
+- Add `instance_name` field to `TofuContext` struct in `src/tofu/template/context.rs`
+- Provide default value "torrust-vm" for backward compatibility
+- **Validation**: Context serialization and template rendering work
+
+### Phase 4: E2E Integration
+
+#### Step 4: Update E2E tests infrastructure context
+
+- Modify `src/e2e/tasks/provision_infrastructure.rs` to pass custom `instance_name` in `TofuContext`
+- Start with default value for validation
+- **Validation**: E2E tests pass with parameterized context
+
+#### Step 5: Add parameterization to e2e_tests.rs main
+
+- Modify `src/bin/e2e_tests.rs` main function to accept instance name parameter
+- Pass it through to E2E tasks
+- Implement CLI argument parsing
+- **Validation**: CLI accepts custom instance names
+
+### Phase 5: Complete Migration
+
+#### Step 6: Update remaining hardcoded references
+
+- Replace remaining 54 hardcoded "torrust-vm" occurrences across codebase with parameterized values
+- Update tests and documentation
+- **Validation**: All hardcoded references eliminated
+
+#### Final validation and documentation
+
+- Run comprehensive tests
+- Update documentation to reflect parameterization capabilities
+- **Validation**: All hardcoded references are eliminated
+
+## 🔍 Analysis of Current "torrust-vm" Usage
+
+This refactor addresses a comprehensive parameterization of the h
 
 Currently, the instance name "torrust-vm" is hardcoded in multiple places across the codebase, including:
 

src/command_wrappers/opentofu/client.rs

@@ -124,6 +124,10 @@ impl OpenTofuClient {
 
     /// Plan infrastructure changes
     ///
+    /// # Arguments
+    ///
+    /// * `extra_args` - Additional arguments to pass to the tofu plan command (e.g., "-var-file=variables.tfvars")
+    ///
     /// # Returns
     ///
     /// * `Ok(String)` - The stdout output if the command succeeds
@@ -134,21 +138,25 @@ impl OpenTofuClient {
     /// This function will return an error if:
     /// * The `OpenTofu` plan fails
     /// * The configuration is not initialized
-    pub fn plan(&self) -> Result<String, CommandError> {
+    pub fn plan(&self, extra_args: &[&str]) -> Result<String, CommandError> {
         info!(
             "Planning infrastructure changes in directory: {}",
             self.working_dir.display()
         );
 
+        let mut args = vec!["plan"];
+        args.extend_from_slice(extra_args);
+
         self.command_executor
-            .run_command("tofu", &["plan"], Some(&self.working_dir))
+            .run_command("tofu", &args, Some(&self.working_dir))
     }
 
     /// Apply infrastructure changes
     ///
     /// # Arguments
     ///
     /// * `auto_approve` - Whether to automatically approve the changes without interactive confirmation
+    /// * `extra_args` - Additional arguments to pass to the tofu apply command (e.g., "-var-file=variables.tfvars")
     ///
     /// # Returns
     ///
@@ -160,13 +168,14 @@ impl OpenTofuClient {
     /// This function will return an error if:
     /// * The `OpenTofu` apply fails
     /// * The configuration is not initialized
-    pub fn apply(&self, auto_approve: bool) -> Result<String, CommandError> {
+    pub fn apply(&self, auto_approve: bool, extra_args: &[&str]) -> Result<String, CommandError> {
         info!(
             "Applying infrastructure changes in directory: {}",
             self.working_dir.display()
         );
 
         let mut args = vec!["apply"];
+        args.extend_from_slice(extra_args);
         if auto_approve {
             args.push("-auto-approve");
         }
@@ -180,6 +189,7 @@ impl OpenTofuClient {
     /// # Arguments
     ///
     /// * `auto_approve` - Whether to automatically approve the destruction without interactive confirmation
+    /// * `extra_args` - Additional arguments to pass to the tofu destroy command (e.g., "-var-file=variables.tfvars")
     ///
     /// # Returns
     ///
@@ -191,13 +201,14 @@ impl OpenTofuClient {
     /// This function will return an error if:
     /// * The `OpenTofu` destroy fails
     /// * The configuration is not initialized
-    pub fn destroy(&self, auto_approve: bool) -> Result<String, CommandError> {
+    pub fn destroy(&self, auto_approve: bool, extra_args: &[&str]) -> Result<String, CommandError> {
         info!(
             "Destroying infrastructure in directory: {}",
             self.working_dir.display()
         );
 
         let mut args = vec!["destroy"];
+        args.extend_from_slice(extra_args);
         if auto_approve {
             args.push("-auto-approve");
         }
@@ -336,7 +347,7 @@ resource "null_resource" "test" {
         drop(client.init());
 
         // This would fail if OpenTofu is not installed, so we ignore it by default
-        match client.plan() {
+        match client.plan(&[]) {
             Ok(_output) => {
                 // Plan succeeded
             }

src/e2e/tasks/cleanup_infrastructure.rs

@@ -53,11 +53,11 @@ pub fn cleanup_infrastructure(env: &TestEnvironment) {
 
     info!(operation = "cleanup", "Cleaning up test environment");
 
-    // Destroy infrastructure using OpenTofuClient
+    // Destroy infrastructure using OpenTofuClient with variables file
     let result = env
         .services
         .opentofu_client
-        .destroy(true) // auto_approve = true
+        .destroy(true, &["-var-file=variables.tfvars"]) // auto_approve = true
         .map_err(anyhow::Error::from);
 
     match result {

src/steps/infrastructure/apply.rs

@@ -73,8 +73,10 @@ impl ApplyInfrastructureStep {
             "Applying OpenTofu infrastructure"
         );
 
-        // Execute tofu apply command
-        let output = self.opentofu_client.apply(self.auto_approve)?;
+        // Execute tofu apply command with variables file
+        let output = self
+            .opentofu_client
+            .apply(self.auto_approve, &["-var-file=variables.tfvars"])?;
 
         info!(
             step = "apply_infrastructure",

src/steps/infrastructure/plan.rs

@@ -58,8 +58,8 @@ impl PlanInfrastructureStep {
             "Planning OpenTofu infrastructure"
         );
 
-        // Execute tofu plan command
-        let output = self.opentofu_client.plan()?;
+        // Execute tofu plan command with variables file
+        let output = self.opentofu_client.plan(&["-var-file=variables.tfvars"])?;
 
         info!(
             step = "plan_infrastructure",

src/tofu/template/renderer/mod.rs

@@ -154,7 +154,7 @@ impl TofuTemplateRenderer {
         let build_tofu_dir = self.create_build_directory().await?;
 
         // List of static templates to copy directly
-        let static_template_files = vec!["main.tf"];
+        let static_template_files = vec!["main.tf", "variables.tfvars"];
 
         // Copy static template files
         self.copy_templates(&static_template_files, &build_tofu_dir)

templates/tofu/lxd/main.tf

@@ -14,8 +14,8 @@ provider "lxd" {
 }
 
 # Variables
-variable "container_name" {
-  description = "Name of the LXD container"
+variable "instance_name" {
+  description = "Name of the LXD instance"
   type        = string
   default     = "torrust-vm"
 }
@@ -58,7 +58,7 @@ resource "lxd_profile" "torrust_profile" {
 
 # Create the LXD virtual machine
 resource "lxd_instance" "torrust_vm" {
-  name      = var.container_name
+  name      = var.instance_name
   image     = var.image
   type      = "virtual-machine"
   profiles  = [lxd_profile.torrust_profile.name]
@@ -90,20 +90,20 @@ output "instance_info" {
 output "connection_commands" {
   description = "Commands to connect to the container"
   value = [
-    "lxc exec ${var.container_name} -- /bin/bash",
-    "lxc exec ${var.container_name} -- whoami",
-    "lxc exec ${var.container_name} -- systemctl status",
-    "lxc list ${var.container_name}"
+    "lxc exec ${var.instance_name} -- /bin/bash",
+    "lxc exec ${var.instance_name} -- whoami",
+    "lxc exec ${var.instance_name} -- systemctl status",
+    "lxc list ${var.instance_name}"
   ]
 }
 
 output "test_commands" {
   description = "Commands to test the container functionality"
   value = [
-    "lxc exec ${var.container_name} -- cat /etc/os-release",
-    "lxc exec ${var.container_name} -- df -h",
-    "lxc exec ${var.container_name} -- free -h",
-    "lxc exec ${var.container_name} -- systemctl list-units --type=service --state=running",
-    "lxc exec ${var.container_name} -- cloud-init status"
+    "lxc exec ${var.instance_name} -- cat /etc/os-release",
+    "lxc exec ${var.instance_name} -- df -h",
+    "lxc exec ${var.instance_name} -- free -h",
+    "lxc exec ${var.instance_name} -- systemctl list-units --type=service --state=running",
+    "lxc exec ${var.instance_name} -- cloud-init status"
   ]
 }