sunset-manifest.yaml

mmand } from '@aws-sdk/client-s3'; import { DynamoDBClient, ScanCommand } from '@aws-sdk/client-dynamodb'; import { unmarshall } from '@aws-sdk/util-dynamodb'; import { createHash } from 'crypto';

const s3 = new S3Client({ region: process.env.AWS_REGION }); const dynamo = new DynamoDBClient({ region: process.env.AWS_REGION });

export async function archiveProductData(tableName: string, archiveBucket: string) { const archiveId = archive-${Date.now()}-${createHash('sha256').update(tableName).digest('hex').slice(0, 8)}; const records: any[] = []; let lastKey: Record<string, any> | undefined;

do { const scan = await dynamo.send(new ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey, Limit: 1000 }));

scan.Items?.forEach(item => {
  records.push(unmarshall(item));
});

lastKey = scan.LastEvaluatedKey;

} while (lastKey);

const payload = JSON.stringify(records, null, 2); const checksum = createHash('sha256').update(payload).digest('hex');

await s3.send(new PutObjectCommand({ Bucket: archiveBucket, Key: ${archiveId}/data.json, Body: payload, Metadata: { 'x-amz-meta-source-table': tableName, 'x-amz-meta-record-count': records.length.toString(), 'x-amz-meta-checksum': checksum, 'x-amz-meta-retention-policy': 'compliance-7y' }, ServerSideEncryption: 'AES256' }));

return { archiveId, recordCount: records.length, checksum }; }

#### Architecture Decisions & Rationale

The sunset pipeline uses an event-driven state machine rather than linear scripts. This allows concurrent execution of archival, deprecation routing, and teardown while maintaining strict ordering for destructive operations. Immutable S3 archives with checksum verification satisfy compliance requirements and prevent accidental data loss. The middleware approach ensures all API consumers receive standardized deprecation signals without requiring application-level changes. Infrastructure teardown is gated behind IaC state validation, preventing orphaned resources and ensuring predictable cost recovery.

## Pitfall Guide

1. **Skipping Downstream Dependency Mapping**
   Teams often decommission a service without mapping webhook consumers, scheduled jobs, or internal API callers. This breaks downstream systems silently. Always generate a dependency graph from runtime traces, CI/CD pipelines, and infrastructure state before initiating teardown.

2. **Permanent Data Deletion Without Legal Hold**
   Deleting databases to "clean up" violates data retention laws and destroys audit trails. Implement a legal hold flag that prevents deletion until compliance sign-off. Archive to immutable storage with explicit retention policies.

3. **Ignoring Async & Webhook Consumers**
   Synchronous API deprecation is visible; async consumers are not. Webhook endpoints continue firing after sunset, causing 404/503 errors and retry storms. Maintain a deprecation proxy that logs attempts, returns `410 Gone` with migration headers, and buffers retries for 30 days.

4. **Abrupt DNS & CDN Cutoff**
   Removing DNS records instantly breaks cached resolvers and enterprise firewalls. Implement a phased TTL reduction, redirect to a sunset landing page, and maintain CNAME records for 90 days post-termination.

5. **Leaving Billing & Subscription Hooks Active**
   Decommissioned products often retain active payment processor webhooks, trial extensions, or renewal triggers. Reconcile all billing integrations, cancel recurring subscriptions, and verify zero transaction volume before infrastructure teardown.

6. **Treating Exit as a One-Off Task**
   Manual teardown scripts become unmaintainable and error-prone. Version-control sunset pipelines, integrate them into CI/CD, and treat decommissioning with the same rigor as feature deployments.

7. **No Post-Sunset Monitoring**
   Resources continue incurring costs or triggering alerts after teardown begins. Maintain a 14-day monitoring window tracking cloud spend, error rates, and DNS resolution. Automate cost anomaly detection during the transition period.

**Best Practices from Production:**
- Embed sunset gates into PR reviews for any service marked `status: sunset`
- Use feature flags to toggle read-only mode before full termination
- Maintain a decommissioning runbook with rollback procedures
- Require legal/compliance sign-off before data archival completion
- Automate credential rotation and secret revocation as final teardown steps

