# Backstage Tollgate-Scaffolder Integration

This document describes the complete integration between the Backstage Tollgate payment plugin and Scaffolder for enabling paid resource provisioning through Kubernetes operators.

## Overview

The Tollgate-Scaffolder integration provides a comprehensive solution for paid infrastructure provisioning that includes:

- **Subscription Validation**: Ensures users have active subscriptions before provisioning
- **Dynamic Pricing**: Calculates costs based on resource specifications and usage
- **Payment Processing**: Handles one-time payments through Stripe integration
- **Resource Provisioning**: Creates Kubernetes Custom Resources through operators
- **Cost Tracking**: Tracks deployment costs and integrates with billing systems

## Architecture Components

### 1. Custom Scaffolder Actions

The integration provides five custom Scaffolder actions:

#### `tollgate:validate-subscription`
Validates user subscription and checks access to required features.

**Input:**
- `userId`: User ID to validate subscription for
- `requiredTier`: Minimum subscription tier (basic, premium, enterprise)
- `requiredFeatures`: Array of required features

**Output:**
- `isValid`: Whether subscription is valid
- `subscriptionTier`: Current subscription tier
- `availableFeatures`: List of available features
- `remainingCredits`: Remaining usage credits
- `nextBillingDate`: Next billing date

#### `tollgate:calculate-price`
Calculates projected costs for resource specifications.

**Input:**
- `resources`: Array of resource specifications (CPU, memory, storage)
- `region`: Cloud region for deployment
- `duration`: Duration in hours for cost calculation
- `backupPlan`: Backup plan (none, basic, premium)
- `additionalFeatures`: Additional features (monitoring, logging, etc.)

**Output:**
- `totalCost`: Total cost for specified duration
- `monthlyCost`: Estimated monthly cost
- `breakdown`: Detailed cost breakdown by resource
- `currency`: Currency code (USD)
- `region`: Region used for pricing

#### `tollgate:create-payment-intent`
Creates a Stripe payment intent for one-time charges.

**Input:**
- `amount`: Payment amount in USD
- `userId`: User ID for the payment
- `description`: Payment description
- `metadata`: Additional metadata

**Output:**
- `paymentIntentId`: Stripe payment intent ID
- `clientSecret`: Client secret for frontend confirmation
- `paymentUrl`: URL for payment completion

#### `tollgate:confirm-payment`
Waits for payment confirmation and validates payment status.

**Input:**
- `paymentIntentId`: Stripe payment intent ID to confirm
- `timeoutMinutes`: Maximum wait time (default: 15 minutes)
- `pollIntervalSeconds`: Polling interval (default: 30 seconds)

**Output:**
- `status`: Final payment status
- `receiptUrl`: URL to payment receipt
- `amountReceived`: Amount received in USD
- `transactionId`: Transaction ID for record keeping

#### `kubernetes:create-cr`
Creates a Kubernetes Custom Resource through the operator.

**Input:**
- `apiVersion`: API version of the Custom Resource
- `kind`: Kind of the Custom Resource
- `name`: Name of the Custom Resource instance
- `namespace`: Kubernetes namespace
- `spec`: Custom Resource specification
- `metadata`: Additional metadata

**Output:**
- `resourceName`: Name of created resource
- `namespace`: Namespace where resource was created
- `uid`: Kubernetes UID of the resource
- `resourceVersion`: Resource version
- `status`: Creation status

### 2. Scaffolder Templates

#### WordPress Deployment Template (`wordpress-deployment`)

**Features:**
- Configurable WordPress and MySQL resources
- Environment-based sizing (development, staging, production)
- Backup plan selection (none, basic, premium)
- SSL certificate configuration
- Monitoring and logging options

**Pricing Tiers:**
- Development: $15-30/month
- Staging: $35-60/month
- Production: $70-150/month

**Workflow:**
1. Validate premium subscription
2. Calculate costs based on resource specifications
3. Create payment intent if cost > $100
4. Wait for payment confirmation
5. Create WordPress Custom Resource
6. Register component in catalog

#### Web Application Deployment Template (`web-app-deployment`)

