AWS EBS Unattached Volume FinOps Auditor

id: aws-ebs-unattached-volume-snapshot-and-prune
namespace: company.team
description: |
  Automated Amazon EBS storage FinOps auditor. Scans AWS EC2 volumes in available (unattached) status
  exceeding retention thresholds, computes monthly storage waste, and prepares snapshot-and-prune advisories.

concurrency:
  limit: 1

inputs:
  - id: aws_region
    type: STRING
    displayName: AWS Region
    defaults: "us-east-1"
    description: "Target AWS Region to inspect for detached EBS storage volumes."

  - id: unattached_days_threshold
    type: INT
    displayName: Detached Days Threshold
    defaults: 14
    description: "Minimum days an EBS volume must be in available status before
      triggering an advisory alert."

  - id: ebs_gp3_price_per_gb_month
    type: FLOAT
    displayName: EBS Price Per GB Month
    defaults: 0.08
    description: "Estimated monthly dollar cost per gigabyte for Amazon EBS gp3 storage."

  - id: slack_channel
    type: STRING
    displayName: Slack Channel
    defaults: "#finops-alerts"
    description: "Slack channel destination for storage cost reclamation alerts."

triggers:
  - id: weekly_ebs_audit
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Executes unattached EBS volume audit weekly on Monday at 08:00 UTC."
    cron: "0 8 * * 1"

tasks:
  - id: scan_unattached_volumes
    type: io.kestra.plugin.scripts.python.Script
    description: "Queries AWS EC2 describe_volumes API to identify detached
      available volumes and calculate wasted storage."
    containerImage: python:3.11-slim
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    beforeCommands:
      - pip install boto3
    env:
      AWS_ACCESS_KEY_ID: "{{ secret('AWS_ACCESS_KEY_ID') }}"
      AWS_SECRET_ACCESS_KEY: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
      AWS_DEFAULT_REGION: "{{ inputs.aws_region }}"
    outputFiles:
      - ebs_audit_report.json
    script: |
      import os
      import json
      from datetime import datetime, timezone
      import boto3
      from kestra import Kestra

      ec2 = boto3.client("ec2")
      # Query for volumes in available (unattached) status
      response = ec2.describe_volumes(
          Filters=[{"Name": "status", "Values": ["available"]}]
      )

      volumes = response.get("Volumes", [])
      unattached_candidates = []
      now = datetime.now(timezone.utc)
      days_threshold = int("{{ inputs.unattached_days_threshold }}")
      price_per_gb = float("{{ inputs.ebs_gp3_price_per_gb_month }}")
      total_wasted_gb = 0

      for v in volumes:
          vol_id = v.get("VolumeId", "unknown")
          size_gb = v.get("Size", 0)
          vol_type = v.get("VolumeType", "gp3")
          create_time = v.get("CreateTime")

          age_days = (now - create_time).days if create_time else 0

          if age_days >= days_threshold:
              monthly_cost = round(size_gb * price_per_gb, 2)
              unattached_candidates.append({
                  "volume_id": vol_id,
                  "size_gb": size_gb,
                  "volume_type": vol_type,
                  "age_days": age_days,
                  "monthly_cost_usd": monthly_cost
              })
              total_wasted_gb += size_gb

      has_unattached = len(unattached_candidates) > 0
      total_monthly_waste = round(total_wasted_gb * price_per_gb, 2)

      report = {
          "region": os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
          "total_available_volumes": len(volumes),
          "flagged_volumes_count": len(unattached_candidates),
          "total_wasted_gb": total_wasted_gb,
          "total_monthly_waste_usd": total_monthly_waste,
          "volumes": unattached_candidates,
          "has_unattached": has_unattached
      }

      with open("ebs_audit_report.json", "w", encoding="utf-8") as f:
          json.dump(report, f, indent=2)

      Kestra.outputs({
          "has_unattached": has_unattached,
          "flagged_count": len(unattached_candidates),
          "total_wasted_gb": total_wasted_gb,
          "total_monthly_waste_usd": total_monthly_waste,
          "top_volume_id": unattached_candidates[0]["volume_id"] if unattached_candidates else "None",
          "top_volume_size": unattached_candidates[0]["size_gb"] if unattached_candidates else 0
      })

  - id: evaluate_unattached_volumes
    type: io.kestra.plugin.core.flow.If
    description: "Evaluates if any detached EBS volumes exceeded the age threshold."
    condition: "{{ outputs.scan_unattached_volumes.vars.has_unattached }}"
    then:
      - id: notify_slack_storage_team
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: "Dispatches actionable storage cleanup advisory to Slack."
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "channel": "{{ inputs.slack_channel }}",
            "text": "*AWS Cloud FinOps Alert: Unattached EBS Volumes Detected*\n• *AWS Region*: `{{ inputs.aws_region }}`\n• *Detached Volumes Count*: {{ outputs.scan_unattached_volumes.vars.flagged_count }} (Detached > {{ inputs.unattached_days_threshold }} days)\n• *Total Orphaned Storage*: {{ outputs.scan_unattached_volumes.vars.total_wasted_gb }} GB (~${{ outputs.scan_unattached_volumes.vars.total_monthly_waste_usd }} USD/month)\n• *Top Waste Candidate*: Volume `{{ outputs.scan_unattached_volumes.vars.top_volume_id }}` ({{ outputs.scan_unattached_volumes.vars.top_volume_size }} GB)\n• *Operational Impact*: AWS charges full provisioned EBS gigabyte rates regardless of whether volumes are attached to running EC2 instances.\n• *Recommended Remediation*: Take a final safety snapshot via `aws ec2 create-snapshot --volume-id {{ outputs.scan_unattached_volumes.vars.top_volume_id }}` and delete the unattached volume to eliminate recurring storage fees."
          }

    else:
      - id: log_clean_ebs_status
        type: io.kestra.plugin.core.log.Log
        description: "Logs confirmation of zero orphaned EBS storage volumes."
        message: "AWS EBS storage audit compliant for {{ inputs.aws_region }}. Zero
          detached volumes found exceeding {{ inputs.unattached_days_threshold
          }} days."

  - id: export_ebs_manifest
    type: io.kestra.plugin.core.debug.Return
    description: "Outputs structured JSON execution manifest for FinOps historical
      reporting."
    format: |
      {
        "pipeline": "aws-ebs-unattached-volume-snapshot-and-prune",
        "audited_at": "{{ execution.startDate }}",
        "region": "{{ inputs.aws_region }}",
        "volumes_flagged": {{ outputs.scan_unattached_volumes.vars.flagged_count }},
        "wasted_gb": {{ outputs.scan_unattached_volumes.vars.total_wasted_gb }},
        "monthly_waste_usd": {{ outputs.scan_unattached_volumes.vars.total_monthly_waste_usd }},
        "status": "{{ outputs.scan_unattached_volumes.vars.has_unattached ? 'ORPHANED_STORAGE_DETECTED' : 'OPTIMIZED' }}"
      }