Checkpoint Commands

The teactl checkpoint commands create and manage environment checkpoints (snapshots). Checkpoints capture the complete state of an environment, allowing quick restoration for training resets or disaster recovery.

teactl checkpoint create

Create a checkpoint of an environment.

teactl checkpoint create <env> [flags]

Flags

Examples

# Interactive creation
teactl checkpoint create march-seminar

# With all options
teactl checkpoint create march-seminar 
  --name "end-of-module-3" 
  --description "Completed GitLab CI setup, all pipelines passing" 
  --wait

Interactive flow:

$ teactl checkpoint create march-seminar
? Checkpoint name: end-of-module-3
? Description (optional): Completed GitLab CI setup, all pipelines passing

Creating checkpoint 'end-of-module-3'...
  ✓ Paused environment
  ✓ Captured cluster state
  ✓ Captured volumes (3/3)
  ✓ Captured database snapshots
  ✓ Resumed environment

✓ Checkpoint created successfully

Checkpoint: end-of-module-3
Size: 2.3 GB
Duration: 45 seconds
Resources: 15 captured

Restore with:
  teactl checkpoint restore end-of-module-3

teactl checkpoint list

List checkpoints for an environment.

teactl checkpoint list <env> [flags]

Flags

Examples

# List all checkpoints
teactl checkpoint list march-seminar

# Manual checkpoints only
teactl checkpoint list march-seminar --type manual

Sample output:

$ teactl checkpoint list march-seminar
NAME              TYPE       SIZE     CREATED         DESCRIPTION
end-of-module-3   manual     2.3 GB   2 hours ago     Completed GitLab CI setup
start-of-day-2    manual     1.8 GB   1 day ago       Clean state for day 2
auto-20240115     automatic  2.1 GB   6 hours ago     Scheduled checkpoint
auto-20240114     automatic  1.9 GB   1 day ago       Scheduled checkpoint

Total: 4 checkpoints (2 manual, 2 automatic)
Storage used: 8.1 GB

teactl checkpoint get

Show detailed information about a checkpoint.

teactl checkpoint get <id> [flags]

Flags

Examples

teactl checkpoint get end-of-module-3

Sample output:

$ teactl checkpoint get end-of-module-3
Name: end-of-module-3
Environment: march-seminar
Type: manual
Status: Ready

Created: 2024-01-15 14:30:00 UTC (2 hours ago)
Size: 2.3 GB
Duration: 45 seconds

Description:
  Completed GitLab CI setup, all pipelines passing

Captured Resources:
  RESOURCE                TYPE              SIZE
  main-cluster            kubernetes        850 MB
  gitlab-data             volume            1.2 GB
  postgresql-data         volume            180 MB
  runner-cache            volume            70 MB
  
Metadata:
  Blueprint: gitlab-cicd v1.2.0
  Participants: 15
  Environment age: 4 hours
  
Restore command:
  teactl checkpoint restore end-of-module-3

teactl checkpoint restore

Restore an environment from a checkpoint.

teactl checkpoint restore <id> [flags]

Flags

Examples

# Restore in-place (same environment)
teactl checkpoint restore end-of-module-3

# Restore to new environment
teactl checkpoint restore end-of-module-3 --to march-seminar-copy

# Skip confirmation
teactl checkpoint restore end-of-module-3 --yes --wait

Restore confirmation:

$ teactl checkpoint restore end-of-module-3
Checkpoint: end-of-module-3
Environment: march-seminar
Created: 2 hours ago

This will:
  ⚠ Replace current environment state with checkpoint
  ⚠ Terminate all active participant sessions
  ⚠ Reset all databases and storage to checkpoint state
  
Current state will be lost. Create a checkpoint first if needed.

Restore checkpoint? [y/N] y

Restoring checkpoint...
  ✓ Stopped environment
  ✓ Restored cluster state
  ✓ Restored volumes (3/3)
  ✓ Restored databases
  ✓ Started environment

✓ Checkpoint restored successfully

Environment 'march-seminar' is now at checkpoint 'end-of-module-3'

Restore to New Environment

Create a new environment from a checkpoint:

$ teactl checkpoint restore end-of-module-3 --to day2-practice
Creating new environment from checkpoint...

