System Versioning & Snapshots

Track complete infrastructure state as immutable versions. Every deployment creates a snapshot of all asset versions, configurations, and metadata for perfect reproducibility and instant rollbacks.

What is System Versioning?

System versioning is Codiac's approach to tracking the complete state of your infrastructure at any point in time. Instead of tracking individual service versions in Git commits or release notes, Codiac captures everything about your deployment in a single, immutable snapshot.

What gets captured:

Asset versions deployed across all cabinets
Configuration values (environment variables, settings)
Infrastructure state (ingress routes, volumes, scaling config)
Metadata (who deployed, when, from where, why)

Every deployment creates a new enterprise version (snapshot).

Business Value

Complete audit trail:

Know exactly what was running at any point in time
Trace who made changes and when
Meet compliance requirements (SOC 2, HIPAA, ISO)

Perfect reproducibility:

Anyone on the team can recreate any environment, anytime, no tribal knowledge required
Debug production issues by recreating exact environment in staging
Test hotfixes against precise historical state
Eliminate "works on my machine" problems

Instant recovery:

One-click rollback of entire system (not just one service)
85% faster incident response vs manual debugging
Roll forward to any previous known-good state

Change confidence:

Try risky changes knowing you can instantly revert
Safely experiment in production
Reduce deployment fear

Real-World Use Case: Release Management & Environment Promotion

The most powerful application of system versioning is perfect environment promotion. Deploy to staging, test thoroughly, then promote the exact snapshot to production in one command.

No manual YAML copying. No "what changed?" mysteries. Perfect reproducibility.

See the complete guide: Release Management & Environment Promotion

How System Versioning Works

Development → Build → Deploy → Snapshot Created
                                      ↓
                              Enterprise Version
                                   (v1.2.45)
                                      ↓
                    ┌─────────────────┼─────────────────┐
                    ↓                 ↓                 ↓
              Cabinet: production  Cabinet: database  Cabinet: workers
                    ↓                 ↓                 ↓
            my-api:1.2.5       postgres:14.3      worker:2.1.0
               (config)            (config)          (config)

Timeline:

Developer deploys new asset version
Codiac records current state across ALL cabinets
Immutable snapshot created with unique version ID
Snapshot includes asset versions + configuration + infrastructure state
Snapshot available for rollback, comparison, or replication

Enterprise Versions (Snapshots)

An enterprise version is a complete snapshot of your infrastructure at a specific moment.

Anatomy of a Snapshot

{
  "version": "1.2.45",
  "timestamp": "2026-01-23T14:32:00Z",
  "creator": "jane@company.com",
  "enterprise": "my-company",
  "cabinets": {
    "production": {
      "assets": {
        "my-api": {
          "version": "1.2.5",
          "image": "my-registry/my-api:1.2.5",
          "replicas": 3,
          "config": { "DATABASE_URL": "..." }
        },
        "postgres": {
          "version": "14.3",
          "image": "postgres:14.3",
          "volumes": ["/var/lib/postgresql/data"]
        }
      }
    }
  },
  "tags": ["prod", "stable", "release-2026-01"]
}

Creating Snapshots

Automatic snapshot creation: Every deployment automatically creates a new enterprise version.

# Deploy an asset
cod asset deploy --cabinet production --asset my-api --update 1.2.5
# → Enterprise version v1.2.45 created automatically

Manual snapshots: Tag important snapshots for easy reference using cod snapshot tags.

Use cases for tagged snapshots:

Before risky changes (database migrations, major refactors)
Before scheduled maintenance windows
Regulatory checkpoints (end of quarter, audit freeze)
Known-good states for testing

Viewing Snapshots

List All Snapshots

cod snapshot list

Example output:

VERSION   CREATED              CREATOR              TAGS
v1.2.45   2026-01-23 14:32    jane@company.com     prod, stable
v1.2.44   2026-01-23 10:15    bob@company.com      prod
v1.2.43   2026-01-22 16:45    jane@company.com     prod, release-2026-01
v1.2.42   2026-01-22 14:20    alice@company.com    prod
v1.2.41   2026-01-21 09:30    bob@company.com      prod, hotfix

View Snapshot Details

View detailed snapshot information in the web UI at app.codiac.io.

Shows:

All cabinets and their deployed assets
Asset versions and configurations
Timestamp and creator
Tags applied
Changes from previous version (diff)

Compare Snapshots

Compare snapshots visually in the web UI at app.codiac.io. The UI provides detailed diff views showing changes between versions.

