feat(cluster): add OPENSHELL_DOCKERIO_MIRROR for docker.io mirror support

  Environments where docker.io is blocked (corporate firewalls, air-gapped
  networks) cannot pull k3s system images like rancher/mirrored-pause,
  preventing any pods from starting.

  This adds an OPENSHELL_DOCKERIO_MIRROR environment variable that
  configures a containerd registry mirror for docker.io in the cluster's
  registries.yaml.  When set, unqualified image pulls are redirected to
  the configured mirror instead of docker.io.

  Usage: export OPENSHELL_DOCKERIO_MIRROR="https://mirror.gcr.io"

  Signed-off-by: Andrew Potozniak <potozniak@redhat.com>

Author: tyraziel

architecture/gateway.md

@@ -128,6 +128,7 @@ All configuration is via CLI flags with environment variable fallbacks. The `--d
 | `--sandbox-ssh-port` | `OPENSHELL_SANDBOX_SSH_PORT` | `2222` | SSH listen port inside sandbox pods |
 | `--ssh-handshake-secret` | `OPENSHELL_SSH_HANDSHAKE_SECRET` | None | Shared HMAC-SHA256 secret for gateway-to-sandbox handshake |
 | `--ssh-handshake-skew-secs` | `OPENSHELL_SSH_HANDSHAKE_SKEW_SECS` | `300` | Allowed clock skew (seconds) for SSH handshake timestamps |
+| — | `OPENSHELL_DOCKERIO_MIRROR` | None | Mirror endpoint for docker.io (e.g. `https://mirror.gcr.io`). Used when Docker Hub is blocked by corporate firewalls or air-gapped networks. Without this, k3s system images such as `rancher/mirrored-pause` fail to pull and no pods can start. |
 
 ## Shared State
 

crates/openshell-bootstrap/src/docker.rs

@@ -842,6 +842,11 @@ pub async fn ensure_container(
     if let Some(endpoint) = registry_endpoint {
         env_vars.push(format!("REGISTRY_ENDPOINT={endpoint}"));
     }
+    // Docker Hub mirror for environments where docker.io is blocked
+    // (corporate firewalls, air-gapped networks, rate limiting, etc.).
+    if let Some(mirror) = env_non_empty("OPENSHELL_DOCKERIO_MIRROR") {
+        env_vars.push(format!("OPENSHELL_DOCKERIO_MIRROR={mirror}"));
+    }
     if let Some(password) = effective_password {
         // Default to __token__ when only a password/token is provided.
         let username = effective_username.unwrap_or_else(|| "__token__".to_string());

deploy/docker/cluster-entrypoint.sh

@@ -282,6 +282,21 @@ REGEOF
 REGEOF
 	fi
 
+	# Mirror docker.io to an alternative registry for environments where
+	# Docker Hub is inaccessible (corporate firewalls, air-gapped networks,
+	# rate limiting, etc.). Without this, k3s system images such as
+	# rancher/mirrored-pause fail to pull and no pods can start.
+	if [ -n "${OPENSHELL_DOCKERIO_MIRROR:-}" ]; then
+		echo "Adding docker.io mirror: ${OPENSHELL_DOCKERIO_MIRROR}"
+		cat >>"$REGISTRIES_YAML" <<REGEOF
+  "docker.io":
+    endpoint:
+      - "${OPENSHELL_DOCKERIO_MIRROR}"
+REGEOF
+	else
+		echo "Info: OPENSHELL_DOCKERIO_MIRROR not set; unqualified image pulls will use docker.io directly"
+	fi
+
 	if [ -n "${REGISTRY_USERNAME:-}" ] && [ -n "${REGISTRY_PASSWORD:-}" ]; then
 		cat >>"$REGISTRIES_YAML" <<REGEOF
 
@@ -318,7 +333,22 @@ REGEOF
 		fi
 	fi
 else
-	echo "Warning: REGISTRY_HOST not set; skipping registry config"
+	echo "Warning: REGISTRY_HOST not set; skipping OpenShell component registry mirror config"
+fi
+
+# Mirror docker.io independently of REGISTRY_HOST — even without a
+# component registry configured, k3s still needs to pull system images
+# (e.g. rancher/mirrored-pause) and will fail if docker.io is unreachable.
+if [ -n "${OPENSHELL_DOCKERIO_MIRROR:-}" ] && [ ! -f "$REGISTRIES_YAML" ]; then
+	echo "Configuring docker.io mirror: ${OPENSHELL_DOCKERIO_MIRROR}"
+	cat >"$REGISTRIES_YAML" <<REGEOF
+mirrors:
+  "docker.io":
+    endpoint:
+      - "${OPENSHELL_DOCKERIO_MIRROR}"
+REGEOF
+elif [ ! -f "$REGISTRIES_YAML" ]; then
+	echo "Info: OPENSHELL_DOCKERIO_MIRROR not set; unqualified image pulls will use docker.io directly"
 fi
 
 # Copy bundled Helm chart tarballs to the k3s static charts directory.

docs/reference/support-matrix.md

@@ -54,6 +54,7 @@ To override the default image references, set the following environment variable
 | ------------------------------ | --------------------------------------------------- |
 | `OPENSHELL_CLUSTER_IMAGE`      | Override the cluster image reference.               |
 | `OPENSHELL_COMMUNITY_REGISTRY` | Override the registry for community sandbox images. |
+| `OPENSHELL_DOCKERIO_MIRROR`    | Mirror endpoint for docker.io (e.g. `https://mirror.gcr.io`). Required when Docker Hub is inaccessible. |
 
 ## Kernel Requirements