Version: 2.1.x

Hauler Store Add Image

Overview

hauler store add image pulls a container image from a registry (or the local Docker daemon) and stores it as an OCI artifact in the content store.

This is one of the imperative "collect" commands you run on the internet-connected side of an airgap. Use it to grab images one at a time while exploring or testing - for example, to confirm a reference resolves or to quickly add a single dependency. Once you know the full set of images you need, prefer a declarative Hauler manifest with hauler store sync so the collection is reproducible and version-controlled. After images are in the store, you move them across the airgap with hauler store save / hauler store load and serve or push them with hauler store serve registry or hauler store copy.

By default each image is pulled for all platforms along with its cosign signatures, attestations, SBOMs, and OCI referrers. Use --platform to narrow the architecture and --exclude-extras to fetch only the image itself.

An example with available flags...

hauler store add image <image-reference> --platform <platform> --key <cosign-public-key>

Command Overview

Usage:
  hauler store add image [flags]

Examples:
  # fetch image
  hauler store add image busybox

  # fetch image with repository and tag
  hauler store add image library/busybox:stable

  # fetch image with full image reference and specific platform
  hauler store add image ghcr.io/hauler-dev/hauler-debug:v1.2.0 --platform linux/amd64

  # fetch image with full image reference via digest
  hauler store add image gcr.io/distroless/base@sha256:7fa7445dfbebae4f4b7ab0e6ef99276e96075ae42584af6286ba080750d6dfe5

  # fetch image with full image reference, specific platform, and signature verification
  curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub
  hauler store add image rgcrprod.azurecr.us/rancher/rke2-runtime:v1.31.5-rke2r1 --platform linux/amd64 --key carbide-key.pub

  # fetch image and rewrite path
  hauler store add image busybox --rewrite custom-path/busybox:latest

  # add image from local Docker daemon
  hauler store add image my-local-app:latest --local

Flags:
      --ca-file string                                  (Optional) Location of CA Bundle to enable certification verification
      --certificate-github-workflow-repository string   (Optional) Cosign certificate-github-workflow-repository option
      --certificate-identity string                     (Optional) Cosign certificate-identity (either --certificate-identity or --certificate-identity-regexp required for keyless verification)
      --certificate-identity-regexp string              (Optional) Cosign certificate-identity-regexp (either --certificate-identity or --certificate-identity-regexp required for keyless verification)
      --certificate-oidc-issuer string                  (Optional) Cosign option to validate oidc issuer
      --certificate-oidc-issuer-regexp string           (Optional) Cosign option to validate oidc issuer with regex
      --exclude-extras                                  (Optional) Exclude cosign signatures, attestations, SBOMs, and OCI referrers when pulling the image
  -h, --help                                            help for image
      --insecure-skip-tls-verify                        (Optional) Skip TLS certificate verification
  -k, --key string                                      (Optional) Location of public key to use for signature verification
      --local                                           (Optional) Add image from the local Docker daemon instead of a remote registry
  -p, --platform string                                 (Optional) Specify the platform of the image... i.e. linux/amd64 (defaults to all). Not allowed with a digest-pinned multi-platform image
      --rewrite string                                  (Optional) Rewrite artifact path to specified string
      --use-tlog-verify                                 (Optional) Enable transparency log verification for key-based signature verification (keyless/OIDC verification always uses the tlog)

Global Flags:
      --audit-level string     Set the audit logging level (none, standard, verbose) (defaults standard)
      --blob-concurrency int   (Optional) Override the maximum number of concurrent blob writes (0 auto-derives from --concurrency where set, otherwise defaults to 16)
  -d, --haulerdir string       Set the location of the hauler directory (default $HOME/.hauler)
      --ignore-errors          Warn and continue instead of failing on errors, including storing images that failed verification (defaults false)
  -l, --log-level string       Set the logging level (i.e. info, debug, warn) (defaults info)
  -r, --retries int            Set the number of retries for operations (0 uses HAULER_RETRIES, otherwise defaults to 3)
  -s, --store string           Set the directory to use for the content store
  -t, --tempdir string         (Optional) Override the default temporary directory determined by the OS
  -w, --work-dir string        (Optional) Set the directory for output that commands would otherwise write to the current directory (default: current directory)

