Image Search API Guide. How to use ​POST /ns/{nsId}/resources/searchImage

[seokho-son]

CB-Tumblebug: Image Search API Guide

Overview

CB-Tumblebug provides a REST API for searching VM images available across multiple cloud providers and regions. This guide explains how to use the RestSearchImage API to find compatible images for your workload, and how to use the RestSearchImageOptions API to explore available search parameters.

🛠️ Currently, the {nsId} path parameter must be "system". Other namespaces are not supported.

---

Image Search API Overview

The image search API enables:

• Filtering by matchedSpecId (e.g., aws+ap-northeast-2+t2.small)
• Filtering by cloud provider (AWS, Azure, GCP, etc.)
• Filtering by region
• Matching OS types and versions (e.g., Ubuntu 22.04)
• Filtering by architecture (x86_64, arm64, etc.)
• Filtering images with GPU or Kubernetes support
• Searching only asset-registered images
• Performing detailed keyword-based image searches

---

Search Request Structure

API Endpoint

• POST /tumblebug/ns/{nsId}/resources/searchImage

Replace {nsId} with "system".

---

Request Body

The request body is a JSON object where all fields are optional.

• If no fields are provided, the API will return the entire image list available in the system.
• If one or more fields are provided, the API applies AND conditions to filter images that match all specified criteria.

You may use any combination of the following fields:

{
  "detailSearchKeys": ["tensorflow", "2.17"],
  "includeDeprecatedImage": false,
  "isGPUImage": false,
  "isKubernetesImage": false,
  "isRegisteredByAsset": false,
  "osArchitecture": "x86_64",
  "osType": "ubuntu 22.04",
  "providerName": "aws",
  "regionName": "us-east-1"
}

---

Field Descriptions

Field	Type	Required	Description
providerName	string	No	Cloud provider name (aws, azure, etc.)
regionName	string	No	Cloud region (ap-northeast-2, us-east-1, etc.)
osType	string	No	OS type and version (e.g., "ubuntu 22.04")
osArchitecture	string	No	CPU architecture (x86_64, arm64, etc.)
isGPUImage	boolean	No	GPU-supported image
isKubernetesImage	boolean	No	Kubernetes-optimized image
isRegisteredByAsset	boolean	No	Asset file registered images only
includeDeprecatedImage	boolean	No	Include deprecated images (default: false)
detailSearchKeys	string[]	No	Keywords for deeper filtering (AND logic)

---

Usage Examples

Quick and Easy Search Example with additional validation among spec and image pairs

POST /tumblebug/ns/system/resources/searchImage

Request Body

{
  "osType": "ubuntu 22.04",
  "matchedSpecId": "aws+ap-northeast-2+t2.small"
}

Basic Filter Search Example

POST /tumblebug/ns/system/resources/searchImage

Request Body

{
  "osArchitecture": "x86_64",
  "osType": "ubuntu 22.04",
  "providerName": "aws",
  "regionName": "ap-northeast-2"
}

---

Advanced Search Example

POST /tumblebug/ns/system/resources/searchImage

Request Body

{
  "detailSearchKeys": ["tensorflow", "2.17"],
  "includeDeprecatedImage": false,
  "isGPUImage": false,
  "isKubernetesImage": false,
  "isRegisteredByAsset": false,
  "osArchitecture": "x86_64",
  "osType": "ubuntu 22.04",
  "providerName": "aws",
  "regionName": "us-east-1"
}

---

Response Example

{
  "imageCount": 42,
  "imageList": [
    {
      "providerName": "aws",
      "id": "aws+ami-0fa30a83d31fe23b7",
      "name": "aws+ami-0fa30a83d31fe23b7",
      "regionList": ["ap-northeast-2"],
      "osType": "Ubuntu 22.04",
      "osArchitecture": "x86_64",
      "isGPUImage": true,
      "osDistribution": "Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 22.04) 20240610",
      "imageStatus": "Available",
      "creationDate": "2024-06-10T18:39:56.000Z",
      "description": "Supported EC2 instances: G4dn, G5, P4d, etc.",
      "details": [
        { "key": "ImageId", "value": "ami-0fa30a83d31fe23b7" },
        { "key": "BootMode", "value": "uefi-preferred" },
        { "key": "PlatformDetails", "value": "Linux/UNIX" }
        // ...
      ]
    }
    // ... additional image objects
  ]
}

---

Search Options API

Search Options API Endpoint

• GET /tumblebug/ns/{nsId}/resources/searchImageOptions

Use this API to retrieve valid option values for image search filters based on the system's current dataset.

---

Example: Search Options Request

GET http://localhost:1323/tumblebug/ns/system/resources/searchImageOptions

---

Example: Search Options Response

{
  "providerName": ["alibaba", "aws", "azure", "gcp", "ibm", "ncpvpc", "nhncloud", "tencent"],
  "regionName": ["ap-northeast-2", "us-east-1", "eu-west-1", "..."],
  "osType": [
    "Ubuntu 20.04", "Ubuntu 22.04", "Amazon Linux 2", "CentOS 7", "Debian 11",
    "Windows 2019", "Red Hat Enterprise Linux 9", "Fedora 39", "Rocky Linux 9", "..."
  ],
  "osArchitecture": ["x86_64", "arm64", "x86_32", "na"],
  "isGPUImage": [true, false],
  "isKubernetesImage": [true, false],
  "isRegisteredByAsset": [true, false],
  "includeDeprecatedImage": [true, false],
  "detailSearchKeys": [
    ["tensorflow", "2.17"],
    ["sql", "2022"],
    ["This is just an example", "omit this option if not needed"]
  ]
}

---

Key Features and Usage Tips

• ✅ Fixed Namespace: Use "system" for all {nsId} values.
• 🧩 Flexible Filters: Use only the fields you care about—omitted fields are ignored.
• 🧠 AND-Based Filtering: All search conditions are combined using AND logic.
• 🌍 Region Matching: Includes results from specified region + "common".
• ⚠️ Empty Search: An empty JSON ({}) returns the entire image list.
• 🔍 Metadata Exploration: Use details for deep inspection of block devices, boot modes, kernel, and more.

---