Installing the HM operator on air-gapped OpenShift v1.4.1 (LTS)

Related installation phase: Phase 4: Preparing the environment

On OpenShift, the Hybrid Manager (HM) operator (edb-hcp-operator) is managed through the Operator Lifecycle Manager (OLM) / OperatorHub. On a connected cluster you install it directly from OperatorHub, from the Red Hat certified-operators catalog — nothing custom is required.

This page covers disconnected or air-gapped (restricted-egress) OpenShift, where the public certified catalog isn't reachable and the operator must be served from a registry you host. There are two supported approaches, described below. A Helm-based install is also a valid path on OpenShift — see Install the EDB Postgres AI Operator.

Choosing an approach

Both approaches install the operator via OLM, so it appears in the OpenShift console and its lifecycle (install, upgrade) is OperatorHub-managed.

Prerequisites

• A working OpenShift 4.18+ cluster you can oc against, with cluster-admin.
• A container registry your cluster can pull from (referred to below as <your-registry>).
• oc and, depending on the approach, the oc-mirror plugin v2 (approach A) or the opm CLI plus a container build tool (approach B).
• The HM platform images (the data-plane container images the operator deploys) synced into <your-registry>. These aren't part of any operator catalog; sync them as described in Syncing images to a local private registry.
• cert-manager (required) — install the Red Hat cert-manager Operator with the All namespaces install mode, from the catalog, before installing the HM operator (see the note below).

Approach A — Mirror the Red Hat certified catalog with oc-mirror

EDB publishes edb-hcp-operator to the Red Hat certified-operators catalog, so a disconnected cluster mirrors it with the same oc mirror v2 workflow it already uses for OpenShift and other operators.

1. Add the operator to your ImageSetConfiguration

Add edb-hcp-operator — plus the HM operator dependencies you need — to your ImageSetConfiguration. The catalog tag matches your cluster's OpenShift minor version (v4.22 is the example used throughout this page). Confirm each operator's channel for your OpenShift version in OperatorHub, as channels vary:

mirror:
  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.22
    packages:
    - name: openshift-cert-manager-operator   # required — install AllNamespaces before the HM operator
      channels:
      - name: stable-v1
    - name: nfd                               # AI scenario only
      channels:
      - name: stable
  - catalog: registry.redhat.io/redhat/certified-operator-index:v4.22
    packages:
    - name: edb-hcp-operator
      channels:
      - name: stable
    - name: gpu-operator-certified            # AI scenario only
      channels:
      - name: v26.3

With only a channel specified, oc mirror mirrors the current head of that channel; to pin or bound versions, add minVersion/maxVersion. Omit nfd and gpu-operator-certified unless you're enabling the AI scenario (see Operators HM installs during deployment).

2. Disable signature mirroring for the partner registry

oc-mirror v2 mirrors cosign signatures by default, but Red Hat doesn't publish signatures for certified/partner content on registry.connect.redhat.com (where the operator bundle lives). Mirroring therefore fails on a missing signature unless you disable signature mirroring for that registry only — a supported, documented setting. Create the following file in /etc/containers/registries.d/ on the host running oc mirror:

# /etc/containers/registries.d/registry.connect.redhat.com.yaml
docker:
  registry.connect.redhat.com:
    use-sigstore-attachments: false

Signature mirroring stays enabled for registry.redhat.io and the OpenShift release payload.

3. Run oc mirror and apply the generated resources

Run oc mirror as usual. Alongside the mirrored images it generates cluster resources under working-dir/cluster-resources/ — a CatalogSource and one or more ImageDigestMirrorSet objects. Apply them:

oc apply -f working-dir/cluster-resources/

Confirm the operator appears in the catalog:

oc get packagemanifest edb-hcp-operator -n openshift-marketplace

4. Install the operator

Create an OperatorGroup and Subscription (or install from the OpenShift console) — see Install the operator below. oc mirror generates the CatalogSource (typically named cs-certified-operator-index-...), so use that name as the Subscription source.

Approach B — Build your own catalog from the EDB bundle

Use this when you can't or won't consume Red Hat catalogs. EDB publishes one bundle image per certified operator release, which you assemble into an FBC catalog hosted in your own registry.

1. Get the bundle (and platform) images into your registry

Syncing images to a local private registry copies the operator bundle image, the operator manager image, the operator Helm chart, and the HM platform images for a given HM version into <your-registry> in one step, preserving digests. That's the simplest way to get everything the install needs.

To mirror a specific bundle version manually instead — for example an older release you want to keep in the catalog's upgrade graph — copy it with skopeo (authenticating to docker.enterprisedb.com with your EDB Repos 2.0 token, username pgai-platform), preserving digests:

skopeo copy --all --preserve-digests \
  docker://docker.enterprisedb.com/pgai-platform/edb-hcp-operator/bundle:v2.0.0 \
  docker://<your-registry>/edb-hcp-operator/bundle:v2.0.0

The bundle's ClusterServiceVersion (CSV) references the operator manager and platform images by digest at docker.enterprisedb.com/pgai-platform/...; those must also be present in <your-registry> (which the Syncing images step ensures).

2. Assemble an FBC catalog

mkdir -p /tmp/edb-catalog/edb-hcp-operator
cd /tmp/edb-catalog

cat > edb-hcp-operator/index.yaml <<'EOF'
---
schema: olm.package
name: edb-hcp-operator
defaultChannel: stable
---
schema: olm.channel
package: edb-hcp-operator
name: stable
entries:
  - name: edb-hcp-operator.v2.0.0
EOF

opm render <your-registry>/edb-hcp-operator/bundle:v2.0.0 -o yaml >> edb-hcp-operator/index.yaml
opm validate edb-hcp-operator/

