Install without internet access

When your cluster can't reach registry.rigfab.com, carry the products in as a signed bundle. You download it on a connected machine, push it into a registry inside your site, and point the cluster at that registry.

Every chart and image keeps its digest and RigFabTech's signature, so you can check them inside the site with the public key alone.

Before you begin

• rft on a connected machine, and on a machine inside the site that can reach your registry.
• Your site ID and a pull token from RigFabTech.
• A registry inside the site that holds OCI artifacts and Helm charts. See Registry support.
• An account that can push to a path in that registry, such as a Harbor project.
• Optional: RigFabTech's public key from the portal. To check the bundle with a key you got separately from rft, add --key rft-app-signing.pub to rft bundle pull, rft push and rft verify.

Download the bundle

On the connected machine, run:

rft bundle pull chronolog@1.4.2 --username <SITE_ID> --password-stdin < pull-token.txt

It writes rigfab-chronolog-1.4.2.tar, an OCI image layout that holds:

• The product's charts, images, signatures, SBOMs and provenance.
• Its signed release.json.
• The public key and the release notes.

The bundle also holds:

• The releases the product requires, at the newest version that fits.
• The newest stable base chart that serves every product's platform level.

Options:

• Leave out the version to get the newest stable release.
• Name several products to get one bundle that stores their shared layers once. Add --output <file>.
• --platform linux/amd64 leaves out the other platforms of multi-platform images. Harbor and Distribution refuse such an image when you push it. Use it only with a registry that takes it.

Carry it in

Note the bundle's SHA-256 on the connected machine:

sha256sum rigfab-chronolog-1.4.2.tar

Copy the file into the site, run sha256sum there, and compare the two.

Push it into your registry

Inside the site, run:

rft push rigfab-chronolog-1.4.2.tar --registry harbor.example.com/rigfab --username <USER> --password-stdin < password.txt

rft push first verifies the bundle, as rft bundle verify does:

1. RigFabTech's signature on each release.json.
2. Every chart, image and referrer it lists.
3. Every blob's digest.

It then copies each one to harbor.example.com/rigfab/rft/apps/<product>/..., byte for byte, with the same tags.

• Without --username, rft uses a login that docker login saved in ~/.docker/config.json. It doesn't run credential helpers. With Docker Desktop or a credsStore, pass --username and --password-stdin.
• Your own CA: when your registry's certificate comes from your own CA, add --ca-file <ca.pem>.
• Referrers: signatures, SBOMs and provenance go through the registry's referrers API when it has one. When it doesn't, they go under sha256-<digest> tags (the referrers tag schema). --referrers tag forces the tags.

Check the signatures in your registry

rft verify rigfab-chronolog-1.4.2.tar --registry harbor.example.com/rigfab

It checks that your registry holds every chart, image, signature, SBOM and provenance the signed release.json names, under the right tag. It also checks that RigFabTech's signature on each one verifies there. On a gap, it exits non-zero and lists every gap.

cosign gives the same answer:

cosign verify --key rft-app-signing.pub --insecure-ignore-tlog=true harbor.example.com/rigfab/rft/apps/chronolog/chronolog@sha256:<DIGEST>

RigFabTech signs with a key it keeps in AWS KMS and writes nothing to a public transparency log. That's why the command needs --insecure-ignore-tlog=true.

Install from your registry

Follow Install, with these changes.

In Check the cluster, check the cluster against your registry:

rft check --registry harbor.example.com/rigfab

In place of Sign in to the registry, sign Helm in to your registry and write the pull Secret with your registry's account:

rft login --registry harbor.example.com/rigfab --username <USER> --password-stdin --pull-secret rft-system/rigfab-pull --pull-secret rft-app-<PRODUCT>/rigfab-pull < password.txt

Then pick how the nodes pull the images:

• In site.yaml. Set global.imageRegistry to your registry. It replaces registry.rigfab.com in every image the charts name. rft config --registry harbor.example.com/rigfab --format values prints the lines to add.

• RKE2 or k3s mirror. The nodes pull registry.rigfab.com/... from your registry instead, with no values to change:

  rft config --registry harbor.example.com/rigfab --format registries.yaml > registries.yaml

  When your registry needs a login, add it under configs.<your registry>.auth (username, password). The nodes pull with it, since pods name registry.rigfab.com. Merge the file into /etc/rancher/rke2/registries.yaml (/etc/rancher/k3s/registries.yaml on k3s) on every node, and restart RKE2 or k3s. See RKE2's private registry configuration.