Environment: day2-practice
Blueprint: gitlab-cicd v1.2.0
From checkpoint: end-of-module-3

  ✓ Created environment record
  ✓ Restored cluster state
  ✓ Restored volumes (3/3)
  ✓ Restored databases
  ✓ Configured networking

✓ Environment 'day2-practice' created from checkpoint

Access: https://day2-practice.env.teabar.dev

teactl checkpoint diff

Compare checkpoints or checkpoint vs live state.

teactl checkpoint diff <id> [flags]

Flags

Examples

# Compare checkpoint to current state
teactl checkpoint diff end-of-module-3 --against live

# Compare two checkpoints
teactl checkpoint diff end-of-module-3 --against start-of-day-2

Sample output:

$ teactl checkpoint diff end-of-module-3 --against live
Comparing: end-of-module-3 → live state

RESOURCE            CHECKPOINT         LIVE              CHANGE
Deployments         12                 14                +2 added
ConfigMaps          8                  9                 +1 added
Secrets             5                  5                 unchanged
PVCs                3                  3                 unchanged
Services            6                  7                 +1 added

Database rows       1,234              1,456             +222 rows
Volume usage        1.2 GB             1.4 GB            +200 MB

Changes since checkpoint:
  + deployment/nginx created
  + deployment/redis created
  + service/redis created
  + configmap/nginx-config created
  ~ configmap/app-config modified

teactl checkpoint delete

Delete checkpoints.

teactl checkpoint delete <id>... [flags]

Flags

Examples

# Delete single checkpoint
teactl checkpoint delete old-checkpoint

# Delete multiple
teactl checkpoint delete checkpoint-1 checkpoint-2 checkpoint-3

# Delete old checkpoints
teactl checkpoint delete --older-than 30d --yes

$ teactl checkpoint delete end-of-module-3
Checkpoint: end-of-module-3
Size: 2.3 GB
Created: 2 hours ago

This will permanently delete the checkpoint.
Environment data will not be affected.

Delete checkpoint? [y/N] y

✓ Checkpoint deleted
  Freed 2.3 GB of storage

Automatic Checkpoints

Teabar can create automatic checkpoints on a schedule.

Configure in Blueprint

spec:
  checkpoints:
    automatic:
      enabled: true
      schedule: "0 */6 * * *"  # Every 6 hours
      retention: 5              # Keep last 5 automatic checkpoints

View Automatic Checkpoints

teactl checkpoint list march-seminar --type automatic

Configure via CLI

# Enable automatic checkpoints
teactl env update march-seminar --checkpoints-enabled --checkpoints-schedule "0 */6 * * *"

# Disable
teactl env update march-seminar --checkpoints-enabled=false

Best Practices

Create Checkpoints at Key Milestones

# Before starting new module
teactl checkpoint create workshop 
  --name "before-module-4" 
  --description "Ready to start Kubernetes deployment module"

# After completing exercises
teactl checkpoint create workshop 
  --name "exercises-complete" 
  --description "All participants completed hands-on exercises"

Use Descriptive Names

# Good: Clear purpose and timing
teactl checkpoint create workshop --name "day1-end" --description "End of day 1, CI pipelines configured"

# Avoid: Unclear names
teactl checkpoint create workshop --name "checkpoint1"

Plan Restoration Points

For multi-day workshops, create checkpoints at natural break points:

# End of each day
teactl checkpoint create workshop --name "day1-end"
teactl checkpoint create workshop --name "day2-end"

# Before exercises (for reset if needed)
teactl checkpoint create workshop --name "before-exercise-3"

Clean Up Old Checkpoints

# Review checkpoint usage
teactl checkpoint list march-seminar

# Delete old checkpoints
teactl checkpoint delete --older-than 7d --yes

Common Workflows

Training Reset

Reset environment to a known good state:

# Restore to clean state
teactl checkpoint restore start-of-exercises --yes --wait

# Verify environment is ready
teactl env get march-seminar

Disaster Recovery

# List available checkpoints
teactl checkpoint list march-seminar

# Restore most recent
teactl checkpoint restore auto-20240115 --yes --wait

Clone Environment

Create a copy of an environment at a specific point:

# Create checkpoint of source
teactl checkpoint create source-env --name "for-clone"

# Create new environment from checkpoint
teactl checkpoint restore for-clone --to cloned-env

Related Commands

• env - Environment management
• activity - View activity since checkpoint