Generating Snapshots

This workflow covers generating snapshots—immutable, signed bundles containing release metadata and artifact references for distribution to vendor-controlled mirrors. Snapshots enable regulated customers to self-host artifacts while maintaining trust in vendor-signed metadata.

Prerequisites

• API credentials with snapshot generation permissions
• Releases published and available
• Understanding of mirror distribution requirements

Understanding Snapshots

Snapshots are:

• Immutable — Once created, snapshots cannot be modified
• Signed — Ed25519 signature ensures authenticity
• Point-in-time — Contains releases available at snapshot creation time
• Tenant-scoped — Snapshots are generated per tenant

Snapshots enable mirrors to:

• Pull updates outbound-only
• Verify vendor signatures
• Host artifacts locally
• Serve clients from local infrastructure

Step 1: Check Snapshot Generation Status

Snapshots are automatically generated when:

• New releases are published
• Releases are revoked
• Scheduled generation runs (if configured)

Check if automatic generation is enabled:

curl "${BP_BASE_URL}/v1/snapshots/config" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "auto_on_publish": true,
  "scheduled": {
    "enabled": true,
    "interval": "1h"
  }
}

Step 2: Generate Snapshot Manually

Generate a snapshot manually:

curl -X POST "${BP_BASE_URL}/v1/snapshots/generate" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_xyz789",
    "channels": ["stable", "beta"],
    "force": false
  }'

Parameters:

• tenant_id — Tenant to generate snapshot for (optional, generates for all if omitted)
• channels — Channels to include (optional, includes all if omitted)
• force — Force regeneration even if no changes (default: false)

Response:

{
  "snapshot_id": "snapshot_abc123",
  "tenant_id": "tenant_xyz789",
  "created_at": "2024-01-15T10:30:00Z",
  "channels": ["stable", "beta"],
  "release_count": 25,
  "artifact_count": 50
}

Step 3: Retrieve Snapshot

Get snapshot manifest:

curl "${BP_BASE_URL}/v1/snapshots/snapshot_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "snapshot_id": "snapshot_abc123",
  "tenant_id": "tenant_xyz789",
  "created_at": "2024-01-15T10:30:00Z",
  "channels": ["stable", "beta"],
  "releases": [
    {
      "release_id": "rel_abc123",
      "product_id": "prod_xyz789",
      "version": "1.2.3",
      "channel": "stable",
      "published_at": "2024-01-15T10:30:00Z",
      "artifacts": [
        {
          "artifact_id": "art_win64",
          "platform": "windows",
          "arch": "x86_64",
          "installer_type": "msi",
          "sha256": "a1b2c3d4e5f6...",
          "size_bytes": 15728640,
          "download_url": "https://..."
        }
      ]
    }
  ],
  "signature": "ed25519_signature_here"
}

Step 4: Get Latest Snapshot

Get the latest snapshot for a tenant:

curl "${BP_BASE_URL}/v1/snapshots/latest?tenant_id=tenant_xyz789&channels=stable" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Step 5: Get Snapshot Bundle

Get snapshot bundle (manifest + artifact references):

curl "${BP_BASE_URL}/v1/snapshots/snapshot_abc123/bundle" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "snapshot_id": "snapshot_abc123",
  "manifest": {
    // Snapshot manifest (as above)
  },
  "artifacts": [
    {
      "artifact_id": "art_win64",
      "sha256": "a1b2c3d4e5f6...",
      "download_url": "https://artifacts.example.com/artifacts/a1b2c3d4e5f6...",
      "size_bytes": 15728640
    }
  ],
  "signature": "ed25519_signature_here"
}

Snapshot Content

Release inclusion:

• Latest non-revoked release per product/channel combination
• Optionally includes historical releases (configurable limit)
• Excludes revoked releases

Artifact references:

• Artifact ID
• SHA-256 hash
• Size in bytes
• Download URL
• Platform, architecture, installer type

Deduplication:

• Same artifact (by SHA-256) referenced by multiple releases appears once
• Mirrors download artifacts by hash, avoiding duplicates

Mirror Sync Process

Mirrors sync snapshots:

1. Query latest snapshot — Mirror queries /v1/snapshots/latest
2. Verify signature — Mirror verifies snapshot signature
3. Compare snapshot ID — Check if snapshot is newer than current
4. Download snapshot bundle — Download snapshot bundle if new
5. Extract artifact references — Extract artifact references from snapshot
6. Download artifacts — Download artifacts by hash (if not already cached)
7. Verify artifacts — Verify artifact hashes match snapshot
8. Serve locally — Serve snapshot and artifacts over local HTTPS

Snapshot Scheduling

Configure snapshot generation schedule:

snapshots:
  generation:
    # Automatic generation on release publish
    auto_on_publish: true

    # Scheduled generation
    scheduled:
      enabled: true
      interval: "1h"  # Generate snapshot every hour
      cron: "0 * * * *"  # Or use cron expression

    # Batch window (generate snapshot within N minutes of changes)
    batch_window: "5m"

  retention:
    # Keep last N snapshots per tenant
    keep_snapshots: 100

    # Cleanup old snapshots
    cleanup_enabled: true
    cleanup_interval: "24h"
    cleanup_older_than: "30d"

Snapshot Verification

Mirrors verify snapshots before accepting:

Signature verification:

• Verify Ed25519 signature matches vendor’s public key
• Ensure signature is valid and not expired

Content verification:

• Check snapshot ID is unique and newer than current
• Verify release metadata is valid
• Verify artifact references have valid hashes
• Check artifact download URLs are accessible

Best Practices

Automate generation: Generate snapshots automatically on release publish.

Schedule regular generation: Generate snapshots periodically even without changes.

Verify signatures: Always verify signatures before accepting snapshots.

Monitor metrics: Track snapshot generation metrics and trends.

Handle failures: Implement robust error handling and retry logic.

Limit snapshot size: Keep snapshots manageable (paginate if needed).

Retain history: Keep historical snapshots for audit and rollback.

Document changes: Document snapshot structure changes.

Next Steps

• Distribute artifacts — see Distributing Artifacts
• Manage release versions — see Managing Release Versions
• Handle rollbacks — see Handling Rollbacks