The databases run CloudNativePG's PostgreSQL image, which RigFabTech doesn't publish. Mirror it too, and set global.rigfab.database.imageName in site.yaml to your copy, by digest. With both settings, site.yaml holds everything the mirror needs:

global:
  imageRegistry: harbor.example.com/rigfab
  rigfab:
    database:
      imageName: harbor.example.com/mirror/cloudnative-pg/postgresql@sha256:<DIGEST>

Leave out imageRegistry with the RKE2 or k3s mirror.

In place of the base chart dry-run in Write your site's values and the commands in Install the charts, dry-run and install from your registry. rft bundle inspect lists the versions in the bundle.

rft check --registry harbor.example.com/rigfab --chart oci://harbor.example.com/rigfab/rft/apps/rft-base/charts/rft-base --version <VERSION> --values site.yaml

helm install rft-base oci://harbor.example.com/rigfab/rft/apps/rft-base/charts/rft-base --version <VERSION> --namespace rft-system -f site.yaml --wait --timeout 15m

helm install <PRODUCT> oci://harbor.example.com/rigfab/rft/apps/<PRODUCT>/charts/<PRODUCT> --version <VERSION> --namespace rft-app-<PRODUCT> -f site.yaml -f <PRODUCT>.yaml --wait --timeout 15m

Upgrade the same way, with helm upgrade and the same values files.

A registry with a certificate from your own CA

Give each tool the CA certificate, ca.pem:

• rft login, rft check, rft push and rft verify: add --ca-file ca.pem.

• Helm: add --ca-file ca.pem to every helm install and helm upgrade, or add the CA to the trust store of the machine you run Helm on.

• The nodes: add the CA to each node's trust store. Or, with the RKE2 or k3s mirror, copy it to each node and give its path there to rft config:

  rft config --registry harbor.example.com/rigfab --format registries.yaml --ca-file /etc/rancher/rke2/mirror-ca.pem > registries.yaml

Updates

Pull each new release the same way. To carry less, leave out the layers that a release you already pushed shipped:

rft bundle pull chronolog@1.5.0 --since 1.4.2 --username <SITE_ID> --password-stdin < pull-token.txt

rft push then checks that your registry still holds those layers before it pushes anything else.

Before a base chart upgrade, check it against your registry, then follow the order in Upgrade:

rft check --registry harbor.example.com/rigfab --base <VERSION>

Registry support

Tested every night with make airgap-test (zot and Distribution), and against a throwaway Harbor with the same script:

Not tested yet, from their vendors' documentation:

On Harbor, keep --referrers auto. With tag, Harbor keeps the signatures but also lists each sha256-<digest> index as an artifact of its own.

Without rft

The bundle is a plain OCI image layout in a tar file, so oras and regctl can read it too:

mkdir bundle && tar -xf rigfab-chronolog-1.4.2.tar -C bundle
oras cp -r --from-oci-layout bundle@sha256:<DIGEST> harbor.example.com/rigfab/rft/apps/chronolog/chronolog:1.4.2

bundle/rigfab/<product>-<version>/release.json lists every digest. rft bundle inspect prints them.

RFT-E-AIRGAP-BUNDLE

The bundle didn't verify. A release.json isn't signed with RigFabTech's key, or something it lists is missing, unsigned or changed.

Download the bundle again and compare its SHA-256 on both sides. Pass --key only with the public key from the portal.

RFT-E-AIRGAP-PULL

rft bundle pull couldn't sign in, find a release, or copy what the release names, and wrote no bundle.

Check:

• The site ID and pull token.
• That your licence covers the product and version.
• That the machine reaches registry.rigfab.com over HTTPS.

RFT-E-AIRGAP-MIRROR

Your registry refused a push, or doesn't hold everything the bundle signs.

• The registry refused a push: give the account rights to create repositories and tags under the path, and run rft push again.
• rft verify --registry reports missing signatures or SBOMs: run rft push again with --referrers tag.

Next steps

• Install your licence.
• Upgrade when new releases come out.