pull: airgapped mode

Adds a new "airgapped" attribute to the pull rule.
If set, it can be used to ensure that any requests are provided by predownloaded files from "blob_files".

Author: malt3

docs/pull.md

@@ -9,8 +9,8 @@ Public API for pulling base container images.
 <pre>
 load("@rules_img//img:pull.bzl", "pull")
 
-pull(<a href="#pull-name">name</a>, <a href="#pull-blob_files">blob_files</a>, <a href="#pull-digest">digest</a>, <a href="#pull-downloader">downloader</a>, <a href="#pull-layer_handling">layer_handling</a>, <a href="#pull-registries">registries</a>, <a href="#pull-registry">registry</a>, <a href="#pull-repo_mapping">repo_mapping</a>,
-     <a href="#pull-repository">repository</a>, <a href="#pull-tag">tag</a>)
+pull(<a href="#pull-name">name</a>, <a href="#pull-airgapped">airgapped</a>, <a href="#pull-blob_files">blob_files</a>, <a href="#pull-digest">digest</a>, <a href="#pull-downloader">downloader</a>, <a href="#pull-layer_handling">layer_handling</a>, <a href="#pull-registries">registries</a>, <a href="#pull-registry">registry</a>,
+     <a href="#pull-repo_mapping">repo_mapping</a>, <a href="#pull-repository">repository</a>, <a href="#pull-tag">tag</a>)
 </pre>
 
 Pulls a container image from a registry using shallow pulling.
@@ -42,6 +42,7 @@ will resolve the tag to a digest at fetch time and print a warning.
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="pull-name"></a>name |  A unique name for this repository.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="pull-airgapped"></a>airgapped |  Enable airgapped mode.<br><br>When enabled, the pull tool will only use locally cached blobs and will not attempt any network requests. This is useful for completely offline/air-gapped environments where all required blobs must be provided via blob_files.<br><br>If a required blob is not available locally, the pull will fail rather than attempting to download it.   | Boolean | optional |  `False`  |
 | <a id="pull-blob_files"></a>blob_files |  Pre-downloaded blob files to use.<br><br>A dictionary mapping blob digests (e.g., "sha256:abc123...") to file labels. These blobs will be verified and used instead of downloading from the registry when available. This is useful for air-gapped environments or to avoid redundant downloads of common base layers.   | Dictionary: String -> Label | optional |  `{}`  |
 | <a id="pull-digest"></a>digest |  The image digest for reproducible pulls (e.g., "sha256:abc123...").<br><br>When specified, the image is pulled by digest instead of tag, ensuring reproducible builds. The digest must be a full SHA256 digest starting with "sha256:".   | String | optional |  `""`  |
 | <a id="pull-downloader"></a>downloader |  The tool to use for downloading manifests and blobs.<br><br>**Available options:**<br><br>* **`img_tool`** (default): Uses the `img` tool for all downloads.<br><br>* **`bazel`**: Uses Bazel's native HTTP capabilities for downloading manifests and blobs.   | String | optional |  `"img_tool"`  |

img/private/repository_rules/download.bzl

@@ -181,14 +181,15 @@ def get_layers(rctx, digests):
         for digest in digests
     ]
 
-def download_with_tool(rctx, *, tool_path, reference, blob_files = {}):
+def download_with_tool(rctx, *, tool_path, reference, blob_files = {}, airgapped = False):
     """Download an image using the img tool.
 
     Args:
         rctx: Repository context.
         tool_path: The path to the img tool to use for downloading.
         reference: The image reference to download.
         blob_files: Dictionary mapping blob digests to file labels.
+        airgapped: Enable airgapped mode (no network access).
 
     Returns:
         A struct containing manifest and layers of the downloaded image.
@@ -223,6 +224,8 @@ def download_with_tool(rctx, *, tool_path, reference, blob_files = {}):
         "--repository=" + rctx.attr.repository,
         "--layer-handling=" + rctx.attr.layer_handling,
     ] + ["--registry=" + r for r in registries]
+    if airgapped:
+        args.append("--airgapped")
     result = rctx.execute(args, quiet = False)
     if result.return_code != 0:
         fail("img tool failed with exit code {} and message {}".format(result.return_code, result.stderr))

img/private/repository_rules/pull.bzl

@@ -61,6 +61,7 @@ def _pull_impl(rctx):
             tool_path = tool_path,
             reference = reference,
             blob_files = rctx.attr.blob_files,
+            airgapped = rctx.attr.airgapped,
         )
 
     manifest_kwargs = dict(
@@ -359,6 +360,16 @@ These blobs will be verified and used instead of downloading from the registry w
 This is useful for air-gapped environments or to avoid redundant downloads of common base layers.""",
             allow_files = True,
         ),
+        "airgapped": attr.bool(
+            default = False,
+            doc = """Enable airgapped mode.
+
+When enabled, the pull tool will only use locally cached blobs and will not attempt any network
+requests. This is useful for completely offline/air-gapped environments where all required blobs
+must be provided via blob_files.
+
+If a required blob is not available locally, the pull will fail rather than attempting to download it.""",
+        ),
     },
 )
 

pull_tool/cmd/internal/pull/pull.go

@@ -26,6 +26,7 @@ func PullProcess(ctx context.Context, args []string) {
 	var registries stringSliceFlag
 	var layerHandling string
 	var concurrency int
+	var airgapped bool
 
 	flagSet := flag.NewFlagSet("pull", flag.ExitOnError)
 	flagSet.Usage = func() {
@@ -48,6 +49,7 @@ func PullProcess(ctx context.Context, args []string) {
 	flagSet.Var(&registries, "registry", "Registry to use (can be specified multiple times, defaults to docker.io)")
 	flagSet.StringVar(&layerHandling, "layer-handling", "shallow", "Method used for handling layer data. \"eager\" causes layer data to be materialized.")
 	flagSet.IntVar(&concurrency, "j", 10, "Number of concurrent download workers")
+	flagSet.BoolVar(&airgapped, "airgapped", false, "Enable airgapped mode (only use local cached blobs, no network access)")
 
 	if err := flagSet.Parse(args); err != nil {
 		flagSet.Usage()
@@ -77,7 +79,7 @@ func PullProcess(ctx context.Context, args []string) {
 		os.Exit(1)
 	}
 	// Create a custom HTTP client with cached blob transport
-	transport := cachedblob.NewTransport(outputDir, http.DefaultTransport)
+	transport := cachedblob.NewTransport(outputDir, http.DefaultTransport, cachedblob.WithAirgapped(airgapped))
 
 	// Default to docker.io if no registries specified
 	if len(registries) == 0 {