Container Images

Pulling container images over the network every time you recreate a cluster gets old fast. gck gives you two strategies to speed things up: mirror proxies that cache layers locally, and image preloading that stages images before the cluster starts. The Architecture page shows how these fit into the overall system.

Image mirrors#

Mirror proxies run as local registry:2 containers that cache image layers on your machine. When you delete and recreate a cluster, cached layers are reused – no re-downloading.

How it works#

Each upstream registry gets its own pull-through cache container, bound to a local port. The Kind nodes’ containerd is configured to check the mirror first. Mirror containers keep running until the last gck cluster is deleted, and their cache lives in $GCK_HOME/mirrors, so it survives across cluster lifecycles.

Enabling mirrors#

Add images.mirrors to your gck.yaml:

# Mirror docker.io only (always implicit)
images:
  mirrors: {}
# Mirror docker.io + additional registries
images:
  mirrors:
    upstreams:
      - ghcr.io
      - docker.elastic.co

docker.io is always included – you don’t need to list it explicitly.

Mirror options#

FieldDefaultDescription
upstreams(none)Additional registries to mirror (on top of docker.io)
data$GCK_HOME/mirrorsDirectory for cached layers and containerd host configs

Private registries#

Combine mirrors with component value overrides to pull from a private registry through the local cache:

images:
  mirrors:
    upstreams:
      - acme.example.com

components:
  - name: my-app
    helm:
      valueFiles:
        - values-private.yaml

Image preloading#

As an alternative (or complement) to mirrors, you can preload specific images into the cluster before components are deployed. This is especially useful on CI systems with Docker Layer Caching (DLC).

How it works#

  1. Before the Kind cluster is created, gck pulls each image listed in images.preload.refs on the host Docker daemon.
  2. A local registry:2 container (gck-preload) is started, backed by persistent storage in $GCK_HOME/preload. Pre-pulled images are re-tagged and pushed to this registry.
  3. Kind nodes are configured to check the preload registry first for each upstream referenced by the listed images.

Because the preload registry stores its data on the host filesystem, cached layers survive across cluster lifecycles. When you delete and recreate a cluster, only layers that have actually changed need to be re-pushed – stable images like databases are available instantly. For mutable-tag images (snapshots, latest), gck re-pulls the upstream version and pushes only the changed layers.

Each time a mutable tag moves to a new build, the previous build becomes unreachable: nothing pulls it by tag any more, but its layers stay in storage. For large images rebuilt daily, this adds gigabytes per recreate. gck collects that garbage right after pushing, so $GCK_HOME/preload only holds the images currently tagged. Images pushed by gck build and gck patch are collected on the next gck create; run gck clean preload to reclaim that space immediately.

Enabling preloading#

images:
  preload:
    refs:
      - docker.io/library/mongo:7
      - docker.elastic.co/elasticsearch/elasticsearch:8.17.0
      - bitnami/redis:7.4

Context authors can ship the image list directly in the context gck.yaml, so you don’t have to maintain it yourself.

Private images#

Preload pulls send the credentials docker login stored for the image’s registry, so log in before gck create:

docker login registry.mycompany.com
# or, for Azure Container Registry, which calls docker login:
az acr login --name mycompany

gck reads them from the Docker CLI configuration (DOCKER_CONFIG, DOCKER_AUTH_CONFIG, credsStore and credHelpers). A registry with no stored credential is pulled anonymously. When a registry refuses the stored credential, gck retries the pull once anonymously, so an expired login still pulls public images.

Only preloaded images get these credentials. Kind nodes pull any other image themselves, without them, so list every image a component pulls from a private registry in images.preload.refs.

How preload merges across layers#

When a context composes from parents via from, or when you override preload in your own config, the preload lists are merged by default – your refs are unioned with the inherited ones. This is controlled by the mode field.

FieldDefaultDescription
modemergemerge unions refs with inherited preload. replace discards inherited refs entirely.
refs(none)Image references to preload
skip(none)Image references to exclude from inherited preload (merge mode only)

Merge mode (default)#

In merge mode, refs from every layer are deduplicated and combined. If a context preloads mongo:7 and you add redis:7.4, the cluster gets both:

images:
  preload:
    refs:
      - bitnami/redis:7.4

Omit mode (or set it to merge) to keep this behavior.

Replace mode#

When you need full control over exactly which images are preloaded, set mode: replace. This discards every ref inherited from parent contexts and uses only the refs you list:

images:
  preload:
    mode: replace
    refs:
      - docker.io/library/mongo:7
      - bitnami/redis:7.4

Skipping inherited images#

Sometimes you want to keep most of the inherited preload list but remove a few images – for example, when a context flag disables a component whose images would otherwise be pulled for nothing. Use skip instead of switching to replace mode:

images:
  preload:
    skip:
      - docker.elastic.co/elasticsearch/elasticsearch:8.17.0

skip entries accumulate across layers the same way refs do: if a parent context skips an image and a child adds another skip, both are excluded.

This is especially useful in context flags. APIM’s --disable-portal turns the portal off and skips its image in the same patch file:

description: "Disable the developer portal UI"
components:
  - name: apim
    helm:
      values:
        portal:
          enabled: false
images:
  preload:
    skip:
      - "{{ .imagePrefix }}/apim-portal-ui:{{ .imageTag }}"

Write the skip entry with the same template as the preload ref it removes, so it still matches when a user overrides imagePrefix or imageTag.

skip is ignored when mode is set to replace, since replace already gives you an explicit list.

Combining mirrors and preloading#

Both strategies work together. Preloading handles your known images (fast, DLC-friendly), while mirrors transparently cache anything else pulled at runtime:

images:
  preload:
    refs:
      - docker.io/library/mongo:7
      - bitnami/redis:7.4
  mirrors:
    upstreams:
      - docker.elastic.co

Skipping preload at runtime#

If a context defines preload images but you want to bypass preloading for a particular run, use --skip-preload:

gck create --skip-preload
gck patch upgrade.yaml --skip-preload

This is useful when mirrors already cover the upstreams you need, or during iterative development where you want a faster cluster startup. If you’re building images locally as part of a dev loop, see the Developer Loop guide.