# Cloud Instance Query Tool

A unified tool to query instance type metadata across AWS, Azure, GCP, and Alibaba Cloud with consistent filtering and output formats.

## Features

- **Multi-Cloud Support**: Query AWS, Azure, GCP, and Alibaba Cloud from a single tool
- **Unified Data Structure**: Consistent instance data format across all providers
- **Smart Caching**: File-based caching to avoid repeated downloads
- **Powerful Filtering**: Regex-based type filtering, family filtering, vCPU/memory filters
- **Sorting**: Optional sorting by price, vCPU, or memory
- **Multiple Output Formats**: Table, JSON, YAML output formats
- **Flexible Query Modes**: Download fresh data, use cache, or both

## Installation

```bash
# Download dependencies
go mod tidy

# Build the tool
go build -o cloud-instances main.go
```

## Quick Start

### List Available Providers
```bash
./cloud-instances --list-providers
```

### List Regions for a Provider
```bash
./cloud-instances --provider aws --list-regions
./cloud-instances --provider azure --list-regions
./cloud-instances --provider aliyun --list-regions
```

### Download Data (Cache Mode)
```bash
# Download AWS data for us-east-1
./cloud-instances --provider aws --region us-east-1 --download

# Download Azure data (global metadata)
./cloud-instances --provider azure --download

# Download Alibaba Cloud data (requires credentials)
./cloud-instances --provider aliyun --region cn-hangzhou --download
```

### Query with Filters

#### AWS Examples
```bash
# Query all AWS instances in us-east-1
./cloud-instances --provider aws --region us-east-1 --format table

# Sort by price (lowest to highest)
./cloud-instances --provider aws --region us-east-1 --format table --sort price

# Filter by instance type regex (r7g instances)
./cloud-instances --provider aws --type "^r7g" --format table

# Filter by family and vCPU
./cloud-instances --provider aws --family "Memory optimized" --vcpu "64" --format json

# Filter by memory
./cloud-instances --provider aws --memory "128 GiB" --format table

# Filter by local instance storage
./cloud-instances --provider aws --local-storage --format table

# Price range filtering
./cloud-instances --provider aws --min-price 1.0 --max-price 5.0 --format table

# Multiple filters combined
./cloud-instances --provider aws --type "^m" --vcpu "16" --memory "64 GiB" --format json --details
```

#### Azure Examples
```bash
# Query Azure instances (metadata only, no prices)
./cloud-instances --provider azure --format table

# Filter by instance family
./cloud-instances --provider azure --family "Memory optimized" --format table

# Filter by type prefix
./cloud-instances --provider azure --type "^D" --format json
```

#### Alibaba Cloud Examples
```bash
# Query with SDK (requires ALICLOUD_ACCESS_KEY and ALICLOUD_SECRET_KEY)
./cloud-instances --provider aliyun --region cn-hangzhou --download

# Query from cache
./cloud-instances --provider aliyun --region cn-hangzhou --from-cache --format table

# Filter Alibaba instances
./cloud-instances --provider aliyun --type "^ecs.g" --format json
```

#### Multi-Provider Queries
```bash
# Query all providers
./cloud-instances --provider all --format table

# Filter across all providers
./cloud-instances --provider all --memory "32 GiB" --format json

# Family filter across all providers
./cloud-instances --provider all --family "General purpose" --format table
```

### Cache Management

#### View Cache Information
```bash
# Show cached files for a provider
./cloud-instances --provider aws --cache-info
```

#### Clear Cache
```bash
# Clear all AWS cache
./cloud-instances --provider aws --clear-cache

# Clear specific region
./cloud-instances --provider aws --region us-east-1 --clear-cache
```

#### Use Cache Only (No Downloads)
```bash
./cloud-instances --provider aws --from-cache --type "^r7g"
```

### Advanced Options

#### Force Download (Ignore Cache)
```bash
./cloud-instances --provider aws --region us-east-1 --force-download --download
```

