sunset-manifest.yaml

endency graph.

Step 2: Data Archival & Export Pipeline

User data must be exported, encrypted, and stored in immutable archives before deletion. Implement a pipeline that reads from production databases, transforms records to standardized formats (JSON/Parquet), and writes to cold storage with retention policies. Include user-initiated export endpoints compliant with data portability regulations.

Step 3: API & Service Deprecation Routing

Transition services to read-only mode, then route traffic to deprecation endpoints. Use HTTP headers to communicate sunset timelines, provide fallback documentation, and track remaining consumer usage. Implement a state machine that progresses through ACTIVE → READ_ONLY → DEPRECATED → TERMINATED.

Step 4: Infrastructure Teardown Orchestration

Execute teardown using infrastructure-as-code with explicit deletion guards. Remove external exposure first (DNS, load balancers, API gateways), then internal services (compute, queues, caches), and finally persistent storage. Validate each stage with health checks before proceeding.

Step 5: Compliance & Financial Closure

Reconcile billing, cancel subscriptions, rotate and revoke credentials, and generate audit reports. Store decommissioning logs in a compliance vault for regulatory retention periods.

TypeScript Implementation: Deprecation Middleware & Archival Pipeline

// sunset-middleware.ts
import { Request, Response, NextFunction } from 'express';

export interface SunsetConfig {
  sunsetDate: string;
  deprecationDocsUrl: string;
  contactEmail: string;
}

export function sunsetMiddleware(config: SunsetConfig) {
  return (req: Request, res: Response, next: NextFunction) => {
    res.set('Sunset', config.sunsetDate);
    res.set('Deprecation', 'true');
    res.set('Link', `<${config.deprecationDocsUrl}>; rel="deprecation"`);
    res.set('X-Sunset-Contact', config.contactEmail);
    
    // Track usage for migration analytics
    const usageTracker = req.app.get('sunsetUsageTracker');
    usageTracker?.record(req.originalUrl, req.method);
    
    next();
  };
}

// sunset-archival.ts
import { S3Client, PutObjectCommand } 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

# 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.