Tagging Snapshots

Tags organize snapshots for easy filtering and identification.

Adding Tags

# Add tags to a snapshot (non-interactive)
cod snapshot tags --silent --addTags stable --filterVersions v1.2.45

# Add multiple tags
cod snapshot tags --silent --addTags prod --addTags release-2026-01 --filterVersions v1.2.45

Removing Tags

cod snapshot tags --silent --removeTags stable --filterVersions v1.2.45

Listing by Tag

# View all snapshots (filter by tag in interactive mode)
cod snapshot tags --filterTags stable

# View all prod releases
cod snapshot tags --filterTags prod

Common Tagging Strategies

Tag	Usage	Example
`prod`	Currently deployed to production	All production snapshots
`stable`	Known-good, tested versions	Snapshots that passed QA
`release-YYYY-MM`	Monthly releases	`release-2026-01`, `release-2026-02`
`hotfix`	Emergency fixes	Snapshots created during incidents
`pre-migration`	Checkpoint before risky changes	Before database migrations
`Q1-2026`	Quarterly tags for audit	Compliance checkpoints

Bulk Tag Management

New feature: Manage tags across multiple snapshots efficiently.

Interactive Bulk Tagging

cod snapshot tags

Interactive mode:

Lists all snapshots
Fuzzy search to filter snapshots
Select multiple snapshots
Add/remove tags in bulk

Example workflow:

$ cod snapshot tags
? Search snapshots: 2026-01
  → v1.2.45 (2026-01-23)
  → v1.2.43 (2026-01-22)
  → v1.2.41 (2026-01-21)

? Select snapshots: (Use arrow keys, space to select, enter to confirm)
  [x] v1.2.45
  [x] v1.2.43
  [ ] v1.2.41

? Action: (Use arrow keys)
  → Add tags
    Remove tags

? Enter tags to add (comma separated): release-2026-01,audited

✓ Added tags to 2 snapshots

Silent Mode (Non-Interactive)

# Add tag to specific versions
cod snapshot tags --silent --addTags stable --filterVersions v1.2.45 --filterVersions v1.2.46

# Remove tag from specific versions
cod snapshot tags --silent --removeTags deprecated --filterVersions v1.2.40

# Filter by cabinet when managing tags
cod snapshot tags --silent --addTags prod --filterCabinets production

Bulk Operations

Tag snapshots by date:

cod snapshot tags --silent --addTags Q1-2026 --filterDates 2026-01-15

Filter by existing tags:

cod snapshot tags --silent --addTags audited --filterTags prod

Rolling Back

Restore your infrastructure to any previous snapshot.

Full System Rollback

cod snapshot deploy --version v1.2.43

What happens:

Codiac reads snapshot v1.2.43
Reverts ALL asset versions across ALL cabinets to snapshot state
Restores configuration values
Kubernetes performs rolling update to target versions
New enterprise version created (e.g., v1.2.46) referencing v1.2.43 state

Typical rollback time: 2-5 minutes for entire system.

Key point: Rollback creates a NEW snapshot. This maintains audit trail (you can see the rollback action).

Cabinet-Level Rollback

cod snapshot deploy --version v1.2.43 --cabinet production

Rollback only the production cabinet to its state in snapshot v1.2.43. Other cabinets remain unchanged.

Asset-Level Rollback

cod asset deploy --cabinet production --asset my-api --update 1.2.4

Revert single asset to previous version. This is simpler than full snapshot rollback for single-service issues.

When to Use Each Rollback Type

Scenario	Rollback Type	Command
Single service bug	Asset rollback	`cod asset deploy --update <version>`
Cabinet-wide issue	Cabinet rollback	`cod snapshot deploy --version <version> --cabinet <cabinet>`
System-wide incident	Full rollback	`cod snapshot deploy --version <version>`
Database migration failure	Full rollback to pre-migration version	`cod snapshot deploy --version <pre-migration-version>`

Reproducible Environments

Use snapshots to replicate exact production state in other environments.

Replicate Production to Staging

# List snapshots to find production version
cod snapshot list

# Deploy that snapshot to staging cabinet
cod snapshot deploy --version v1.2.45 --cabinet staging

Result:

Staging now runs exact same versions as production
Configuration inherited from staging environment (not production config)
Perfect for reproducing production bugs

Create Testing Environment from Snapshot

# Deploy historical snapshot to test cabinet
cod snapshot deploy --version v1.2.30 --cabinet test-reproduce-issue

