Concept and guide for Cloud-Agnostic Image feature

[seokho-son]

Cloud-Agnostic Image

Comprehensive guide for automated CSP-agnostic custom image creation using CB-Tumblebug

📑 Table of Contents

1. Overview
2. Key Features
3. Workflow Architecture
4. API Reference
5. Usage Scenarios

---

Overview

What is Cloud-Agnostic Image?

Cloud-Agnostic Image is a high-level workflow in CB-Tumblebug that automates the entire lifecycle of creating custom machine images (snapshots) across multiple cloud providers. It handles infrastructure provisioning, software installation (via post-commands), snapshot creation, and resource cleanup in a single API call.

Why Use Cloud-Agnostic Image?

Problem:

• Creating custom images manually involves multiple steps: Provision VM → Install Software → Verify → Stop VM → Create Image → Delete VM.
• Doing this across multiple clouds (AWS, Azure, GCP, etc.) requires different tools and procedures.
• Managing the timing (waiting for VM to be ready, waiting for image to be available) is complex and error-prone.

Solution:

• One-Click Automation: Define your infrastructure and software once, and Tumblebug handles the rest.
• CSP Agnostic: Works uniformly across all supported cloud providers.
• Resource Efficiency: Automatically cleans up expensive compute resources after the image is secured.

Key Highlights

✅ End-to-End Automation: From empty state to ready-to-use custom image in one request.
✅ Parallel Processing: Creates snapshots for multiple VMs (subgroups) simultaneously.
✅ Smart Cleanup: Automatically terminates temporary VMs only after images are confirmed "Available".
✅ Error Handling: Uses "Refine" policy to handle partial provisioning failures gracefully.
✅ Status Tracking: Monitors image creation progress and ensures availability before cleanup.

---

Key Features

1. Automated Workflow

The system executes a strictly ordered sequence of operations:

1. Provisioning: Creates a temporary MCI (Multi-Cloud Infrastructure) based on your specifications.
2. Configuration: Executes post-deployment commands (e.g., apt install nginx) to set up the software environment.
3. Snapshotting: Triggers CSP-native snapshot mechanisms for each running VM.
4. Verification: Actively polls image status until it transitions to Available.
5. Cleanup: Terminates the temporary MCI to prevent unnecessary costs (optional but recommended).

2. Parallel Snapshot Creation

• Identifies the first running VM in each SubGroup.
• Executes snapshot requests in parallel across different providers.
• Uses provider-specific semaphores to prevent API rate limiting.

3. Safety Mechanisms

• Wait-for-Available: The system does not delete the source VM until the created image is fully registered and available.
• Partial Failure Handling: If some VMs fail to provision, the system proceeds with snapshotting the successful ones.
• Cleanup Protection: If snapshot creation fails completely, cleanup can still be enforced to avoid zombie resources.

---

Workflow Architecture

1. Overall Execution Sequence

The following sequence diagram illustrates the interaction between the user, Tumblebug components, and the underlying CB-Spider layer.

sequenceDiagram
    actor User
    participant API as Tumblebug API
    participant MCI as MCI Manager
    participant Snap as Snapshot Manager
    participant Spider as CB-Spider
    
    User->>API: POST /buildAgnosticImage
    
    rect rgb(230, 240, 255)
        Note over API,MCI: Phase 1: Provisioning
        API->>MCI: CreateMciDynamic (Policy="refine")
        MCI->>Spider: Create VMs
        Spider-->>MCI: VMs Created
        MCI-->>API: MCI Info
        
        API->>MCI: GetMciStatus
        MCI-->>API: Running Count
    end
    
    rect rgb(255, 245, 230)
        Note over API,Snap: Phase 2: Snapshotting
        API->>Snap: CreateMciSnapshot
        
        par Parallel per SubGroup
            Snap->>Spider: Create Image (VM 1)
            Snap->>Spider: Create Image (VM 2)
        end
        
        Spider-->>Snap: Image IDs
        Snap-->>API: Snapshot Results
    end
    
    rect rgb(255, 255, 230)
        Note over API,Snap: Phase 3: Verification
        loop Until Available or Timeout
            API->>Snap: Check Image Status
        end
    end
    
    rect rgb(255, 230, 230)
        Note over API,MCI: Phase 4: Cleanup
        API->>MCI: DelMci (Terminate)
    end
    
    API-->>User: Final Result

Loading

2. Smart Snapshot Strategy

Tumblebug optimizes the snapshot process by selecting representative VMs and managing API concurrency limits per provider.

flowchart TD
    Start([Start Snapshot Process]) --> GetVMs[Get All VMs in MCI]
    
    subgraph Selection [Target Selection]
        GetVMs --> GroupSG[Group by SubGroup]
        GroupSG --> FilterRunning[Filter Running VMs]
        FilterRunning --> SelectOne[Select First Running VM / per SubGroup]
    end
    
    subgraph Concurrency [Provider-Aware Parallelism]
        SelectOne --> GroupProv[Group by Provider]
        
        GroupProv --> AWS[AWS Tasks]
        GroupProv --> Azure[Azure Tasks]
        GroupProv --> GCP[GCP Tasks]
        
        AWS --> SemAWS{Semaphore Limit: 3}
        Azure --> SemAzure{Semaphore Limit: 3}
        GCP --> SemGCP{Semaphore Limit: 3}
    end
    
    SemAWS --> ExecAWS[Execute Snapshot]
    SemAzure --> ExecAzure[Execute Snapshot]
    SemGCP --> ExecGCP[Execute Snapshot]
    
    ExecAWS --> Collect[Collect Results]
    ExecAzure --> Collect
    ExecGCP --> Collect
    
    Collect --> End([Return Results])
    
    style Selection fill:#e1f5fe
    style Concurrency fill:#fff3e0
    style SelectOne stroke:#d32f2f,stroke-width:2px