Hauler Command Line for Images

hauler store add image <image-reference> --platform <platform> --key <cosign-public-key>

Example Commands for Images

# fetch image
hauler store add image busybox

# fetch image with repository and tag
hauler store add image library/busybox:stable

# fetch image with full image reference and specific platform
hauler store add image ghcr.io/hauler-dev/hauler-debug:v1.0.7 --platform linux/amd64

# fetch image with full image reference via digest
hauler store add image gcr.io/distroless/base@sha256:7fa7445dfbebae4f4b7ab0e6ef99276e96075ae42584af6286ba080750d6dfe5

# fetch image with full image reference, specific platform, and signature verification
hauler store add image rgcrprod.azurecr.us/hauler/rke2-manifest.yaml:v1.28.12-rke2r1 --platform linux/amd64 --key carbide-key.pub

# fetch image and rewrite path
hauler store add image busybox --rewrite custom-path/busybox:latest

# fetch image without its associated signatures, attestations, SBOMs, and referrers
hauler store add image busybox --exclude-extras

# add image from the local Docker daemon instead of a remote registry
hauler store add image my-local-app:latest --local

# fetch image from a registry with a private CA
hauler store add image registry.example.com/app:latest --ca-file /path/to/ca.pem

# fetch image from a registry with a self-signed or otherwise unverifiable certificate
hauler store add image registry.example.com/app:latest --insecure-skip-tls-verify

Configuring TLS for Registry Connections

Use --ca-file to trust a private or internal CA when pulling from a registry that presents a certificate not signed by a public CA, or --insecure-skip-tls-verify to skip certificate verification entirely (self-signed certs, testing, etc.). Both flags can also be set via the CA_FILE and INSECURE_SKIP_TLS_VERIFY environment variables, which apply whenever the corresponding flag isn't explicitly passed.

# via flag
hauler store add image registry.example.com/app:latest --ca-file /path/to/ca.pem

# via environment variable
CA_FILE=/path/to/ca.pem hauler store add image registry.example.com/app:latest

Note: --ca-file and --insecure-skip-tls-verify are mutually exclusive - supplying a CA file always forces certificate verification on, regardless of --insecure-skip-tls-verify. When neither is set, the system's default CA bundle is used.

Adding an Image from the Local Docker Daemon

The --local flag adds an image directly from the local Docker daemon instead of pulling it from a remote registry. This is useful for images you have built locally and not yet pushed anywhere.

hauler store add image my-local-app:latest --local

Note: --local cannot be combined with cosign verification flags (--key, --certificate-identity, etc.) or --platform, since the image is read directly from the daemon.

Excluding Extras

By default, adding an image also pulls its associated cosign signatures, attestations, SBOMs, and OCI referrers. Pass --exclude-extras to fetch only the image itself:

hauler store add image busybox --exclude-extras

Hauler Manifest for Images

Used with hauler store sync. CLI flags override per-image fields, which override manifest-level annotations. The following shows all supported per-image fields and annotations:

hauler-image-manifest.yaml
apiVersion: content.hauler.cattle.io/v1
kind: Images
metadata:
  name: hauler-content-images-example
  annotations:
    # global flags for all images in the manifest
    # image flags override global flags
    # example: key set globally, but not observed if set per image
    # example: platform set globally, but not observed if set per image
    # example: registry set globally, but not observed if set per image
    hauler.dev/key: <cosign-public-key>
    hauler.dev/platform: <platform>
    hauler.dev/registry: <registry>
    hauler.dev/use-tlog-verify: "true"
    hauler.dev/exclude-extras: "true"
    hauler.dev/certificate-identity: <cosign-certificate-identity>
    hauler.dev/certificate-identity-regexp: <cosign-certificate-identity-regexp>
    hauler.dev/certificate-oidc-issuer: <cosign-oidc-issuer>
    hauler.dev/certificate-oidc-issuer-regexp: <cosign-oidc-issuer-regexp>
    hauler.dev/certificate-github-workflow-repository: <cosign-github-workflow-repository>
    # TLS options for pulling from the registry (mutually exclusive; ca-file wins if both are set)
    hauler.dev/ca-file: <path-to-ca-bundle>
    hauler.dev/insecure-skip-tls-verify: "true"
spec:
  images:
    - name: <image-reference>
      # path to the cosign public key for signature verification
      key: <cosign-public-key>
      # platform of the image to pull (defaults to all)
      platform: <platform>
      # rewrite the artifact path in the store
      rewrite: <desired-image-reference>
      # exclude cosign signatures, attestations, SBOMs, and OCI referrers
      exclude-extras: false
      # add the image from the local Docker daemon instead of a remote registry
      local: false
      # enable transparency log verification for key-based verification
      use-tlog-verify: false
      # keyless (cosign certificate) verification options
      certificate-identity: <cosign-certificate-identity>
      certificate-identity-regexp: <cosign-certificate-identity-regexp>
      certificate-oidc-issuer: <cosign-oidc-issuer>
      certificate-oidc-issuer-regexp: <cosign-oidc-issuer-regexp>
      certificate-github-workflow-repository: <cosign-github-workflow-repository>
      # TLS options for pulling this image (mutually exclusive; ca-file wins if both are set)
      ca-file: <path-to-ca-bundle>
      insecure-skip-tls-verify: false

Example Manifest for Images

hauler-image-manifest.yaml
apiVersion: content.hauler.cattle.io/v1
kind: Images
metadata:
  name: hauler-content-images-example
  annotations:
    # global flags for all images in the manifest
    # image flags override global flags
    # example: key set globally, but not observed if set per image
    # example: platform set globally, but not observed if set per image
    # example: registry set globally, but not observed if set per image
    hauler.dev/key: <cosign-public-key>
    hauler.dev/platform: <platform>
    hauler.dev/registry: <registry>
spec:
  images:
    # fetch image
    - name: neuvector/scanner
    # fetch image with full image reference
    - name: docker.io/neuvector/updater:latest
    # fetch image with full image reference with digest
    - name: docker.io/neuvector/updater@sha256:0076b356368c9988eec5f3cead771d29a377074b982f22800f4d9c8c3b215a56
    # fetch image with full image reference, specific version, specific platform
    - name: docker.io/longhornio/longhorn-ui:v1.6.0
      platform: linux/amd64
    # fetch image with full image reference, specific version, specific platform, and signature verification
    - name: docker.io/longhornio/longhorn-manager:v1.6.0
      key: cosign-public-key.pub
      platform: linux/amd64

Example Manifest with Rewrite

hauler-image-manifest.yaml
apiVersion: content.hauler.cattle.io/v1
kind: Images
metadata:
  name: hauler-content-images-example
  annotations:
    # global flags for all images in the manifest
    # image flags override global flags
    # example: key set globally, but not observed if set per image
    # example: platform set globally, but not observed if set per image
    # example: registry set globally, but not observed if set per image
    hauler.dev/key: <cosign-public-key>
    hauler.dev/platform: <platform>
    hauler.dev/registry: <registry>
spec:
  images:
    - name: <image-reference>
      rewrite: <desired-image-reference>
      key: <cosign-public-key>
      platform: <platform>

Overview​

Command Overview​

Hauler Command Line for Images​

Example Commands for Images​

Configuring TLS for Registry Connections​

Adding an Image from the Local Docker Daemon​

Excluding Extras​

Hauler Manifest for Images​

Example Manifest for Images​

Example Manifest with Rewrite​