Use case: Customer reports bug from two weeks ago. Reproduce exact environment to debug.

Clone Production for Training

# Create training environment with exact production versions
codiac snapshot deploy
# Select snapshot v1.2.45 and training environment

# Override with dummy data
codiac config set
# Select environment scope → training → DATABASE_URL → postgres://training-db

Best Practices

1. Tag Important Snapshots Immediately

Don't wait. Tag snapshots right after deployment:

cod asset deploy --cabinet production --asset my-api --update 1.2.5
# Then tag using the interactive tool
cod snapshot tags

Better: Use CI/CD integration to auto-tag:

# GitHub Actions example
- name: Deploy and Tag
  run: |
    cod asset deploy --cabinet production --asset my-api --update $VERSION
    # Tag the latest snapshot
    cod snapshot tags --silent --addTags prod --addTags release-${{ github.ref_name }} --filterCabinets production

2. Tag Before Risky Changes

Always tag current state before:

Database migrations
Major infrastructure changes
Kubernetes version upgrades
Configuration overhauls

# Tag current snapshot before migration
cod snapshot tags --silent --addTags pre-db-migration --filterCabinets production
# ... perform migration ...
# If fails: cod snapshot deploy --version <pre-migration-version> --cabinet production

3. Keep Snapshots Organized

Tagging strategy:

prod - Currently in production
stable - Passed all tests, deployable
release-YYYY-MM-DD - Date-based releases
pre-X - Checkpoints before major changes
post-X - State after major changes
QX-YYYY - Quarterly compliance tags

4. Regular Cleanup

Manage snapshot retention in the web UI at app.codiac.io.

Keep:

Snapshots tagged stable, release-*, or Q*-*
Last 30 days of all snapshots
Current production snapshot

5. Document Snapshot Decisions

Add descriptive tags to snapshots:

cod snapshot tags --silent --addTags hotfix-auth-bug --filterVersions v1.2.45

Team communication:

Tag snapshots with Jira/GitHub issue numbers
Include incident postmortem links
Note breaking changes

6. Test Rollback Procedures

Practice rollbacks regularly:

# In staging cabinet
cod snapshot deploy --version v1.2.40 --cabinet staging
# Verify application works
# Roll forward
cod snapshot deploy --version v1.2.45 --cabinet staging

Why: Ensure rollback works BEFORE you need it in production emergency.

Integration with CI/CD

GitHub Actions Example

name: Deploy and Snapshot

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to Production
        run: |
          cod asset deploy \
            --cabinet production \
            --asset my-api \
            --update ${{ github.sha }}

      - name: Tag Snapshot
        run: |
          cod snapshot tags --silent \
            --addTags prod \
            --addTags release-$(date +%Y-%m-%d) \
            --filterCabinets production

      - name: Notify Team
        run: |
          echo "✓ Deployed version $VERSION to production"

GitLab CI Example

deploy_production:
  stage: deploy
  script:
    - cod asset deploy --cabinet production --asset my-api --update $CI_COMMIT_SHA
    - cod snapshot tags --silent --addTags prod --addTags pipeline-$CI_PIPELINE_ID --filterCabinets production
  only:
    - main

Comparison with Other Approaches

Approach	Snapshot Scope	Rollback Speed	Reproducibility	Audit Trail
Codiac System Versioning	Complete system state	2-5 minutes	100% (exact reproduction)	Complete (who, what, when, why)
Git Tags + CI/CD	Code only (not config/state)	10-30 minutes (rebuild + redeploy)	Partial (config may differ)	Git history only
Helm Rollback	Single chart/release	2-5 minutes	Partial (config may differ)	Helm history (per release)
Kubernetes Rollout Undo	Single deployment	1-2 minutes	No (previous ReplicaSet only)	K8s events (limited retention)
ArgoCD/Flux History	Git commit state	5-15 minutes (GitOps sync)	Partial (declarative only)	Git history

Codiac advantage: Complete system snapshot including configuration, not just code versions. No tribal knowledge required-anyone can reproduce any environment by deploying a snapshot. And because Codiac writes clean Kubernetes native objects (not CRDs or operator-managed resources), what you capture is what you get: standard deployments, services, and configmaps.

Advanced: Snapshot Automation

Scheduled Tagging

Tag daily production snapshots:

# Via cron (Linux/macOS) - tag latest snapshot with daily marker
0 2 * * * cod snapshot tags --silent --addTags daily-backup-$(date +\%Y-\%m-\%d) --filterCabinets production

Pre-deployment tagging in CI/CD:

before_deploy:
  script:
    - cod snapshot tags --silent --addTags pre-deploy-$CI_COMMIT_SHA --filterCabinets production

Snapshot Retention Policies

Enterprise tier feature: Automatic snapshot pruning with retention rules.

Example policy:

retention:
  keep_last: 30  # Keep last 30 snapshots
  keep_tagged: true  # Never delete tagged snapshots
  keep_production: 90  # Keep prod snapshots for 90 days
  keep_compliance: 365  # Keep compliance tags for 1 year

Snapshot Webhooks

Trigger actions on snapshot creation:

cod webhook create \
  --event snapshot.created \
  --url https://api.mycompany.com/notify \
  --filter "tags.contains('prod')"

Use cases:

Slack notifications on production deployments
Automated testing of new snapshots
Compliance logging to external systems

Troubleshooting

Problem: Snapshot doesn't match production

Possible causes:

Manual changes made via kubectl (bypassing Codiac)
Configuration drift from external systems
Snapshot created before recent deployment completed

Solution:

# Check for manual changes
kubectl get deployments -A -o yaml | grep -v "last-applied-configuration"

# Redeploy to sync state
cod asset deploy --cabinet production --asset my-api

Problem: Rollback fails

Error: Unable to pull image my-api:1.2.3

Cause: Old image version no longer in registry (deleted or retention policy expired).

Solution:

Rebuild image from source (if available)
Restore image from backup registry
Roll forward to newer version instead

Prevention: Configure registry retention policies to keep images longer than snapshot retention.

Problem: Snapshot differences unclear

Cause: Configuration values changed outside of Codiac.

Solution: View detailed snapshot comparisons in the web UI at app.codiac.io. The UI provides verbose diff views including all configuration changes.

FAQ

Q: How long are snapshots retained?

Free tier: 30 days
Team tier: 90 days
Enterprise tier: Configurable (up to 1 year or indefinite for tagged snapshots)

Q: Do snapshots include database data?

A: No. Snapshots capture infrastructure state (versions, config) but not application data. Use database backups for data recovery.

Q: Can I share snapshots between enterprises?

A: No. Snapshots are scoped to a single enterprise. Use kits or cluster stacks to share infrastructure patterns.

Q: What happens if I deploy a snapshot to a different cloud provider?

A: Codiac adapts the deployment to the target cloud. Asset versions and configuration remain the same, but cloud-specific resources (load balancers, volumes) are recreated using the target provider's services.

Q: How large are snapshots?

A: Very small (typically < 100 KB). Snapshots only store metadata and references, not actual images or data.

Release Management & Environment Promotion - Complete guide to using snapshots for staging→prod workflows
Glossary: Enterprise Version
Glossary: System Versioning
Rollback Guide
CI/CD Integration
Compliance & Audit

Need help with system versioning? Contact Support or check our rollback best practices guide.

What is System Versioning?​

Business Value​

How System Versioning Works​

Enterprise Versions (Snapshots)​

Anatomy of a Snapshot​

Creating Snapshots​

Viewing Snapshots​

List All Snapshots​

View Snapshot Details​

Compare Snapshots​

Tagging Snapshots​

Adding Tags​

Removing Tags​

Listing by Tag​

Common Tagging Strategies​

Bulk Tag Management​

Interactive Bulk Tagging​

Silent Mode (Non-Interactive)​

Bulk Operations​

Rolling Back​

Full System Rollback​

Cabinet-Level Rollback​

Asset-Level Rollback​

When to Use Each Rollback Type​

Reproducible Environments​

Replicate Production to Staging​

Create Testing Environment from Snapshot​

Clone Production for Training​

Best Practices​

1. Tag Important Snapshots Immediately​

2. Tag Before Risky Changes​

3. Keep Snapshots Organized​

4. Regular Cleanup​

5. Document Snapshot Decisions​

6. Test Rollback Procedures​

Integration with CI/CD​

GitHub Actions Example​

GitLab CI Example​

Comparison with Other Approaches​

Advanced: Snapshot Automation​

Scheduled Tagging​

Snapshot Retention Policies​

Snapshot Webhooks​

Troubleshooting​

Problem: Snapshot doesn't match production​

Problem: Rollback fails​

Problem: Snapshot differences unclear​

FAQ​

Related Documentation​