Skip to main content

Container Images

Overview​

The Container Images panel (also known as the Image Builder) enables users to build custom Docker container images from Dockerfiles stored in Git repositories. This feature integrates with Harbor registry to store built images and provides a complete workflow for creating, managing, and tracking container image builds. Users can build images from any branch or commit, tag them for organization, view build logs, and convert successful builds into Environment Configs for use in Shakudo workloads.

Access & Location​

  • Route: ?panel=container-images
  • Navigation: Shakudo Objects → Container Images
  • Access Requirements: None (available to all authenticated users)
  • Feature Flags: harborImageBuilderEnabled - Harbor registry must be installed and active for this feature to be available

Key Capabilities​

Build Docker Images from Git​

Create custom container images by specifying a Dockerfile path in a Git repository. The system builds the image using Harbor's in-cluster image builder and stores the resulting artifact in the Harbor registry.

Tag and Version Management​

Apply multiple tags to images for easy identification and versioning. Tags are displayed as chips throughout the interface and can be used to organize and track different versions of the same image.

Clone Existing Builds​

Duplicate existing image build configurations to quickly create new builds with minor modifications. All settings (image name, tags, Git repository, branch, commit, and Dockerfile path) are pre-populated from the source build.

Convert to Environment Config​

Transform successful image builds directly into Environment Configs (EC), enabling the custom images to be used as base containers for Sessions, Jobs, and Microservices throughout the platform.

Track Build Status​

Monitor the progress of image builds in real-time with status indicators (Building, Built, Failed, Local). View live logs during active builds and access historical logs through integrated Grafana links.

Apply filters by image name, digest, creation date, status, branch name, Git commit, and owner email. Quick search functionality allows searching across image names and digests simultaneously.

Pin Important Images​

Pin frequently used or important images to keep them at the top of the table for easy access.

User Interface​

Main View​

The main panel displays a hierarchical data grid showing all container images grouped by image name. Each image name acts as a parent row that can be expanded to reveal historical builds of that image, sorted by creation date (newest first). The table supports pagination with 20 items per page and automatically refreshes every 30 seconds to show updated build statuses.

Table Columns:

  • Image Name (expandable group) - Shows the base image name with pin button and detail link
  • Tag - Displays image tags as chips with a menu for viewing all tags when multiple exist
  • Status - Visual status indicator (Building, Built, Failed, Local)
  • Logs - Live log viewer for active builds and Grafana link for historical logs
  • Build Date - Timestamp of when the build was initiated (YYYY-MM-DD HH:mm:ss format)
  • Git Commit ID - Copyable commit hash used for the build
  • SHA256 Hash - Copyable image digest identifier
  • Actions - Dropdown menu with available operations

Toolbar Features:

  • Filter button with comprehensive filtering dialog
  • Column visibility toggle
  • Refresh button
  • Quick search field
  • Reset Filters button
  • Active filter chips with individual remove buttons

Dialogs & Modals​

  1. Build Docker Image Dialog

    • Purpose: Create a new container image build job
    • Fields:
      • Image Name (required) - Name for the container image
      • Tags (required, multiple) - Press Enter to add each tag
      • Git Repository (required, autocomplete) - Select from configured Git repositories
      • Branch (required) - Git branch name
      • Commit (optional) - Specific commit hash, uses branch HEAD if omitted
      • Dockerfile Path (required, autocomplete) - Relative path from repository root to Dockerfile
    • Actions: Cancel, Create (with loading indicator)
    • Features: Includes tutorial component link for guidance

  2. Filter Dialog

    • Purpose: Apply advanced filters to the image list
    • Fields:
      • Image Name (text search)
      • Image Digest (text search)
      • Job ID (text search)
      • Creation Date Range (start and end dates)
      • Status (dropdown: Building, Built, Failed, Local)
      • Branch Name (text)
      • Git Commit (text)
      • Owner Email (text)
    • Actions: Apply Filters, Clear All

  3. Delete/Cancel Confirmation Dialog

    • Purpose: Confirm deletion of built images or cancellation of active builds
    • Content: Displays image name and confirmation message
    • Actions: Close, Delete/Cancel (with loading indicator)

  4. Image Build Job Details Panel

    • Purpose: View comprehensive details about a specific build
    • Content:
      • Image name, ID, and owner at the top
      • Status indicator
      • Creation timestamp
      • Image digest (copyable)
      • Image tags (as chips)
      • Full image URL for pulling (copyable)
      • Dockerfile path (copyable)
      • Git repository URL (copyable)
      • Git branch name (copyable)
      • Git commit ID (copyable)
    • Actions:
      • Open in Harbor (for completed builds)
      • Historical Logs (Grafana link)
      • Back button to return to table