**Features:**
- Container image or Git repository (S2I) deployment
- Auto-scaling configuration
- Optional database integration
- Ingress and SSL configuration
- Multiple build strategies (Node.js, Python, Java, etc.)

**Pricing Tiers:**
- Basic: $10-25/month
- Standard: $25-50/month
- Premium: $50-100/month

**Workflow:**
1. Validate basic subscription
2. Calculate costs for app and optional database
3. Create payment intent if cost > $50
4. Wait for payment confirmation
5. Create WebApp Custom Resource
6. Create Database Custom Resource (if needed)
7. Register component in catalog

### 3. Custom Resource Definitions (CRDs)

#### WordPress CRD (`wordpresses.apps.example.com`)
Defines WordPress deployments with MySQL backend, backup configuration, and monitoring.

#### WebApp CRD (`webapps.apps.example.com`)
Defines web application deployments supporting both container images and source-to-image builds.

#### Database CRD (`databases.data.example.com`)
Defines managed database instances with backup, monitoring, and security features.

## Configuration

### Backend Configuration

Add to `app-config.yaml`:

```yaml
tollgate:
  scaffolder:
    autoApprovalThreshold: 100
    defaultRegion: us-east-1
    pricing:
      cpuHourlyRate: 0.048
      memoryHourlyRate: 0.0067
      storageMonthlyRate: 0.10
      regionalMultipliers:
        us-east-1: 1.0
        us-west-2: 1.05
        eu-west-1: 1.15
    kubernetes:
      defaultNamespace: default
      clusterName: production-cluster
```

### Template Discovery

Add templates to catalog locations:

```yaml
catalog:
  locations:
    - type: file
      target: ../../templates/wordpress-deployment/template.yaml
    - type: file  
      target: ../../templates/web-app-deployment/template.yaml
```

## Integration Flow

### 1. Pre-Creation Validation

```yaml
steps:
  - id: validate-subscription
    name: Validate Subscription
    action: tollgate:validate-subscription
    input:
      userId: ${{ user.entity.metadata.name }}
      requiredTier: premium
      requiredFeatures:
        - kubernetes-deployment
        - custom-resources
```

### 2. Cost Calculation

```yaml
  - id: calculate-price
    name: Calculate Deployment Cost
    action: tollgate:calculate-price
    input:
      resources:
        - type: wordpress
          cpu: 2
          memory: 4
          storage: 5
          replicas: 2
      region: us-east-1
      duration: 720
      backupPlan: basic
```

### 3. Payment Processing

```yaml
  - id: cost-approval-gate
    name: Cost Approval Gate
    when: ${{ steps['calculate-price'].output.totalCost > 100 }}
    action: tollgate:create-payment-intent
    input:
      amount: ${{ steps['calculate-price'].output.totalCost }}
      userId: ${{ user.entity.metadata.name }}
      description: "WordPress deployment: ${{ parameters.name }}"

  - id: payment-confirmation
    name: Wait for Payment Confirmation
    when: ${{ steps['cost-approval-gate'].output.paymentIntentId }}
    action: tollgate:confirm-payment
    input:
      paymentIntentId: ${{ steps['cost-approval-gate'].output.paymentIntentId }}
      timeoutMinutes: 15
```

### 4. Resource Creation

```yaml
  - id: create-wordpress-cr
    name: Create WordPress Custom Resource
    action: kubernetes:create-cr
    input:
      apiVersion: apps.example.com/v1
      kind: WordPress
      name: ${{ parameters.name }}
      namespace: production
      spec:
        wordpress:
          image: wordpress:6.4
          resources:
            requests:
              cpu: "2"
              memory: "4Gi"
          replicas: 2
        mysql:
          image: mysql:8.0
          storage:
            size: "20Gi"
```

## Pricing Model

### Resource Pricing

| Resource Type | Unit | Price (USD/hour) |
|---------------|------|------------------|
| CPU Core | 1 core | $0.048 |
| Memory | 1 GB | $0.0067 |
| Storage | 1 GB/month | $0.10 |

### Regional Multipliers

| Region | Multiplier |
|--------|------------|
| us-east-1 | 1.0x |
| us-west-2 | 1.05x |
| eu-west-1 | 1.15x |
| ap-southeast-1 | 1.20x |

