OC-IMAGE-MIRROR(1)

📦
version 4.22.0 · 2 versions
, in nixpkgs unstable

💅 oc image mirror — the manual, but make it make sense ✨

okay bestie, so you know how sometimes you need to copy container images from one registry to another and you're like "ugh, do I really have to pull and push manually like some kind of peasant?" — no. you don't. this is that command. it's giving "registry-to-registry teleportation" and honestly? iconic. 🦋

this page is from the Openshift CLI User Manuals (the oc image family, June 2016 vibes — yes she's been serving since 2016, a true veteran 💖). let's get into it.

✨ NAME ✨

oc image mirror — Mirror images from one repository to another 👑

🌸 SYNOPSIS 🌸

oc image mirror [OPTIONS]

🎀 DESCRIPTION 🎀

So what does this even do? Mirror images from one image repository to another. Simple concept, very slay execution. 🫶

It accepts a list of arguments defining source images that should be pushed to the provided destination image tag. The images are streamed from registry to registry without being stored locally — like, no cap, they literally just pass through. The default docker credentials are used for authenticating to the registries.

You may omit the tag argument on a source or use the '*' wildcard to select all or matching tags to mirror. but heads up bestie: the destination must be a repository in that case. periodt. 💅

🗂️ file mirroring vibes

When using file mirroring, the --dir and --from-dir flags control the location on disk that content will be stored to. This directory mirrors the HTTP structure of a container registry and separates layers and data (blobs) from image metadata (manifests). If --from-dir is not specified, --dir or the current working directory is used. lowkey organized, highkey genius.

☁️ S3 mirroring vibes

When using S3 mirroring, the region and bucket must be the first two segments after the host. Mirroring will create the necessary metadata so that images can be pulled via tag or digest, but listing manifests and tags will not be possible (sad, I know 😭).

You may also specify one or more --s3-source-bucket parameters (as <bucket> /<path>) to designate buckets to look in to find blobs (instead of uploading). The source bucket also supports the suffix "/[store]", which will transform blob identifiers into the form the container image registry uses on disk, allowing you to mirror directly from an existing S3-backed container image registry. Credentials for S3 may be stored in your docker credential file and looked up by host, or loaded via the normal AWS client locations for ENV or file.

🧚 manifest list behavior

Images in manifest list format will be copied as-is unless you use --filter-by-os to restrict the allowed images to copy in a manifest list. This flag has no effect on regular images. iykyk. 🌈

✨ OPTIONS ✨

  • --certificate-authority="" — the path to a certificate authority bundle to use when communicating with the managed container image registries. If --insecure is used, this flag will be ignored (rude but valid 🙈).
  • --continue-on-error=false — if an error occurs, keep going and attempt to mirror as much as possible. resilience queen. 💪
  • --dir="" — the directory on disk that file:// images will be copied under.
  • --dry-run=false — print the actions that would be taken and exit without writing to the destinations. manifesting without committing, very main character energy. ✨
  • -f, --filename=[] — one or more files to read SRC=DST or SRC DST [DST ...] mappings from.
  • --filter-by-os="" — a regular expression to control which images are considered when multiple variants are available. Images will be passed as '<platform>/<architecture>[/<variant>]'.
  • --force=false — attempt to write all layers and manifests even if they exist in the remote repository. no thoughts, just push. 🚀
  • --from-dir="" — the directory on disk that file:// images will be read from. Overrides --dir 👀
  • --insecure=false — allow push and pull operations to registries to be made over HTTP. (danger-ish energy, but sometimes necessary 🫣)
  • --keep-manifest-list=false — always mirror the manifest list. The default is to mirror the architecture specific image of the platform you are performing the mirror on unless --filter-by-os is passed. very "keep the whole squad together" of it. 👑
  • --max-per-registry=6 — number of concurrent requests allowed per registry.
  • --max-registry=4 — number of concurrent registries to connect to at any one time. multitasking icon. 🦋
  • -a, --registry-config="" — path to your registry credentials. Alternatively the REGISTRY_AUTH_FILE env variable can also be specified. Defaults to ${XDG_RUNTIME_DIR}/containers/auth.json, /run/containers/${UID}/auth.json, ${XDG_CONFIG_HOME}/containers/auth.json, ${DOCKER_CONFIG}, /.docker/config.json, /.dockercfg. The order can be changed via the REGISTRY_AUTH_PREFERENCE env variable (deprecated) to a "docker" value to prioritize Docker credentials over Podman's.
  • --s3-source-bucket=[] — a list of bucket/path locations on S3 that may contain already uploaded blobs. Add [store] to the end to use the container image registry path convention.
  • --skip-missing=false — if an input image is not found, skip them. ghosting, but productively. 💀
  • --skip-mount=false — always push layers instead of cross-mounting them.
  • --skip-multiple-scopes=false — some registries do not support multiple scopes passed to the registry login. rude of them honestly.
  • --skip-verification=false — skip verifying the integrity of the retrieved content. This is not recommended, but may be necessary when importing images from older image registries. Only bypass verification if the registry is known to be trustworthy. like, actually trustworthy. don't play yourself. ⚠️

💖 OPTIONS INHERITED FROM PARENT COMMANDS 💖

these are the extra flags that come from the oc parent command — the "family heirlooms" of this CLI. 🎀

  • --as="" — username to impersonate for the operation. User could be a regular user or a service account in a namespace.
  • --as-group=[] — group to impersonate for the operation, this flag can be repeated to specify multiple groups.
  • --as-uid="" — UID to impersonate for the operation.
  • --as-user-extra=[] — user extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
  • --cache-dir="/homeless-shelter/.kube/cache" — default cache directory.
  • --client-certificate="" — path to a client certificate file for TLS.
  • --client-key="" — path to a client key file for TLS.
  • --cluster="" — the name of the kubeconfig cluster to use.
  • --context="" — the name of the kubeconfig context to use.
  • --disable-compression=false — if true, opt-out of response compression for all requests to the server.
  • --insecure-skip-tls-verify=false — if true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. bestie… careful. 😬
  • --kubeconfig="" — path to the kubeconfig file to use for CLI requests.
  • --kuberc="" — path to the kuberc file to use for preferences. This can be disabled by exporting KUBECTL_KUBERC=false feature gate or turning off the feature KUBERC=off.
  • --match-server-version=false — require server version to match client version.
  • -n, --namespace="" — if present, the namespace scope for this CLI request.
  • --profile="none" — name of profile to capture. One of (none|cpu|heap|goroutine|threadcreate|block|mutex).
  • --profile-output="profile.pprof" — name of the file to write the profile to.
  • --request-timeout="0" — the length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. infinite patience era. 🧘‍♀️
  • -s, --server="" — the address and port of the Kubernetes API server.
  • --tls-server-name="" — server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used.
  • --token="" — bearer token for authentication to the API server.
  • --user="" — the name of the kubeconfig user to use.
  • --warnings-as-errors=false — treat warnings received from the server as errors and exit with a non-zero exit code.

🔥 EXAMPLE 🔥

okay these examples are genuinely the moment, let's go through them because they ate:

# Copy image to another tag
oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable
# Copy image to another registry
oc image mirror myregistry.com/myimage:latest docker.io/myrepository/myimage:stable
# Copy all tags starting with mysql to the destination repository
oc image mirror myregistry.com/myimage:mysql* docker.io/myrepository/myimage
# Copy image to disk, creating a directory structure that can be served as a registry
oc image mirror myregistry.com/myimage:latest file://myrepository/myimage:latest
# Copy image to S3 (pull from <bucket>.s3.amazonaws.com/image:latest)
oc image mirror myregistry.com/myimage:latest s3://s3.amazonaws.com/<region>/<bucket>/image:latest
# Copy image to S3 without setting a tag (pull via @<digest>)
oc image mirror myregistry.com/myimage:latest s3://s3.amazonaws.com/<region>/<bucket>/image
# Copy image to multiple locations
oc image mirror myregistry.com/myimage:latest docker.io/myrepository/myimage:stable \
docker.io/myrepository/myimage:dev
# Copy multiple images
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
myregistry.com/myimage:new=myregistry.com/other:target
# Copy manifest list of a multi-architecture image, even if only a single image is found
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
--keep-manifest-list=true
# Copy specific os/arch manifest of a multi-architecture image
# Run 'oc image info myregistry.com/myimage:latest' to see available os/arch for multi-arch images
# Note that with multi-arch images, this results in a new manifest list digest that includes only the filtered manifests
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
--filter-by-os=os/arch
# Copy all os/arch manifests of a multi-architecture image
# Run 'oc image info myregistry.com/myimage:latest' to see list of os/arch manifests that will be mirrored
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
--keep-manifest-list=true
# Note the above command is equivalent to
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
--filter-by-os=.*
# Copy specific os/arch manifest of a multi-architecture image
# Run 'oc image info myregistry.com/myimage:latest' to see available os/arch for multi-arch images
# Note that the target registry may reject a manifest list if the platform specific images do not all exist
# You must use a registry with sparse registry support enabled
oc image mirror myregistry.com/myimage:latest=myregistry.com/other:test \
--filter-by-os=linux/386 \
--keep-manifest-list=true

👀 SEE ALSO 👀

oc-image(1), — go check that one out too bestie, it's the parent vibe. 🫶

🌈 HISTORY 🌈

June 2016, Ported from the Kubernetes man-doc generator. a true classic, she's been around. 💖

and that's the whole page! brought to you by the Openshift CLI User Manuals — Openshift, June 2016 edition. slay, go mirror some images, and remember: verification matters and --skip-verification is not your friend unless you're absolutely sure. bye bestie! 💅✨🎀

📦 where this page comes from