github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/adr/0012-local-image-support-via-docker.md (about)

     1  # 12. Local Image Support Via Docker
     2  
     3  Date: 2023-02-06
     4  
     5  ## Status
     6  
     7  Accepted
     8  
     9  ## Context
    10  
    11  There has been a long-standing usability gap with Jackal when doing local development due to a lack of local image support. A solution was merged in, [#1173](https://github.com/Racer159/jackal/pull/1173), and released in [v0.23.4](https://github.com/Racer159/jackal/releases/tag/v0.23.4) to support this feature. Unfortunately, we didn't realize there is a [glaring issue](https://github.com/Racer159/jackal/issues/1214) with the implementation that causes Jackal to crash when trying to load large images into the local docker daemon.  The docker daemon support in Crane is somewhat naive and can send a machine into an OOM condition due to how the tar stream is loaded into memory from the docker save action. Crane does have an option to avoid this issue, but at the cost of being much slower to load images from docker.
    12  
    13  We did extensive investigation into various strategies of loading docker images from the daemon including: crane, skopeo, the docker go client and executing the docker cli directly with varying levels of success. Unfortunately, some of the methods that did work well were up to 3 times slower than the current implementation, though they avoided the OOM issue. Lastly, the docker daemon save operations directly still ended up being slower than crane and docker produced a legacy format that would cause issues with [future package schema changes](https://github.com/Racer159/jackal/issues/1319) we are planning for oci imports.
    14  
    15  |                                                    | **Docker** | **Crane** |
    16  | -------------------------------------------------- | ---------- | --------- |
    17  | Big Bang Core (cached)                             | 3m 1s      | 1m 58s    |
    18  | Big Bang Core (cached + skip-sbom)                 | 1m 51s     | 56s       |
    19  | 20 GB Single-Layer Image (local registry)          |            | 6m 14s    |
    20  | 20 GB Single-Layer Image (local registry + cached) | 5m 2s      | 2m 10s    |
    21  
    22  ## Decision
    23  
    24  We had hoped to leverage docker caching and avoid crane caching moreso, but realized that caching was still occurring via Syft for SBOM. Additionally, the extremely-large, local-only image is actually the edge case here and we created a recommended workaround in the FAQs as well as an inline alert when a large docker image is detected. This restores behavior to what it was before the docker daemon support was added, but with the added benefit of being able to load images from the docker daemon when they are available locally.
    25  
    26  ## Consequences
    27  
    28  For most cases this will be a seamless transition back to the previous behavior while still supporting local-only images. While this will work for large images too, it will be slow and this is automatically communicated to the user via a warning/recommendation to use a local registry.