The entries list is the channel's upgrade graph; with a single version it's just the channel head (see Upgrading).

3. Build and push the catalog image

Generate the Dockerfile, then build and push the catalog image. With docker buildx (multi-arch):

opm generate dockerfile edb-hcp-operator

docker buildx build --platform linux/amd64,linux/arm64 \
  -f edb-hcp-operator.Dockerfile \
  -t <your-registry>/edb-hcp-operator/catalog:latest \
  . --push

Or with podman (single-arch shown; for multi-arch build per-arch and combine with podman manifest, or use docker buildx):

opm generate dockerfile edb-hcp-operator

podman build -f edb-hcp-operator.Dockerfile \
  -t <your-registry>/edb-hcp-operator/catalog:latest .
podman push <your-registry>/edb-hcp-operator/catalog:latest

4. Redirect the EDB image references

Because the bundle's CSV references images at docker.enterprisedb.com/pgai-platform/... by digest, redirect those pulls to your registry with an ImageDigestMirrorSet:

apiVersion: config.openshift.io/v1
kind: ImageDigestMirrorSet
metadata:
  name: edb-hcp-operator-mirror
spec:
  imageDigestMirrors:
  - source: docker.enterprisedb.com/pgai-platform
    mirrors:
    - <your-registry>

Apply a CatalogSource pointing at your catalog image:

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: edb-hcp-operator
  namespace: openshift-marketplace
spec:
  sourceType: grpc
  image: <your-registry>/edb-hcp-operator/catalog:latest
  displayName: HM Operator
  publisher: EnterpriseDB
  updateStrategy:
    registryPoll:
      interval: 10m

Install the operator

Give the cluster pull access to <your-registry> (merge its credentials into the global pull secret), then create an OperatorGroup and Subscription:

oc get secret/pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > /tmp/pull-secret.json
oc registry login --registry="<your-registry>" --auth-basic="<user>:<password>" --to=/tmp/pull-secret.json
oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=/tmp/pull-secret.json

Set the Subscription source to the name of your CatalogSource: edb-hcp-operator if you created it in approach B, or the oc mirror–generated name (for example cs-certified-operator-index-v4-22, matching your OpenShift version) in approach A.

apiVersion: project.openshift.io/v1
kind: Project
metadata:
  name: edb-hcp-operator-system
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: edb-hcp-operator-group
  namespace: edb-hcp-operator-system
spec: {}
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: edb-hcp-operator
  namespace: edb-hcp-operator-system
spec:
  channel: stable
  installPlanApproval: Automatic
  name: edb-hcp-operator
  source: edb-hcp-operator            # your CatalogSource name (see above)
  sourceNamespace: openshift-marketplace

Watch the install and confirm the CSV reaches Succeeded:

oc get csv -n edb-hcp-operator-system -w

Operators HM installs during deployment

If you enable the AI scenario (GPU/AI workloads), HM — once running — installs two more OpenShift operators through OperatorHub, with automatic approval:

• Node Feature Discovery (nfd) — from the redhat-operators catalog (namespace openshift-nfd).
• NVIDIA GPU Operator (gpu-operator-certified) — from the certified-operators catalog (namespace nvidia-gpu-operator).

On disconnected/air-gapped OpenShift these must already be mirrored into your environment (the same way as the HM operator), or the HM deployment hangs waiting for them to install. Mirroring is sufficient — HM approves the installs automatically — but pre-installing them from the catalog beforehand is a good reliability step that avoids having to triage a stuck deployment. They come from the Red Hat catalogs regardless of how you installed the HM operator: approach B only changes where the EDB operator comes from, not nfd/gpu-operator-certified.

Upgrading

Approach A. Re-run oc mirror: it mirrors the current head of the stable channel, so a newly published release is picked up automatically, then re-apply the generated resources. To control exactly which versions are mirrored, set minVersion/maxVersion on the package or channel in your ImageSetConfiguration. OLM upgrades along the certified catalog's upgrade graph — the same workflow you run for every other operator.

Approach B. Add the new release to your catalog. For example, to move from 2.0.0 to a future 2.1.0:

1. Get the new bundle (and its images) into <your-registry> — re-run Syncing images for the new HM version, or skopeo copy the specific bundle.

2. Add it to the channel with a replaces: edge to the previous version and append its rendered bundle:

   → WrapCopy

   entries:
     - name: edb-hcp-operator.v2.0.0
     - name: edb-hcp-operator.v2.1.0
       replaces: edb-hcp-operator.v2.0.0

   → WrapCopy

   opm render <your-registry>/edb-hcp-operator/bundle:v2.1.0 -o yaml >> edb-hcp-operator/index.yaml
   opm validate edb-hcp-operator/

3. Rebuild and push the catalog image (step 3 above), then re-apply. Within the CatalogSource poll interval OLM detects the new version and (with installPlanApproval: Automatic) applies the upgrade.

Troubleshooting

• CatalogSource pod stuck CONNECTING — The catalog image isn't being pulled. Verify the global pull secret includes credentials for <your-registry>.
• Operator or platform pod ImagePullBackOff — The bundle references images at docker.enterprisedb.com/pgai-platform/...; confirm the ImageDigestMirrorSet redirects that source to <your-registry> and that the images (including the platform images and, for HM version changes, the bootstrap image) are actually mirrored there.
• OLM tries to install a second cert-manager — The existing cert-manager is namespace-scoped. Reinstall it with the All namespaces install mode (see the prerequisite note above).
• oc mirror fails on registry.connect.redhat.com signatures (approach A) — Apply the use-sigstore-attachments: false registries.d file from step 2.