### Additional Features

| Feature | Cost |
|---------|------|
| Basic Backup | +5% of resource cost |
| Premium Backup | +15% of resource cost |
| Monitoring | +$10/month |
| Logging | +$15/month |
| SSL Certificates | +$10/month |
| Load Balancer | +$25/month |

## Security Considerations

### 1. Payment Data Security
- All payment processing handled through Stripe
- No payment data stored in Backstage
- Webhook signature verification required
- Environment-based secret management

### 2. Kubernetes Security
- Service account permissions for Custom Resource creation
- Namespace-based resource isolation
- RBAC integration with Backstage permissions
- Audit logging for all resource operations

### 3. Subscription Security
- Token-based authentication for API calls
- User identity verification before provisioning
- Subscription status validation on each request
- Rate limiting for cost calculations

## Monitoring and Observability

### 1. Cost Tracking
- All deployments tagged with cost information
- Integration with billing systems
- Monthly cost reports per user/team
- Budget alerts and notifications

### 2. Resource Monitoring
- Kubernetes resource utilization tracking
- Custom Resource status monitoring
- Deployment health checks
- Performance metrics collection

### 3. Payment Monitoring
- Payment success/failure tracking
- Fraud detection integration
- Chargeback handling
- Revenue reporting

## Error Handling

### 1. Subscription Validation Errors
- Clear error messages for subscription issues
- Upgrade prompts for insufficient tiers
- Feature availability notifications
- Billing status warnings

### 2. Payment Processing Errors
- Automatic retry for transient failures
- Clear payment failure reasons
- Alternative payment method suggestions
- Support contact information

### 3. Resource Creation Errors
- Kubernetes API error handling
- Resource quota limit notifications
- Namespace permission errors
- Operator availability checks

## Troubleshooting

### Common Issues

1. **Subscription validation fails**
   - Check user entity metadata
   - Verify subscription API connectivity
   - Review required tier configuration

2. **Payment processing timeout**
   - Increase timeout in template
   - Check Stripe webhook configuration
   - Verify payment intent status

3. **Custom Resource creation fails**
   - Verify CRD installation
   - Check namespace permissions
   - Review operator logs

4. **Cost calculation errors**
   - Validate pricing configuration
   - Check regional multipliers
   - Review resource specifications

### Debug Commands

```bash
# Check Scaffolder action logs
kubectl logs -n backstage deployment/backstage-backend -c backend | grep tollgate

# Verify Custom Resource creation
kubectl get wordpress,webapp,database -A

# Check payment status
curl -H "Authorization: Bearer $STRIPE_KEY" \
  https://api.stripe.com/v1/payment_intents/$PAYMENT_INTENT_ID
```

## Best Practices

### 1. Template Design
- Clear parameter validation
- Helpful descriptions and examples
- Sensible defaults for common use cases
- Cost transparency in UI

### 2. Resource Management
- Appropriate resource limits
- Environment-specific configurations
- Backup and monitoring by default
- Security best practices

### 3. Cost Management
- Auto-approval thresholds
- Budget notifications
- Regular cost reviews
- Resource optimization recommendations

## Future Enhancements

### 1. Advanced Pricing
- Volume discounts
- Reserved instance pricing
- Multi-cloud cost comparison
- Custom pricing tiers

### 2. Enhanced Workflows
- Approval workflows for large deployments
- Multi-step provisioning
- Resource dependency management
- Rollback capabilities

### 3. Integration Extensions
- Additional payment providers
- Cloud provider integrations
- External monitoring systems
- Advanced analytics

## Support

For issues with the Tollgate-Scaffolder integration:

1. Check the troubleshooting section above
2. Review Backstage logs for error details
3. Verify configuration settings
4. Contact the platform team for assistance

## Related Documentation

- [Tollgate Plugin Documentation](./tollgate-plugin.md)
- [Scaffolder Documentation](https://backstage.io/docs/features/software-templates)
- [Custom Resource Definitions](./kubernetes-crds.md)
- [Payment Processing Guide](./payment-processing.md)