Actions Menu​

Each image build has an Actions dropdown menu with the following options:

  1. Open in Harbor (only for Built/Local images)

    • Opens the Harbor registry interface showing the specific image artifact
    • Provides access to security scanning, tags, and pull commands

  2. Clone

    • Creates a duplicate build configuration
    • Opens the Build Docker Image dialog pre-filled with all settings
    • Allows quick creation of similar images with modifications

  3. Convert To EC

    • Transforms the image into an Environment Config
    • Navigates to Environment Configs panel with pre-populated fields
    • Includes image URL, description, and readme (if available)

  4. Delete/Cancel

    • For active builds (Building status): Cancels the build job
    • For completed builds: Deletes both the build record and Harbor image artifact
    • Requires confirmation before execution

Technical Details​

GraphQL Operations​

Queries:

  • getImageBuilderJobs - Retrieves paginated list of image builder jobs with filtering, ordered by pinned status then creation date
  • countImageBuilderJobs - Gets total count of jobs matching filter criteria for pagination
  • searchImageBuilderJobs - Full-text search across image builder jobs by search term
  • GetImageBuildJobVcServerDocument - Fetches Git repository details for a specific build job
  • GetImageBuildJobDescriptionDocument - Retrieves description and readme metadata for EC conversion
  • getImageBuilderLogs - Fetches build logs for live log viewing

Mutations:

  • createImageBuilderJob - Initiates a new container image build with specified Git source and Dockerfile
  • deleteImageandImageBuilderJob - Removes build job record and deletes corresponding Harbor image artifact
  • updateOneImageBuilderJob (via pinImageBuildJob) - Toggles pin status for a build job

Subscriptions:

  • None (uses polling with 30-second interval for status updates)

Component Structure​

  • Main Component: /components/ImageBuilder/ImageBuilderPanel.tsx
  • Table Component: /components/ImageBuilder/ImageBuilderTable.tsx
  • Create Dialog: /components/ImageBuilder/ImageBuilderCreate.tsx
  • Details Panel: /components/ImageBuilder/ImageBuildJobDetailDialog.tsx
  • Action Menu: /components/ImageBuilder/ImageBuilderActionMenu.tsx
  • Filter Dialog: /components/ImageBuilder/ImageBuildTableFilterDialog.tsx
  • Live Log Viewer: /components/ImageBuilder/ImageBuilderLiveLog.tsx
  • Search Results: /components/Search/ContainerImagesSearchResults.tsx

State Management (Jotai Atoms)​

  • ImageBuildJobsPanelSectionAtom - Controls view toggle between table and details ('table' | 'details')
  • ImageBuilderJobsTablePageAtom - Manages pagination state (current page number)
  • ImageBuilderJobFiltersAtom - Stores active filter criteria
  • ImageBuilderJobsDataLoadingAtom - Tracks loading state for UI feedback
  • JobsDetailsValueAtom - Holds currently selected job for details view
  • ImageBuilderOpenCreateDialogAtom - Controls visibility of create dialog
  • ImageBuilderCloneDefaultValuesAtom - Stores values for cloning operations

Common Workflows​

Building a New Container Image​

  1. Click "Create a Container Image" button (disabled if Harbor is not installed)
  2. Enter an image name (e.g., "custom-python-env")
  3. Add one or more tags by typing and pressing Enter (e.g., "v1.0", "latest")
  4. Select a Git repository from the dropdown
  5. Specify the branch name (defaults to branch from repository config)
  6. Optionally specify a commit hash (uses branch HEAD if blank)
  7. Enter the relative path to your Dockerfile (e.g., "./docker/Dockerfile" or "./Dockerfile")
  8. Click "Create" to start the build job
  9. Monitor build progress in the table with live status updates
  10. View live logs by clicking the log icon for active builds
  11. Once completed (status: Built), the image is available in Harbor

