Docker Image Automation

Purpose

This subtopic addresses the need for an automated, reliable, and efficient mechanism to build, tag, cache, and push Docker images used in deploying blockchain node services, indexers, and APIs. In the broader context of deployment automation, Docker Image Automation ensures that container images are consistently created with proper versioning and caching, minimizing build times and avoiding redundant uploads. It tackles challenges such as verifying existing image tags to prevent unnecessary rebuilds and managing multi-tag images essential for Kubernetes deployments.

Functionality

At its core, Docker Image Automation provides utilities to:

• Authenticate and interact with Docker registries securely for pushing images.

• Build Docker images from specified contexts and Dockerfiles, supporting:

  • Custom build arguments.

  • Environment variables influencing the build process.

  • Cache optimizations via --cache-from to reuse layers from previous builds.

• Tag images with multiple tags, including semantic or hash-based tags and a default latest tag.

• Check for the existence of an image tag remotely before deciding to build and push, saving time and bandwidth.

• Push all built tags to the configured Docker registry unless running in a dry-run environment (e.g., Pulumi preview).

Key Workflow Example

1. Tag Existence Check:

   Before building an image, the system queries the Docker Hub API to verify if an image tag already exists.

   const exists = await hasTag('username/my-image', 'v1.0.0')
   if (!exists) {
     // Proceed with build and push
   }
   

2. Image Building and Tagging:

   The build function constructs Docker CLI arguments, incorporating:

   • Multiple tags (-t image:tag).

   • Build arguments (--build-arg).

   • Cache layers (--cache-from).

   • Custom Dockerfile if provided (-f Dockerfile).

   • Build context directory.

   It then runs `docker build` with these parameters and environment variables.

3. Image Pushing:

   After successful build, all tags are pushed to the Docker registry using docker push.

4. Integration with Pulumi Deployment:

   Higher-level functions use these utilities to build base images tagged with content hashes to ensure uniqueness and cacheability, as seen in:

   if (!(await hasTag(baseImage, baseTag))) {
     await buildAndPushImage({ /* ... */ })
   }
   

This process reduces redundant builds and network usage by skipping image creation when an exact tag is already published.

Integration

Docker Image Automation complements the broader **Deployment Automation** topic by providing the foundational step of creating container images that Kubernetes will deploy as StatefulSets or services. It integrates tightly with:

• Kubernetes Resource Management: The generated images are referenced in StatefulSet manifests, ensuring that the correct versions are deployed.

• Cluster Setup: Base images built with these utilities form the foundation for all node, indexer, and API service containers in the cluster.

• Infrastructure Scripts: The automation scripts rely on deterministic tagging (e.g., content hashes) to manage image versions consistently across environments.

• Pulumi Deployment Pipelines: Pulumi scripts invoke image building and pushing, ensuring infrastructure and container images remain in sync.

This subtopic introduces the critical feature of **remote tag existence checks** (`hasTag`) to avoid unnecessary builds, which is not covered by other deployment automation aspects. Also, the detailed handling of multi-tag builds with caching is unique here.

Diagram

flowchart TD
  Start[Start Deployment] --> CheckTag[Check if Image Tag Exists]
  CheckTag -->|Tag Exists| SkipBuild[Skip Build and Push]
  CheckTag -->|Tag Missing| BuildImage[Build Docker Image]
  BuildImage --> TagImage[Apply Multiple Tags]
  TagImage --> PushImage[Push Tags to Registry]
  SkipBuild --> End[Deployment Continues]
  PushImage --> End

This flowchart illustrates the core decision-making process in Docker Image Automation, emphasizing the optimization of skipping builds when the image tag already exists remotely.

By automating Docker image lifecycle management with caching, tagging, and remote tag verification, this subtopic ensures efficient, reproducible, and scalable container deployments within the blockchain infrastructure platform.