mirror of
https://github.com/ghndrx/argus.git
synced 2026-02-10 06:45:04 +00:00
feat: initial Argus - AI-powered FinOps agent
Argus is an all-seeing eye on your AWS costs: - Scan for optimization opportunities (unused resources, oversized instances) - Evaluate Terraform plans for cost impact - Generate weekly/monthly cost reports - Integrate with Atlantis for pre-apply cost analysis Components: - CLI tool (argus scan/evaluate/report) - GitHub Action for CI/CD integration - AWS Scanner for resource analysis - AI engine for intelligent recommendations Features: - Unused EBS volumes, idle EC2, oversized RDS - Cost delta on Terraform changes - Atlantis integration - Slack/email notifications
This commit is contained in:
Argus Bot
292
README.md
Normal file
292
README.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Argus
|
||||
|
||||
**AI-powered FinOps agent for AWS** — Find waste, optimize costs, evaluate changes.
|
||||
|
||||
[](LICENSE)
|
||||
|
||||
## What is Argus?
|
||||
|
||||
Argus is an all-seeing eye on your AWS costs. It uses AI to:
|
||||
|
||||
- 🔍 **Find waste** — Unused resources, oversized instances, missing reservations
|
||||
- 💰 **Estimate impact** — Cost analysis on Terraform changes before you apply
|
||||
- 🤖 **Auto-optimize** — Generate PRs to fix inefficiencies
|
||||
- 📊 **Report trends** — Weekly/monthly cost reports with actionable insights
|
||||
|
||||
## Features
|
||||
|
||||
### Standalone Mode
|
||||
Run Argus on a schedule to continuously find savings:
|
||||
|
||||
```bash
|
||||
# Weekly cost report
|
||||
argus report --period weekly
|
||||
|
||||
# Find all optimization opportunities
|
||||
argus scan --output recommendations.md
|
||||
|
||||
# Auto-fix with PR
|
||||
argus fix --create-pr
|
||||
```
|
||||
|
||||
### Atlantis Integration
|
||||
Add cost analysis to your Terraform PR workflow:
|
||||
|
||||
```yaml
|
||||
# atlantis.yaml
|
||||
workflows:
|
||||
default:
|
||||
plan:
|
||||
steps:
|
||||
- init
|
||||
- plan
|
||||
- run: argus evaluate --plan-file $PLANFILE
|
||||
```
|
||||
|
||||
**Result:**
|
||||
```
|
||||
💰 Argus Cost Analysis
|
||||
|
||||
This PR will change your monthly spend:
|
||||
|
||||
+ aws_rds_cluster.main +$680/mo
|
||||
+ aws_nat_gateway.private +$32/mo
|
||||
- aws_instance.deprecated -$45/mo
|
||||
─────────────────────────────────────────
|
||||
Net Impact: +$667/mo (+15%)
|
||||
|
||||
⚠️ Suggestions:
|
||||
• Consider db.r5.large instead of xlarge (-$340/mo)
|
||||
• VPC endpoints could replace NAT for S3 traffic
|
||||
```
|
||||
|
||||
### GitHub Action
|
||||
Use Argus as a GitHub Action:
|
||||
|
||||
```yaml
|
||||
- uses: ghndrx/argus-action@v1
|
||||
with:
|
||||
aws-role-arn: ${{ secrets.AWS_ROLE_ARN }}
|
||||
mode: evaluate # or 'scan', 'report'
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install
|
||||
|
||||
```bash
|
||||
# Via pip
|
||||
pip install argus-finops
|
||||
|
||||
# Via Docker
|
||||
docker pull ghcr.io/ghndrx/argus:latest
|
||||
|
||||
# Via GitHub Action
|
||||
uses: ghndrx/argus-action@v1
|
||||
```
|
||||
|
||||
### 2. Configure AWS Access
|
||||
|
||||
```bash
|
||||
# Option A: IAM Role (recommended)
|
||||
export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/argus
|
||||
|
||||
# Option B: Environment variables
|
||||
export AWS_ACCESS_KEY_ID=...
|
||||
export AWS_SECRET_ACCESS_KEY=...
|
||||
```
|
||||
|
||||
### 3. Configure AI Provider
|
||||
|
||||
```bash
|
||||
# AWS Bedrock (recommended)
|
||||
export ARGUS_AI_PROVIDER=bedrock
|
||||
export ARGUS_AI_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
|
||||
|
||||
# Or OpenAI
|
||||
export ARGUS_AI_PROVIDER=openai
|
||||
export OPENAI_API_KEY=...
|
||||
```
|
||||
|
||||
### 4. Run
|
||||
|
||||
```bash
|
||||
# Generate cost report
|
||||
argus report
|
||||
|
||||
# Scan for optimizations
|
||||
argus scan
|
||||
|
||||
# Evaluate a Terraform plan
|
||||
argus evaluate --plan-file tfplan.json
|
||||
```
|
||||
|
||||
## What Argus Finds
|
||||
|
||||
| Category | Examples | Typical Savings |
|
||||
|----------|----------|-----------------|
|
||||
| **Unused Resources** | Unattached EBS, idle load balancers, orphaned snapshots | 10-20% |
|
||||
| **Oversized Instances** | EC2, RDS, ElastiCache running at <20% utilization | 20-40% |
|
||||
| **Missing Reservations** | Steady-state workloads without RIs or Savings Plans | 30-60% |
|
||||
| **Architecture Issues** | NAT Gateway for S3 traffic, cross-AZ data transfer | 5-15% |
|
||||
| **Storage Optimization** | S3 lifecycle policies, EBS type optimization | 10-30% |
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# argus.yaml
|
||||
scan:
|
||||
regions:
|
||||
- us-east-1
|
||||
- us-west-2
|
||||
exclude_tags:
|
||||
- Key: argus-ignore
|
||||
Value: "true"
|
||||
|
||||
thresholds:
|
||||
idle_cpu_percent: 10
|
||||
idle_days: 14
|
||||
min_savings_to_report: 10 # dollars
|
||||
|
||||
notifications:
|
||||
slack_webhook: https://hooks.slack.com/...
|
||||
email: finops@company.com
|
||||
|
||||
ai:
|
||||
provider: bedrock
|
||||
model: anthropic.claude-3-5-sonnet-20241022-v2:0
|
||||
```
|
||||
|
||||
## Atlantis Integration
|
||||
|
||||
### Setup
|
||||
|
||||
1. Add Argus to your Atlantis server
|
||||
2. Configure the workflow:
|
||||
|
||||
```yaml
|
||||
# atlantis.yaml
|
||||
workflows:
|
||||
default:
|
||||
plan:
|
||||
steps:
|
||||
- init
|
||||
- plan
|
||||
- run: |
|
||||
argus evaluate \
|
||||
--plan-file $PLANFILE \
|
||||
--output-format github-comment \
|
||||
> $OUTPUT_FILE
|
||||
apply:
|
||||
steps:
|
||||
- apply
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Developer opens PR with Terraform changes
|
||||
2. Atlantis runs `terraform plan`
|
||||
3. Argus analyzes the plan:
|
||||
- Calculates cost delta
|
||||
- Identifies optimization opportunities
|
||||
- Checks for cost policy violations
|
||||
4. Argus comments on PR with findings
|
||||
5. Team reviews cost impact before merge
|
||||
|
||||
## GitHub Action
|
||||
|
||||
### Evaluate PR Changes
|
||||
|
||||
```yaml
|
||||
name: Argus Cost Check
|
||||
on: [pull_request]
|
||||
|
||||
jobs:
|
||||
cost-check:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
pull-requests: write
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: aws-actions/configure-aws-credentials@v4
|
||||
with:
|
||||
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
|
||||
aws-region: us-east-1
|
||||
|
||||
- uses: hashicorp/setup-terraform@v3
|
||||
|
||||
- run: terraform init && terraform plan -out=tfplan
|
||||
|
||||
- uses: ghndrx/argus-action@v1
|
||||
with:
|
||||
mode: evaluate
|
||||
plan-file: tfplan
|
||||
comment-on-pr: true
|
||||
```
|
||||
|
||||
### Scheduled Cost Report
|
||||
|
||||
```yaml
|
||||
name: Weekly Cost Report
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 9 * * 1' # Monday 9am
|
||||
|
||||
jobs:
|
||||
report:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: ghndrx/argus-action@v1
|
||||
with:
|
||||
mode: report
|
||||
period: weekly
|
||||
slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Argus │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Scanner │ │ Evaluator │ │ Reporter │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • AWS APIs │ │ • TF Plans │ │ • Markdown │ │
|
||||
│ │ • Usage │ │ • Cost Calc │ │ • Slack │ │
|
||||
│ │ • Pricing │ │ • AI Review │ │ • Email │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
||||
│ │ │ │ │
|
||||
│ └────────────────┼────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────┐ │
|
||||
│ │ AI Engine │ │
|
||||
│ │ (Bedrock) │ │
|
||||
│ └─────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [x] Cost evaluation on Terraform plans
|
||||
- [x] AWS resource scanning
|
||||
- [x] Atlantis integration
|
||||
- [x] GitHub Action
|
||||
- [ ] Slack bot interface
|
||||
- [ ] Multi-cloud (GCP, Azure)
|
||||
- [ ] Cost anomaly detection
|
||||
- [ ] Budget enforcement policies
|
||||
- [ ] Recommendation auto-apply
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
## License
|
||||
|
||||
Apache 2.0 - See [LICENSE](LICENSE)
|
||||
Reference in New Issue
Block a user