#### Download Only (No Analysis)
```bash
./cloud-instances --provider aws --region us-east-1 --download-only
```

#### Custom Cache Directory
```bash
./cloud-instances --provider aws --cache-dir /tmp/my-cache --download
```

#### Output Styles
```bash
# Pretty format (default)
./cloud-instances --provider aws --format table --style pretty

# Compact format
./cloud-instances --provider aws --format table --style compact

# Full details
./cloud-instances --provider aws --details --format table
```

## Command Reference

### Provider Selection
- `--provider <name>`: Select provider (aws, azure, gcp, aliyun, all)
- `--region <id>`: Specify region(s), comma-separated for multiple
- `--list-providers`: List all available providers
- `--list-regions`: List regions for selected provider

### Download Options
- `--download`: Download data and cache it
- `--download-only`: Download only, no analysis
- `--force-download`: Force download even if cache exists
- `--cache-dir <path>`: Specify cache directory (default: current directory)

### Query Filters
- `--type <regex>`: Filter by instance type regex (e.g., `^r7g`)
- `--family <name>`: Filter by instance family (e.g., `Memory optimized`)
- `--vcpu <count>`: Filter by vCPU count (e.g., `64`)
- `--memory <size>`: Filter by memory (e.g., `32 GiB`)
- `--local-storage`: Filter instances with local disk (instance storage)
- `--instance-storage`: Alias for `--local-storage`
- `--no-local-storage`: Filter instances without local disk
- `--min-price <value>`: Minimum price filter
- `--max-price <value>`: Maximum price filter
- `--from-cache`: Use only cached data

### Output Options
- `--format <type>`: Output format (table, json, yaml, all)
- `--style <style>`: Output style (pretty, compact)
- `--sort <field>`: Sort by `price`, `vcpu`, or `memory` (default: no sorting)
- `--details`: Include full details in output

### Cache Management
- `--cache-info`: Show cache information
- `--clear-cache`: Clear cache for provider/region

## Configuration

### AWS
No credentials required - uses public pricing API.

### Azure
Requires authentication for metadata (Compute Resource SKUs API).

Environment variables:
```bash
export AZURE_ACCESS_TOKEN="your-access-token"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
# OR service principal
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
```

CLI overrides:
```bash
./cloud-instances --provider azure --region eastus --download \\
  --azure-access-token "$AZURE_ACCESS_TOKEN" \\
  --azure-subscription-id "$AZURE_SUBSCRIPTION_ID"
```

SSO via Azure CLI:
```bash
./cloud-instances --provider azure --region eastus --download --azure-sso
```

### Alibaba Cloud
Requires authentication credentials. Set environment variables:
```bash
export ALICLOUD_ACCESS_KEY="your-access-key"
export ALICLOUD_SECRET_KEY="your-secret-key"
export ALICLOUD_SECURITY_TOKEN="your-security-token"  # Optional, for STS
```

CLI overrides:
```bash
./cloud-instances --provider aliyun --region cn-hangzhou --download \\
  --aliyun-access-key "$ALICLOUD_ACCESS_KEY" \\
  --aliyun-secret-key "$ALICLOUD_SECRET_KEY" \\
  --aliyun-security-token "$ALICLOUD_SECURITY_TOKEN"
```

If Aliyun endpoints are slow, increase the request timeout:
```bash
./cloud-instances --provider aliyun --region us-west-1 --download --aliyun-timeout 90s
```

SSO via Alibaba Cloud CLI config:
```bash
./cloud-instances --provider aliyun --region cn-hangzhou --download --aliyun-sso
```

### GCP
Requires authentication for metadata (Compute Engine API) and pricing (Cloud Billing Catalog API).

Environment variables:
```bash
export GCP_PROJECT_ID="your-project-id"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# Optional for billing API if using API key
export GCP_API_KEY="your-api-key"
```