Cloning and Modifying an Existing Image​

  1. Locate the image you want to clone in the table
  2. Click the "Actions" dropdown button for that image
  3. Select "Clone" from the menu
  4. The Build Docker Image dialog opens with all fields pre-filled
  5. Modify any fields as needed (e.g., change tags, update commit, or adjust image name)
  6. Click "Create" to build the modified image
  7. The new build appears in the table as a separate entry

Converting an Image to an Environment Config​

  1. Locate a successfully built image (status: Built or Local)
  2. Click the "Actions" dropdown for that image
  3. Select "Convert To EC" from the menu
  4. You are automatically redirected to the Environment Configs panel
  5. The image URL is pre-populated in the EC creation form
  6. Complete any additional EC configuration (name, description, resource limits, etc.)
  7. Save the EC to make it available for Sessions, Jobs, and Microservices

Filtering and Finding Images​

  1. Click the filter button in the table toolbar
  2. Set one or more filter criteria:
    • Search by image name or digest
    • Filter by build status (Building, Built, Failed)
    • Specify creation date range
    • Filter by Git branch or commit
    • Filter by owner email
  3. Click "Apply Filters"
  4. Active filters appear as chips below the toolbar
  5. Click the X on any chip to remove that specific filter
  6. Click "Reset Filters" to clear all filters at once
  7. Use the quick search field for real-time filtering across image names and digests

Viewing Detailed Build Information​

  1. Click on any image name in the table (appears as a blue link)
  2. The details panel slides in showing comprehensive build information
  3. Review all metadata, Git source details, and image identifiers
  4. Copy any field value using the copy button
  5. Click "Open in Harbor" to view the image in Harbor's web interface
  6. Click "Historical Logs" to view complete build logs in Grafana
  7. Click "Back" to return to the table view

Deleting or Canceling Builds​

  1. For active builds, click Actions → Cancel to stop the build in progress
  2. For completed builds, click Actions → Delete to remove the build record and Harbor artifact
  3. Confirm the action in the dialog that appears
  4. The image is removed from the table and deleted from Harbor registry

Notes & Tips​

  • Harbor Dependency: The Container Images feature requires Harbor registry to be installed and in ACTIVE status. If Harbor is not available, the "Create a Container Image" button will be disabled with a tooltip explaining the requirement.

  • Image Hierarchy: The table groups builds by image name, allowing you to see the history of builds for each image. Expand an image name to see all historical builds sorted by date (newest first).

  • Tag Strategy: Use meaningful tags like version numbers (v1.0, v2.0) or environment indicators (dev, staging, prod) to organize your images. Multiple tags can be applied to the same build.

  • Commit Specificity: Specifying a commit hash ensures reproducible builds. If omitted, the build uses the HEAD of the specified branch, which may change over time.

  • Dockerfile Paths: The Dockerfile path is relative to the Git repository root. Common paths include ./Dockerfile, ./docker/Dockerfile, or ./path/to/custom.Dockerfile.

  • Build Monitoring: Builds are automatically polled every 30 seconds for status updates. For real-time monitoring, use the live log viewer available for active builds.

  • Image URLs: Built images are stored in Harbor at harbor.{domain}/in-cluster-image-builder/{imageName}@{digest}. Use this full URL when referencing the image in Environment Configs or direct Docker pulls.

  • Security Scanning: After builds complete, Harbor automatically performs security vulnerability scanning on images. Access these reports through the "Open in Harbor" action.

  • Pin for Quick Access: Pin frequently used or important images to keep them at the top of the table, making them easier to find when working with many images.

  • EC Conversion Benefits: Converting images to Environment Configs allows them to be used throughout Shakudo with proper resource management, access control, and metadata tracking.

  • Search Integration: Container images are indexed in the global platform search (Cmd/Ctrl+K). Search results show image name, tags, Dockerfile source, owner, and creation date.

  • Filtering Persistence: Filters can be saved in the URL query parameters, allowing you to bookmark specific filtered views of your images.

  • Role-Based Filtering: Users without elevated permissions automatically see only their own images. Administrators and users with appropriate roles can see all images across the platform.

  • Tutorial Available: Click the video icon next to the panel title to watch a tutorial on using the Container Images feature.

Last updated on by chyuen-devsentient