syalioune/gcp-finops-sentinel repository overview

# Pull the latest image
docker pull syalioune/gcp-finops-sentinel:latest

# Run with basic configuration
docker run -p 8080:8080 \
  -e ORGANIZATION_ID=123456789012 \
  -e RULES_CONFIG='{"rules":[{"name":"budget_alert","conditions":{"threshold_percent":{"operator":">=","value":100}},"actions":[{"type":"log_only","message":"Budget exceeded"}]}]}' \
  -e DRY_RUN=true \
  syalioune/gcp-finops-sentinel:latest

{
  "rules": [
    {
      "name": "critical_budget_breach",
      "description": "Restrict compute when budget exceeds 100%",
      "conditions": {
        "threshold_percent": {
          "operator": ">=",
          "value": 100
        }
      },
      "actions": [
        {
          "type": "restrict_services",
          "target_projects": ["prod-web-1", "prod-api-1"],
          "services": ["compute.googleapis.com"]
        },
        {
          "type": "send_mail",
          "to_emails": ["[email protected]"],
          "template": "budget_alert",
          "custom_message": "Critical budget breach detected!"
        }
      ]
    }
  ]
}

rules:
  - name: tiered_response
    description: Graduated response based on budget thresholds
    conditions:
      # Range-based threshold: 80-89.99%
      threshold_percent:
        - operator: min
          value: 80
        - operator: max
          value: 89.99
      billing_account_filter: "012345-6789AB-CDEF01"
    actions:
      # Target projects by labels (dynamic discovery)
      - type: restrict_services
        target_labels:
          env: prod
          cost-center: engineering
        services:
          - compute.googleapis.com
          - container.googleapis.com

      # Apply constraint at folder level
      - type: apply_constraint
        target_folders:
          - "123456789012"
        constraint: compute.vmExternalIpAccess
        enforce: true

# Clone repository
git clone https://github.com/syalioune/gcp-finops-sentinel.git
cd gcp-finops-sentinel

# Start complete local environment
docker compose up -d

# Publish test budget alert (120% threshold)
export PUBSUB_EMULATOR_HOST=localhost:8681
python scripts/publish-budget-alert-event.py --cost-amount 1200 --budget-amount 1000

# View logs
docker compose logs -f budget-function

# View email notifications at http://localhost:8025

# Start Pub/Sub emulator
docker run -d --name pubsub-emulator \
  -p 8681:8681 \
  gcr.io/google.com/cloudsdktool/google-cloud-cli:emulators \
  gcloud beta emulators pubsub start --host-port=0.0.0.0:8681

# Start MailHog for email testing
docker run -d --name mailhog \
  -p 8025:8025 -p 1025:1025 \
  mailhog/mailhog

# Run FinOps Sentinel
docker run -d --name finops-sentinel \
  -p 8080:8080 \
  -e ORGANIZATION_ID=123456789012 \
  -e DRY_RUN=true \
  -e PUBSUB_EMULATOR_HOST=pubsub-emulator:8681 \
  -e SMTP_HOST=mailhog \
  -e SMTP_PORT=1025 \
  --link pubsub-emulator \
  --link mailhog \
  syalioune/gcp-finops-sentinel:latest

# View emails at http://localhost:8025

# Deploy with gcloud
gcloud run deploy gcp-finops-sentinel \
  --image=syalioune/gcp-finops-sentinel:latest \
  --platform=managed \
  --region=us-central1 \
  --set-env-vars="ORGANIZATION_ID=123456789012" \
  --set-secrets="RULES_CONFIG=finops-rules:latest" \
  --no-allow-unauthenticated

# Create Eventarc trigger for Pub/Sub
gcloud eventarc triggers create budget-alerts-trigger \
  --destination-run-service=gcp-finops-sentinel \
  --destination-run-region=us-central1 \
  --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
  --transport-topic=projects/YOUR_PROJECT/topics/budget-alerts

version: '3.8'
services:
  finops-sentinel:
    image: syalioune/gcp-finops-sentinel:latest
    ports:
      - "8080:8080"
    environment:
      - ORGANIZATION_ID=123456789012
      - DRY_RUN=true
      - LOG_LEVEL=DEBUG
    volumes:
      - ./rules.json:/workspace/rules.json:ro

resource "google_cloud_run_v2_service" "finops_sentinel" {
  name     = "gcp-finops-sentinel"
  location = "us-central1"

  template {
    service_account = google_service_account.finops_sentinel.email

    containers {
      image = "syalioune/gcp-finops-sentinel:latest"

      env {
        name  = "ORGANIZATION_ID"
        value = var.organization_id
      }

      env {
        name = "RULES_CONFIG"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.rules.secret_id
            version = "latest"
          }
        }
      }

      resources {
        limits = {
          cpu    = "1"
          memory = "512Mi"
        }
      }
    }
  }
}

# The container exposes port 8080
curl http://localhost:8080/

{
  "severity": "INFO",
  "message": "Processing budget alert",
  "budget_id": "budget-123",
  "threshold_percent": 120.5,
  "matched_rules": 2
}