Bye-Bye External Registries: Going Fully Offline with Quay on OpenShift SNO

Introduction (a.k.a. “Why We’re Here”)

This guide is inspired by the wonderful work of Shon Paz in his article “Dealing with Air-Gapped Environments Just Got Much Easier”.

[embed]Dealing With Air-Gapped Environments Just Got Much Easier Dealing with air-gapped environments can sometimes be challenging and costly in terms of time and effort put in order…shonpaz.medium.com

Let’s face it: OpenShift is fantastic when you’ve got all your ducks — or rather, container images — in a neat little row. In traditional data centers, there’s usually an image registry ready to go, sitting pretty, waiting to serve up your containers like a pro. But what happens when you’re not in Kansas anymore? Welcome to the wild world of edge computing!

Edge scenarios often mean playing by a different set of rules — rules where connectivity is spotty, the closest Starbucks is 100 miles away, and your “data center” might actually just be one lonely node sitting in a dusty room. Enter Single Node OpenShift (SNO): a great solution, but with its own quirks. One biggie? Keeping your container images handy without relying on external registries, because, let’s be honest, the edge doesn’t do “external” very well.

Note: The procedure below is applicable to RHOCP versions 4.16 and below.

The Mission (Should You Choose to Accept It)

Today’s goal: Set up an offline image registry — our friend Quay — right smack dab on your Single Node OpenShift instance, post-installation. Why bother? Simple! With a local registry:

• You can kiss external network dependencies goodbye (and we know you’ve always wanted to).
• You keep your containers happier and closer to home (literally).
• You avoid disabling crio-wipe—because let's admit it, workarounds are never really fun (and they secretly scare us).

By the end of this little adventure, you’ll be rocking a fully offline Quay registry, integrated seamlessly and securely with your OpenShift SNO. Ready to dive into containerized survival at the edge? Let’s roll!

Part 1: Preparing the Battlefield (a.k.a. Setting Up Prerequisites)

Prerequisites

• A Bastion server based on RHEL9, already connected to the network.
• Access to your freshly installed Single Node OpenShift (SNO).

Preparations

First things first, let’s grab the necessary tools that will help us set up our offline registry:

wget https://mirror.openshift.com/pub/openshift-v4/clients/mirror-registry/latest/mirror-registry.tar.gz
wget https://mirror.openshift.com/pub/openshift-v4/amd64/clients/ocp-dev-preview/pre-release/oc-mirror.tar.gz

Once downloaded, transfer both tar.gz files to your SNO node.

Installation

Before we begin, switch to the root user to avoid permission headaches:

sudo -i

On your SNO node (yes, we’re doing all of this directly on the SNO itself!), start by extracting the goodies:

tar xvf oc-mirror.tar.gz -C /usr/local/bin/
chmod +x /usr/local/bin/oc-mirror
tar xvf mirror-registry.tar.gz

You’ll find the following extracted:

• image-archive.tar
• execution-environment.tar
• mirror-registry

Next, create a directory to organize your artifacts:

mkdir disconnected-mirror && cd disconnected-mirror

Now, copy the important files into the new directory:

cp ../image-archive.tar .
cp ../execution-environment.tar .
cp ../mirror-registry .

Time to fire up our Quay instance using the mirror-registry CLI:

./mirror-registry install --quayHostname quay.yb.local --initUser admin --initPassword password

The installer will do a quick “sanity check” and, assuming the planets are aligned, you should see:

INFO[2022–03–31 18:57:28] Quay installed successfully, permanent data is stored in /etc/quay-install
INFO[2022–03–31 18:57:28] Quay is available at https://quay.yb.local:8443 with credentials (admin, password)

Boom! 🎉 Our Quay instance is officially alive!

Let’s double-check everything:

podman pod ps

You should see something like this:

POD ID        NAME        STATUS    CREATED              INFRA ID      # OF CONTAINERS
7cd58c3158af  quay-pod    Running   39 seconds ago       4abd27e126dd  4

Now, try accessing https://quay.yb.local:8443 in your browser to confirm that Quay is up and running.

Trusting Our Brand-New Quay

Since we’re using a self-signed certificate, we need to tell our SNO to trust it. Update the trusted CA sources so oc-mirror can securely push images:

cp /etc/quay-install/quay-rootCA/rootCA.pem /etc/pki/ca-trust/source/anchors/
update-ca-trust extract

Finally, let’s verify we can log in to our freshly baked registry:

podman login quay.yb.local:8443

Credentials:

• Username: admin
• Password: password

If login succeeds, congrats! You’re officially running your own offline registry right inside your SNO!

Part 2: SNO’s Next Evolution — Trusting Its Own Quay Like a Container Jedi

Prerequisites

• You have access to the OpenShift cluster as a user with the cluster-admin role.

Making It Happen (Without Breaking Anything)

Attention Padawan: Execute these commands on the Bastion server. The SNO must remain calm and undisturbed.

First, download the current pull secret from your cluster:

oc get secret/pull-secret -n openshift-config --template='{{index .data ".dockerconfigjson" | base64decode}}' > <pull_secret_location>

Make a backup, because safety first!

cp <pull_secret_location> <pull_secret_location>.bak

Now, add the credentials for your new shiny offline Quay registry to the pull secret:

oc registry login --registry="quay.yb.local:8443" \
  --auth-basic="admin:password" \
  --to=<pull_secret_location>

Once updated, set the new global pull secret:

oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=<pull_secret_location>

At this point, your cluster knows about your offline Quay and trusts it.

Repeating the Push (Because Practice Makes Perfect)

Now that your cluster trusts your offline Quay like an old friend, it’s time to re-run the image mirroring process — but this time, for real. You’ll need to mirror all required OpenShift release images again, targeting your new offline Quay registry.

Additionally, all future mirroring operations — such as Operators, optional components, or updates — must also target your new offline Quay registry to keep everything fully self-contained.

This ensures your SNO has everything it needs locally to pull from — no external lookups, no broken deployments.

No external registries, no nasty surprises, just pure, glorious independence.

Conclusion: SNO, Unchained and Unstoppable

Congratulations, brave cluster adventurer! 🎉

You’ve just turned your Single Node OpenShift (SNO) into a fully independent, offline-capable, registry-savvy machine. By setting up your own Quay instance directly on the SNO and teaching your cluster to trust and use it, you’ve eliminated one of the biggest hurdles of edge computing — reliance on external registries.

No more internet dependency.

No more “Oops, can’t pull the image” drama.

No more workarounds like disabling crio-wipe and crossing fingers.

Instead, you’ve built a system that can operate where others tap out: in remote sites, edge locations, or anywhere bandwidth is a luxury. 🚀

This approach not only makes your SNO smarter and more reliable, but it also gives you full control over your container lifecycle — the way OpenShift was meant to be used in disconnected environments.

And the best part?

You’ve achieved all of this without compromising stability — just pure, clean, edge computing glory.

Until next time: Keep building, keep breaking barriers, and may your containers always pull successfully!

Special thanks to Shoval Ben David for the provided materials and assistance !