# CloudZero Billing Generator (CZBG)

Generate and upload synthetic cloud billing data to CloudZero organizations. Built for CloudZero sales engineers and demo teams.

## Quick Start

```bash
# 1. Install
pipx install cz-billing-generator

# 2. Set up credentials (see Getting Started)
# Edit ~/.czbg/.env with credentials from 1Password (Demo vault)

# 3. Download configs
czbg config download

# 4. Run your first job via API
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml

# 5. Time-shift data to different months
czbg upload time-shift --config czbg-configs/upload/time-shift/production-2025-to-2026.yaml
```

**New to CZBG?** → [Getting Started Guide](docs/GETTING_STARTED.md)

## What is CZBG?

CZBG generates realistic synthetic cloud billing data for CloudZero demos and testing:

- **Multi-Cloud**: AWS, Azure, GCP, and 10+ SaaS providers
- **Realistic Data**: Behavioral variance, anomalies, seasonal patterns
- **API-First**: Serverless execution via Lambda + ECS (v2.0+)
- **Full Pipeline**: Generate → K8s → Metadata → Usage → Discount → Upload

**Default execution is now via API** - jobs run on serverless infrastructure, not your local machine. Use `--local` flag for local debugging.

## Installation

**Prerequisites:**
- Python 3.10+
- AWS SSO access (cz-test-env-1)
- CloudZero API credentials

**Install:**
```bash
pipx install cz-billing-generator
```

**Upgrade to latest:**
```bash
pipx upgrade cz-billing-generator
```

## Core Workflows

### Generate Billing Data

```bash
# Generate base AWS billing data (via API)
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml

# Generate locally for debugging
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml --local
```

### Enrich with K8s Allocation

```bash
# Add Kubernetes allocations to existing dataset
czbg k8s run --config czbg-configs/k8s/production/config.k8s.yaml
```

### Add Metadata (Tags, Resource IDs)

```bash
# Inject tags and resource metadata
czbg metadata run --config czbg-configs/metadata/production/config.metadata.yaml
```

### Apply Usage & Discounts

```bash
# Convert costs to usage metrics
czbg usage run --config czbg-configs/usage/production/config.usage.yaml

# Apply cloud discounts
czbg discount run --config czbg-configs/discount/production/config.discount.yaml
```

### Upload to CloudZero

```bash
# Upload generated data to organizations
czbg upload generated --config czbg-configs/upload/production/production.upload.yaml

# Time-shift data to different months (bulk operation)
czbg upload time-shift --config czbg-configs/upload/time-shift/production-2025-to-2026.yaml
```

### Monitor Jobs

```bash
# List all jobs
czbg jobs list

# Check job status
czbg jobs describe <job-id>
```

## Configuration Management

```bash
# Download all configs from S3
czbg config download

# Download specific stage configs
czbg config download --prefix czbillgen/configs/generate/

# List available configs in S3
czbg config list
```

## Documentation

### By User Type

**👤 New Users** → [Getting Started](docs/GETTING_STARTED.md)
*Step-by-step setup and first workflows*

**📊 Sales Engineers** → [API Workflows](docs/user-guides/api-workflows.md)
*Common demo scenarios and API execution*

**🔧 Config Writers** → [Generate Config Guide](docs/reference/generate-config-writing-guide.md)
*Creating custom billing scenarios*

**💻 Developers** → [Development Guide](docs/development/README.md)
*Contributing and architecture*

### Quick References

- [Command Reference](docs/reference/commands.md) - All CLI commands
- [Configuration Reference](docs/reference/configuration.md) - YAML config formats
- [Troubleshooting](docs/reference/troubleshooting.md) - Common issues
- [Complete Documentation](docs/README.md) - Full documentation hub

## Key Features

### v2.0 - API-First Architecture

**Breaking Change:** All commands now execute via API by default (Lambda + ECS workers).

- ✅ **Serverless execution** - No local processing required
- ✅ **Auto-scaling** - Workers scale based on job queue
- ✅ **Job tracking** - Monitor progress via DynamoDB
- ✅ **Works anywhere** - Run from any machine with CLI access

Use `--local` flag to opt-in to local execution for development/debugging.

### Multi-Stage Pipeline

```
Generate → K8s → Metadata → Usage → Discount → Upload
```

Each stage enriches billing data:
- **Generate**: Base cloud billing costs
- **K8s**: Kubernetes allocation and workload mapping
- **Metadata**: Tags, regions, resource IDs
- **Usage**: Usage metrics with realistic rates
- **Discount**: Cloud savings plans and discounts
- **Upload**: Stream to CloudZero organizations

### Time-Shift Capability

Move generated data to different time periods:
- Copy Nov 2025 data → Nov 2026
- Preserves all metadata, K8s allocations, and anomalies
- Parallel processing by provider (AWS, Azure, GCP)

## Support

**📚 Documentation**: [Complete docs](docs/README.md)
**💬 Internal**: CloudZero Slack #demo-environment
**🐛 Issues**: [GitHub Issues](https://github.com/cloudzero/cz-billing-generator/issues)

## Quick Help

```bash
# Get help for any command
czbg --help
czbg generate --help
czbg upload --help

# Check version
czbg jobs list  # Version shown in output
```

---

**Current Version:** 2.0.0
**License:** Proprietary - CloudZero Internal Use Only
**Maintainer:** CloudZero Demo Engineering Team
