# Tollgate-Scaffolder Integration Deployment Guide

This guide walks through the deployment of the Tollgate-Scaffolder integration for paid resource provisioning.

## Prerequisites

- Backstage instance with Tollgate plugin installed
- Kubernetes cluster with operator capabilities
- Stripe account for payment processing
- Node.js 18+ and Yarn package manager

## Step 1: Install Dependencies

### Backend Dependencies

Add the Scaffolder module to your backend:

```bash
cd packages/backend
yarn add @internal/scaffolder-backend-module-tollgate
```

### Update Backend Configuration

Edit `packages/backend/src/index.ts`:

```typescript
// Add the Tollgate Scaffolder module
backend.add(import('@internal/scaffolder-backend-module-tollgate'));
```

## Step 2: Configure the Integration

### Update app-config.yaml

```yaml
tollgate:
  scaffolder:
    # Auto-approval threshold for costs under this amount (USD)
    autoApprovalThreshold: 100
    
    # Default region for pricing calculations
    defaultRegion: us-east-1
    
    # Resource pricing configuration
    pricing:
      cpuHourlyRate: 0.048      # $0.048 per CPU core per hour
      memoryHourlyRate: 0.0067  # $0.0067 per GB memory per hour
      storageMonthlyRate: 0.10  # $0.10 per GB storage per month
      
      # Regional pricing multipliers
      regionalMultipliers:
        us-east-1: 1.0
        us-west-2: 1.05
        eu-west-1: 1.15
        ap-southeast-1: 1.20
    
    # Kubernetes configuration
    kubernetes:
      defaultNamespace: default
      clusterName: production-cluster

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

### Environment Variables

Set required environment variables:

```bash
export STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
export STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
```

## Step 3: Deploy Custom Resource Definitions

Deploy the CRDs to your Kubernetes cluster:

```bash
# Deploy WordPress CRD
kubectl apply -f k8s-operator/crds/wordpress-crd.yaml

# Deploy WebApp CRD
kubectl apply -f k8s-operator/crds/webapp-crd.yaml

# Deploy Database CRD
kubectl apply -f k8s-operator/crds/database-crd.yaml

# Verify CRDs are installed
kubectl get crd | grep -E "(wordpress|webapp|database)"
```

## Step 4: Configure Kubernetes Permissions

Create a service account and RBAC for the Scaffolder:

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: backstage-scaffolder
  namespace: backstage
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-scaffolder
rules:
- apiGroups: ["apps.example.com"]
  resources: ["wordpresses", "webapps"]
  verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
- apiGroups: ["data.example.com"]
  resources: ["databases"]
  verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["secrets", "configmaps"]
  verbs: ["create", "get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: backstage-scaffolder
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: backstage-scaffolder
subjects:
- kind: ServiceAccount
  name: backstage-scaffolder
  namespace: backstage
```

Apply the RBAC configuration:

```bash
kubectl apply -f backstage-scaffolder-rbac.yaml
```

## Step 5: Build and Start Backstage

### Install Dependencies

```bash
yarn install
```

### Build the Integration

```bash
yarn build:backend
```

### Start Backstage

```bash
yarn dev
```

## Step 6: Verify the Integration

### 1. Check Scaffolder Actions

Navigate to `http://localhost:3000/create/actions` and verify the new actions are available:

- `tollgate:validate-subscription`
- `tollgate:calculate-price`
- `tollgate:create-payment-intent`
- `tollgate:confirm-payment`
- `kubernetes:create-cr`

### 2. Test Template Discovery

Navigate to `http://localhost:3000/create` and verify the templates are listed:

- WordPress Deployment with Pricing
- Web Application Deployment

### 3. Test Cost Calculation

Create a new WordPress deployment and verify:

1. Subscription validation works
2. Cost calculation displays correctly
3. Payment flow initializes (if cost > threshold)

## Step 7: Production Deployment

### Database Migration

If using persistent storage for cost tracking:

```bash
yarn backstage-cli backend:migrate
```

### Production Configuration

Update `app-config.production.yaml`:

```yaml
backend:
  auth:
    dangerouslyDisableDefaultAuthPolicy: false

tollgate:
  stripe:
    secretKey: ${STRIPE_SECRET_KEY}
    webhookSecret: ${STRIPE_WEBHOOK_SECRET}
  
  scaffolder:
    autoApprovalThreshold: 500  # Higher threshold for production
    defaultRegion: us-east-1
    
app:
  baseUrl: https://backstage.your-company.com
```

### Kubernetes Deployment

Update your Backstage deployment with the new configuration:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
spec:
  template:
    spec:
      serviceAccountName: backstage-scaffolder
      containers:
      - name: backstage
        env:
        - name: STRIPE_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: backstage-secrets
              key: stripe-secret-key
        - name: STRIPE_WEBHOOK_SECRET
          valueFrom:
            secretKeyRef:
              name: backstage-secrets
              key: stripe-webhook-secret
```

## Monitoring and Troubleshooting

### 1. Monitor Scaffolder Logs

```bash
kubectl logs -n backstage deployment/backstage -c backend -f | grep tollgate
```

### 2. Check Custom Resource Status

```bash
# Check WordPress deployments
kubectl get wordpress -A

# Check WebApp deployments  
kubectl get webapp -A

# Check Database instances
kubectl get database -A
```

### 3. Verify Payment Processing

Check Stripe dashboard for payment activity and webhook delivery status.

### 4. Common Issues

#### Subscription Validation Fails
- Verify user entity exists in catalog
- Check Tollgate API connectivity
- Review subscription configuration

#### Payment Processing Timeout
- Increase timeout in template
- Check Stripe webhook configuration
- Verify network connectivity

#### Custom Resource Creation Fails
- Verify CRDs are installed correctly
- Check RBAC permissions
- Review Kubernetes API connectivity

## Security Checklist

- [ ] Stripe keys stored as Kubernetes secrets
- [ ] RBAC configured with minimal permissions
- [ ] Webhook signatures verified
- [ ] Network policies applied
- [ ] Audit logging enabled
- [ ] TLS/SSL configured for production

## Performance Optimization

### 1. Caching

Enable caching for cost calculations:

```yaml
tollgate:
  scaffolder:
    pricing:
      cacheEnabled: true
      cacheTtl: 300  # 5 minutes
```

### 2. Resource Limits

Set appropriate resource limits for the backend:

```yaml
resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi
```

### 3. Database Connection Pooling

If using external database for cost tracking:

```yaml
backend:
  database:
    connection:
      pool:
        min: 5
        max: 20
```

## Next Steps

1. **Operator Development**: Implement the actual Kubernetes operators for the CRDs
2. **Monitoring Integration**: Add Prometheus metrics for cost tracking
3. **Budget Alerts**: Implement budget notifications and limits
4. **Advanced Templates**: Create more sophisticated deployment templates
5. **Multi-Cloud Support**: Extend pricing models for different cloud providers

## Support

For deployment issues:

1. Check the logs for specific error messages
2. Verify all configuration values are correct
3. Test individual Scaffolder actions independently
4. Contact the platform team for assistance

## Related Documentation

- [Tollgate Plugin Setup](./tollgate-plugin-setup.md)
- [Scaffolder Actions Reference](./scaffolder-actions-reference.md)
- [Kubernetes Operator Development](./operator-development.md)
- [Cost Management Guide](./cost-management.md)