## Production Bundle

### Action Checklist
- [ ] Asset Inventory: Map all compute, storage, networking, and third-party dependencies using IaC state and runtime telemetry
- [ ] Legal & Compliance Hold: Flag data for retention, generate audit requirements, and obtain compliance sign-off before deletion
- [ ] Data Archival Pipeline: Export datasets to immutable storage with checksums, encryption, and retention metadata
- [ ] API Deprecation Routing: Deploy sunset middleware, reduce TTL, activate read-only mode, and monitor consumer migration
- [ ] Infrastructure Teardown: Execute phased deletion (external → internal → persistent) with IaC validation gates
- [ ] Billing & Credential Cleanup: Cancel subscriptions, revoke API keys, rotate secrets, and verify zero transaction volume
- [ ] Post-Sunset Monitoring: Track cloud costs, error rates, and DNS resolution for 14 days after termination
- [ ] Audit Archive: Store decommissioning logs, migration reports, and compliance certificates in a retention vault

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Public API with 50k+ consumers | Phased deprecation with proxy + migration incentives | Prevents ecosystem breakage, maintains developer trust | High initial engineering cost, 85% long-term support savings |
| Internal data pipeline | Immediate read-only → archival → teardown | Low external risk, high compliance requirement | Minimal cost, fast teardown (3-5 days) |
| Mobile app with active subscriptions | Billing reconciliation first → app store metadata update → server teardown | Prevents refund storms and chargebacks | Moderate cost, requires app store coordination |
| Legacy monolith with unknown dependencies | Dependency graph generation → canary shutdown → full teardown | Mitigates hidden integration risks | Higher upfront cost, prevents production incidents |

### Configuration Template

```yaml
# sunset-manifest.yaml
product:
  id: "analytics-v2"
  status: "sunset"
  timeline:
    read_only_date: "2024-11-01T00:00:00Z"
    deprecation_date: "2024-12-01T00:00:00Z"
    termination_date: "2025-01-15T00:00:00Z"
  compliance:
    retention_policy: "7y"
    legal_hold: true
    audit_vault: "s3://compliance-logs/analytics-v2/"
  teardown:
    phased: true
    external_exposure_first: true
    monitor_window_days: 14
  contacts:
    engineering: "platform-team@company.com"
    compliance: "legal@company.com"
    customer_success: "support@company.com"

// sunset-pipeline.ts
import { sunsetMiddleware } from './sunset-middleware';
import { archiveProductData } from './sunset-archival';

const config = {
  sunsetDate: '2025-01-15T00:00:00Z',
  deprecationDocsUrl: 'https://docs.company.com/sunset/analytics-v2',
  contactEmail: 'platform-team@company.com'
};

// Express integration
app.use('/api/v2', sunsetMiddleware(config));

// Scheduled archival job
cron.schedule('0 2 * * *', async () => {
  const result = await archiveProductData('analytics-events-v2', 's3://company-archives/');
  console.log(`Archived ${result.recordCount} records. Checksum: ${result.checksum}`);
});

// Teardown guard
if (process.env.SUNSET_PHASE === 'TERMINATED') {
  console.log('Phase gate: Awaiting compliance sign-off before teardown');
  process.exit(0);
}

Quick Start Guide

1. Initialize a sunset manifest in your repository root using the provided YAML template. Update dates, compliance requirements, and contact mappings.
2. Deploy the TypeScript deprecation middleware to your API gateway or Express/Fastify instance. Verify Sunset, Deprecation, and Link headers appear in responses.
3. Configure the archival pipeline with your database credentials and S3/GCS bucket. Run a dry export to validate checksums and retention metadata.
4. Integrate the teardown guard into your CI/CD pipeline. Set SUNSET_PHASE environment variables to control progression through READ_ONLY → DEPRECATED → TERMINATED.
5. Activate post-sunset monitoring dashboards tracking cloud spend, error rates, and consumer migration metrics. Maintain for 14 days post-termination.