CLI overrides:
```bash
./cloud-instances --provider gcp --region us-central1 --download \\
  --gcp-project-id "$GCP_PROJECT_ID" \\
  --gcp-credentials "$GOOGLE_APPLICATION_CREDENTIALS" \\
  --gcp-api-key "$GCP_API_KEY"
```

SSO via gcloud CLI:
```bash
./cloud-instances --provider gcp --region us-central1 --download --gcp-sso
```

## Output Formats

### Table Format
```
Provider  Instance Type      Family              vCPU  Memory    Storage     Price    Region
aws       r7g.16xlarge       Memory optimized    64    512 GiB   EBS only    2.688    us-east-1
aws       r7g.8xlarge        Memory optimized    32    256 GiB   EBS only    1.344    us-east-1
```

### JSON Format
```json
[
  {
    "provider": "aws",
    "instance_type": "r7g.16xlarge",
    "instance_family": "Memory optimized",
    "vcpu": "64",
    "memory": "512 GiB",
    "storage": "EBS only",
    "network_performance": "20 Gigabit",
    "price": 2.688,
    "location": "US East (N. Virginia)",
    "region": "us-east-1"
  }
]
```

### YAML Format
```yaml
- provider: aws
  instance_type: r7g.16xlarge
  instance_family: Memory optimized
  vcpu: "64"
  memory: "512 GiB"
  storage: EBS only
  network_performance: 20 Gigabit
  price: 2.688
  location: US East (N. Virginia)
  region: us-east-1
```

## Architecture

### File Structure
```
cloud-instances/
├── main.go                    # CLI entry point
├── provider/
│   ├── interface.go          # CloudProvider interface
│   ├── aws.go                # AWS provider implementation
│   ├── azure.go              # Azure provider implementation
│   └── aliyun.go             # Alibaba Cloud provider implementation
├── cache/
│   └── manager.go            # Cache management
├── query/
│   └── engine.go             # Query and filter logic
├── output/
│   └── formatter.go          # Output formatting
├── types/
│   └── unified.go            # Unified data structures
├── regions/
│   ├── aws.go                # AWS region mappings
│   ├── azure.go              # Azure region mappings
│   └── aliyun.go             # Alibaba Cloud region mappings
├── go.mod                    # Go module dependencies
└── README.md                 # This file
```

### Cache Files
Cache files are named: `{provider}_{region}.json`
- `aws_us-east-1.json`
- `azure_eastus.json`
- `aliyun_cn-hangzhou.json`

## Examples

### Complete Workflow
```bash
# 1. Download data for multiple regions
./cloud-instances --provider aws --region us-east-1,us-west-2 --download
./cloud-instances --provider azure --download

# 2. Query with filters
./cloud-instances --provider aws --type "^r7g" --vcpu "64" --format table

# 3. Cross-provider query
./cloud-instances --provider all --memory "64 GiB" --format json

# 4. Check cache age
./cloud-instances --provider aws --cache-info

# 5. Refresh cache
./cloud-instances --provider aws --region us-east-1 --force-download --download
```

### Performance Tips
- Use `--from-cache` for fast queries after initial download
- Download only needed regions with `--region`
- Use specific filters to reduce output size
- Cache directory can be on fast storage (SSD)

## Troubleshooting

### "Cache not found"
Solution: Run with `--download` first to populate cache

### "Invalid region"
Solution: Use `--list-regions` to see valid regions for provider

### "Alibaba Cloud credentials not found"
Solution: Set environment variables or provide credentials in code

### "HTTP error" when downloading
Solution: Check network connectivity and API availability

### Empty results
Solution:
- Check if cache exists with `--cache-info`
- Verify filters are correct
- Try without filters to see all data

## Notes

- Azure data is metadata-only (no pricing information)
- GCP provider is not yet implemented
- All code uses English-only comments and variable names
- Cache files can be shared between users (read-only)
- Tool preserves all features from original ec2.go

## License

This tool is provided as-is for cloud infrastructure analysis.