feat: [#238] add Ansible deployment for Prometheus (Phase 6)

- Create Ansible playbooks for Prometheus storage and config deployment
  - create-prometheus-storage.yml: Creates /opt/torrust/storage/prometheus/etc
  - deploy-prometheus-config.yml: Deploys prometheus.yml with verification
- Create application steps following tracker pattern
  - CreatePrometheusStorageStep: Executes create-prometheus-storage playbook
  - DeployPrometheusConfigStep: Executes deploy-prometheus-config playbook
- Register playbooks in AnsibleProjectGenerator (16 total)
- Register steps in application/steps/application module
- Add release handler methods with conditional execution
  - create_prometheus_storage(): Step 5 in workflow
  - deploy_prometheus_config_to_remote(): Step 7 in workflow
- Add ReleaseStep enum variants for Prometheus operations
- Add PrometheusStorageCreation error variant with help text
- Update workflow to 9 steps total
- All linters passing, all tests passing (1507 tests)

Each service now independently handles storage creation and config deployment.

Author: josecelano

docs/issues/238-prometheus-slice-release-run-commands.md

@@ -51,7 +51,7 @@ This task adds Prometheus as a metrics collection service for the Torrust Tracke
   - Added 4 comprehensive unit tests for Prometheus service rendering
   - All linters passing
 
-- ✅ **Phase 5**: Release Command Integration (commit: TBD)
+- ✅ **Phase 5**: Release Command Integration (commit: f20d45c)
 
   - **FIXED**: Moved Prometheus template rendering from docker-compose step to independent step in release handler
   - Created `RenderPrometheusTemplatesStep` to render Prometheus templates
@@ -63,8 +63,34 @@ This task adds Prometheus as a metrics collection service for the Torrust Tracke
   - All linters passing, all tests passing (1507 tests)
   - **Architectural Principle**: Each service renders its templates independently in the release handler
 
-- ⏳ **Phase 6**: Ansible Deployment (pending)
-- ⏳ **Phase 6**: Ansible Playbook Integration (pending)
+- ✅ **Phase 6**: Ansible Deployment (commit: pending)
+
+  - Created Ansible playbooks:
+    - `templates/ansible/create-prometheus-storage.yml` - Creates `/opt/torrust/storage/prometheus/etc` directory
+    - `templates/ansible/deploy-prometheus-config.yml` - Deploys `prometheus.yml` configuration file with verification
+  - Created Rust application steps:
+    - `CreatePrometheusStorageStep` - Executes create-prometheus-storage playbook
+    - `DeployPrometheusConfigStep` - Executes deploy-prometheus-config playbook
+  - Registered playbooks in `AnsibleProjectGenerator` (16 total playbooks)
+  - Registered steps in `application/steps/application/mod.rs`
+  - Updated release handler with new methods:
+    - `create_prometheus_storage()` - Creates Prometheus storage directories (Step 5)
+    - `deploy_prometheus_config_to_remote()` - Deploys Prometheus config (Step 7)
+  - Added new `ReleaseStep` enum variants:
+    - `CreatePrometheusStorage`
+    - `DeployPrometheusConfigToRemote`
+  - Added error handling:
+    - `PrometheusStorageCreation` error variant with help text
+    - Proper trace formatting and error classification
+  - Updated workflow to 9 steps total:
+    - Step 5: Create Prometheus storage (if enabled)
+    - Step 6: Render Prometheus templates (if enabled)
+    - Step 7: Deploy Prometheus config (if enabled)
+    - Step 8: Render Docker Compose templates
+    - Step 9: Deploy compose files
+  - All linters passing, all tests passing (1507 tests)
+  - **Pattern**: Independent Prometheus deployment following tracker pattern
+
 - ⏳ **Phase 7**: Testing (pending)
 - ⏳ **Phase 8**: Documentation (pending)
 

src/application/command_handlers/release/errors.rs

@@ -48,6 +48,10 @@ pub enum ReleaseCommandHandlerError {
     #[error("Tracker database initialization failed: {0}")]
     TrackerDatabaseInit(String),
 
+    /// Prometheus storage directory creation failed
+    #[error("Prometheus storage creation failed: {0}")]
+    PrometheusStorageCreation(String),
+
     /// General deployment operation failed
     #[error("Deployment failed: {message}")]
     Deployment {
@@ -102,6 +106,11 @@ impl Traceable for ReleaseCommandHandlerError {
             Self::TrackerDatabaseInit(message) => {
                 format!("ReleaseCommandHandlerError: Tracker database initialization failed - {message}")
             }
+            Self::PrometheusStorageCreation(message) => {
+                format!(
+                    "ReleaseCommandHandlerError: Prometheus storage creation failed - {message}"
+                )
+            }
             Self::Deployment { message, .. } | Self::DeploymentFailed { message, .. } => {
                 format!("ReleaseCommandHandlerError: Deployment failed - {message}")
             }
@@ -125,6 +134,7 @@ impl Traceable for ReleaseCommandHandlerError {
             | Self::TemplateRendering(_)
             | Self::TrackerStorageCreation(_)
             | Self::TrackerDatabaseInit(_)
+            | Self::PrometheusStorageCreation(_)
             | Self::ReleaseOperationFailed { .. } => None,
         }
     }
@@ -137,7 +147,8 @@ impl Traceable for ReleaseCommandHandlerError {
             Self::StatePersistence(_) => ErrorKind::StatePersistence,
             Self::TemplateRendering(_)
             | Self::TrackerStorageCreation(_)
-            | Self::TrackerDatabaseInit(_) => ErrorKind::TemplateRendering,
+            | Self::TrackerDatabaseInit(_)
+            | Self::PrometheusStorageCreation(_) => ErrorKind::TemplateRendering,
             Self::Deployment { .. } | Self::ReleaseOperationFailed { .. } => {
                 ErrorKind::InfrastructureOperation
             }
@@ -308,6 +319,30 @@ Common causes:
 - Ansible playbook not found
 - Network connectivity issues
 
+For more information, see docs/user-guide/commands.md"
+            }
+            Self::PrometheusStorageCreation(_) => {
+                "Prometheus Storage Creation Failed - Troubleshooting:
+
+1. Verify the target instance is reachable:
+   ssh <user>@<instance-ip>
+
+2. Check that the instance has sufficient disk space:
+   df -h
+
+3. Verify the Ansible playbook exists:
+   ls templates/ansible/create-prometheus-storage.yml
+
+4. Check Ansible execution permissions
+
+5. Review the error message above for specific details
+
+Common causes:
+- Insufficient disk space on target instance
+- Permission denied on target directories
+- Ansible playbook not found
+- Network connectivity issues
+
 For more information, see docs/user-guide/commands.md"
             }
             Self::Deployment { .. } => {

src/application/command_handlers/release/handler.rs

@@ -10,7 +10,10 @@ use super::errors::ReleaseCommandHandlerError;
 use crate::adapters::ansible::AnsibleClient;
 use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::{
-    application::{CreateTrackerStorageStep, DeployTrackerConfigStep, InitTrackerDatabaseStep},
+    application::{
+        CreatePrometheusStorageStep, CreateTrackerStorageStep, DeployPrometheusConfigStep,
+        DeployTrackerConfigStep, InitTrackerDatabaseStep,
+    },
     rendering::{RenderPrometheusTemplatesStep, RenderTrackerTemplatesStep},
     DeployComposeFilesStep, RenderDockerComposeTemplatesStep,
 };
@@ -199,13 +202,19 @@ impl ReleaseCommandHandler {
         // Step 4: Deploy tracker configuration to remote
         self.deploy_tracker_config_to_remote(environment, &tracker_build_dir, instance_ip)?;
 
-        // Step 5: Render Prometheus configuration templates (if enabled)
+        // Step 5: Create Prometheus storage directories (if enabled)
+        Self::create_prometheus_storage(environment, instance_ip)?;
+
+        // Step 6: Render Prometheus configuration templates (if enabled)
         Self::render_prometheus_templates(environment)?;
 
-        // Step 6: Render Docker Compose templates
+        // Step 7: Deploy Prometheus configuration to remote (if enabled)
+        self.deploy_prometheus_config_to_remote(environment, instance_ip)?;
+
+        // Step 8: Render Docker Compose templates
         let compose_build_dir = self.render_docker_compose_templates(environment).await?;
 
-        // Step 7: Deploy compose files to remote
+        // Step 9: Deploy compose files to remote
         self.deploy_compose_files_to_remote(environment, &compose_build_dir, instance_ip)?;
 
         let released = environment.clone().released();
@@ -359,6 +368,104 @@ impl ReleaseCommandHandler {
         Ok(())
     }
 
+    /// Create Prometheus storage directories on the remote host (if enabled)
+    ///
+    /// This step is optional and only executes if Prometheus is configured in the environment.
+    /// If Prometheus is not configured, the step is skipped without error.
+    ///
+    /// # Errors
+    ///
+    /// Returns a tuple of (error, `ReleaseStep::CreatePrometheusStorage`) if creation fails
+    #[allow(clippy::result_large_err)]
+    fn create_prometheus_storage(
+        environment: &Environment<Releasing>,
+        _instance_ip: IpAddr,
+    ) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+        let current_step = ReleaseStep::CreatePrometheusStorage;
+
+        // Check if Prometheus is configured
+        if environment.context().user_inputs.prometheus.is_none() {
+            info!(
+                command = "release",
+                step = %current_step,
+                status = "skipped",
+                "Prometheus not configured - skipping storage creation"
+            );
+            return Ok(());
+        }
+
+        let ansible_client = Arc::new(AnsibleClient::new(environment.build_dir().join("ansible")));
+
+        CreatePrometheusStorageStep::new(ansible_client)
+            .execute()
+            .map_err(|e| {
+                (
+                    ReleaseCommandHandlerError::PrometheusStorageCreation(e.to_string()),
+                    current_step,
+                )
+            })?;
+
+        info!(
+            command = "release",
+            step = %current_step,
+            "Prometheus storage directories created successfully"
+        );
+
+        Ok(())
+    }
+
+    /// Deploy Prometheus configuration to the remote host via Ansible (if enabled)
+    ///
+    /// This step is optional and only executes if Prometheus is configured in the environment.
+    /// If Prometheus is not configured, the step is skipped without error.
+    ///
+    /// # Arguments
+    ///
+    /// * `environment` - The environment in Releasing state
+    /// * `instance_ip` - The target instance IP address
+    ///
+    /// # Errors
+    ///
+    /// Returns a tuple of (error, `ReleaseStep::DeployPrometheusConfigToRemote`) if deployment fails
+    #[allow(clippy::result_large_err, clippy::unused_self)]
+    fn deploy_prometheus_config_to_remote(
+        &self,
+        environment: &Environment<Releasing>,
+        _instance_ip: IpAddr,
+    ) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+        let current_step = ReleaseStep::DeployPrometheusConfigToRemote;
+
+        // Check if Prometheus is configured
+        if environment.context().user_inputs.prometheus.is_none() {
+            info!(
+                command = "release",
+                step = %current_step,
+                status = "skipped",
+                "Prometheus not configured - skipping config deployment"
+            );
+            return Ok(());
+        }
+
+        let ansible_client = Arc::new(AnsibleClient::new(environment.build_dir().join("ansible")));
+
+        DeployPrometheusConfigStep::new(ansible_client)
+            .execute()
+            .map_err(|e| {
+                (
+                    ReleaseCommandHandlerError::TemplateRendering(e.to_string()),
+                    current_step,
+                )
+            })?;
+
+        info!(
+            command = "release",
+            step = %current_step,
+            "Prometheus configuration deployed successfully"
+        );
+
+        Ok(())
+    }
+
     /// Deploy tracker configuration to the remote host via Ansible
     ///
     /// # Arguments

src/application/steps/application/create_prometheus_storage.rs

@@ -0,0 +1,110 @@
+//! Prometheus storage directory creation step
+//!
+//! This module provides the `CreatePrometheusStorageStep` which handles creation
+//! of the required directory structure for Prometheus on remote hosts
+//! via Ansible playbooks. This step ensures Prometheus has the necessary
+//! directories for configuration files.
+//!
+//! ## Key Features
+//!
+//! - Creates standardized directory structure for Prometheus storage
+//! - Sets appropriate ownership and permissions
+//! - Idempotent operation (safe to run multiple times)
+//! - Only executes when Prometheus is enabled in environment configuration
+//!
+//! ## Directory Structure
+//!
+//! The step creates the following directory hierarchy:
+//! ```text
+//! /opt/torrust/storage/prometheus/
+//! └── etc/           # Configuration files (prometheus.yml)
+//! ```
+
+use std::sync::Arc;
+use tracing::{info, instrument};
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::shared::command::CommandError;
+
+/// Step that creates Prometheus storage directories on a remote host via Ansible
+///
+/// This step creates the necessary directory structure for Prometheus,
+/// ensuring all directories have correct ownership and permissions.
+pub struct CreatePrometheusStorageStep {
+    ansible_client: Arc<AnsibleClient>,
+}
+
+impl CreatePrometheusStorageStep {
+    /// Create a new Prometheus storage directory creation step
+    ///
+    /// # Arguments
+    ///
+    /// * `ansible_client` - Ansible client for running playbooks
+    #[must_use]
+    pub fn new(ansible_client: Arc<AnsibleClient>) -> Self {
+        Self { ansible_client }
+    }
+
+    /// Execute the storage directory creation
+    ///
+    /// Runs the Ansible playbook that creates the Prometheus storage directory structure.
+    ///
+    /// # Errors
+    ///
+    /// Returns `CommandError` if:
+    /// - Ansible playbook execution fails
+    /// - Directory creation fails on remote host
+    /// - Permission setting fails
+    #[instrument(
+        name = "create_prometheus_storage",
+        skip_all,
+        fields(step_type = "system", component = "prometheus", method = "ansible")
+    )]
+    pub fn execute(&self) -> Result<(), CommandError> {
+        info!(
+            step = "create_prometheus_storage",
+            action = "create_directories",
+            "Creating Prometheus storage directory structure"
+        );
+
+        match self
+            .ansible_client
+            .run_playbook("create-prometheus-storage", &[])
+        {
+            Ok(_) => {
+                info!(
+                    step = "create_prometheus_storage",
+                    status = "success",
+                    "Prometheus storage directories created successfully"
+                );
+                Ok(())
+            }
+            Err(e) => {
+                tracing::error!(
+                    step = "create_prometheus_storage",
+                    error = %e,
+                    "Failed to create Prometheus storage directories"
+                );
+                Err(e)
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use tempfile::TempDir;
+
+    use super::*;
+
+    #[test]
+    fn it_should_create_prometheus_storage_step() {
+        let temp_dir = TempDir::new().expect("Failed to create temp dir");
+        let ansible_client = Arc::new(AnsibleClient::new(temp_dir.path().to_path_buf()));
+
+        let step = CreatePrometheusStorageStep::new(ansible_client);
+
+        // Step should be created successfully
+        assert!(!std::ptr::addr_of!(step).cast::<()>().is_null());
+    }
+}