Loading

3. Verification and Cleanup Logic

The system ensures images are usable before destroying the source infrastructure.

stateDiagram-v2
    [*] --> SnapshotCreated
    
    state "Waiting for Availability" as Waiting {
        SnapshotCreated --> InitialSleep: Sleep 15s
        InitialSleep --> CheckStatus
        
        CheckStatus --> AllAvailable: Yes
        CheckStatus --> AnyPending: No
        
        AnyPending --> CheckTimeout: > 10 mins?
        CheckTimeout --> SleepLoop: No
        SleepLoop --> CheckStatus: Sleep 10s
        
        CheckTimeout --> TimeoutWarning: Yes
    }
    
    AllAvailable --> CleanupDecision
    TimeoutWarning --> CleanupDecision
    
    state "Cleanup Phase" as Cleanup {
        CleanupDecision --> TerminateMCI: Cleanup=true
        CleanupDecision --> KeepMCI: Cleanup=false
        
        TerminateMCI --> Result
        KeepMCI --> Result
    }
    
    Result --> [*]

Loading

State Transitions

Stage	Description	Typical Duration
Provisioning	Creating VMs and installing software	2 - 10 mins
Snapshotting	Triggering CSP snapshot APIs	1 - 5 mins
Waiting	Waiting for cloud provider to finalize image	5 - 20 mins
Cleanup	Terminating resources	1 - 3 mins

4. Lifecycle: Build Once, Deploy Many

Once a custom image is created, it becomes a reusable asset within Tumblebug. You can use the generated imageId to spawn multiple identical VM instances, enabling rapid scaling and consistent deployments.

flowchart TD
    subgraph BuildPhase [Phase 1: Build]
        SourceMCI[Source MCI] -->|Snapshot| CustomImg[Custom Image / ID: nginx-custom-image-g1]
        SourceMCI -.->|Cleanup| Terminated[Terminated]
    end

    subgraph DeployPhase [Phase 2: Deploy & Scale]
        CustomImg -->|Reference by imageId| NewMCI1[Production MCI 1]
        CustomImg -->|Reference by imageId| NewMCI2[Production MCI 2]
        CustomImg -->|Reference by imageId| ScaleOut[Scale Out Existing MCI]
        
        NewMCI1 --> VM1[VM Instance 1]
        NewMCI1 --> VM2[VM Instance 2]
        NewMCI2 --> VM3[VM Instance 3]
    end
    
    style CustomImg fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
    style BuildPhase fill:#f5f5f5
    style DeployPhase fill:#e3f2fd

Loading

How to Reuse:
Simply use the imageId returned from the build process in your standard MCI creation request:

{
  "vm": [
    {
      "imageId": "nginx-custom-image-g1",
      "specId": "aws-t3-small",
      "name": "prod-vm-01"
    }
  ]
}

---

API Reference

Create Agnostic Image

Endpoint: POST /ns/{nsId}/buildAgnosticImage

Request Body:

{
  "sourceMciReq": {
    "name": "build-image-mci",
    "vm": [
      {
        "subGroupSize": "1",
        "name": "base-vm",
        "imageId": "ubuntu-22.04",
        "specId": "aws-t3-small",
        "vmUserPassword": "mypassword"
      }
    ],
    "postCommand": {
      "command": [
        "sudo apt-get update",
        "sudo apt-get install -y nginx"
      ]
    }
  },
  "snapshotReq": {
    "name": "nginx-custom-image",
    "description": "Ubuntu 22.04 with Nginx pre-installed"
  },
  "cleanupMciAfterSnapshot": true
}

Parameters:

Parameter	Type	Required	Default	Description
sourceMciReq	object	Yes	-	Standard MCI creation request with VM specs and post-commands
snapshotReq	object	Yes	-	Configuration for the resulting images (name, description)
cleanupMciAfterSnapshot	boolean	No	true	Whether to delete the MCI after successful image creation

Response: 200 OK

{
  "namespace": "default",
  "mciId": "build-image-mci",
  "mciStatus": "Terminated",
  "mciCleanedUp": true,
  "totalDuration": "12m45s",
  "message": "Successfully created 1 custom images from MCI build-image-mci and cleaned up infrastructure",
  "snapshotResult": {
    "mciId": "build-image-mci",
    "successCount": 1,
    "failCount": 0,
    "results": [
      {
        "subGroupId": "g1",
        "vmId": "base-vm-01",
        "status": "Success",
        "imageId": "nginx-custom-image-g1",
        "imageInfo": { ... }
      }
    ]
  }
}

---

Usage Scenarios

1. Golden Image Pipeline

Create a standardized "Golden Image" with security patches and compliance tools pre-installed.

• Input: Base OS image (e.g., Ubuntu 22.04)
• Post-Command: Security hardening scripts, monitoring agent installation
• Output: Hardened custom image ready for production deployment

2. Application Pre-baking

Pre-install complex application stacks to reduce boot time for scaling groups.

• Input: Base OS
• Post-Command: docker install, git clone app, npm install
• Output: Application-ready image that starts serving traffic immediately upon boot

3. Cross-Cloud Replication

(Requires running the workflow for each CSP)

• Define one BuildAgnosticImage request structure.
• Change only the specId and imageId for the target cloud (AWS, Azure, GCP).
• Execute to get functionally identical images across different clouds.

---

Testing based on GUI

request

result