Private Registry (BYO ACR)
By default, StratoLens pulls its self-update images straight from the StratoLens vendor registry. Private Registry Sourcing changes that: every update image lands in your Azure Container Registry (ACR) first, so you can scan it, gate egress, or apply supply-chain policy before it is ever installed. Configuration lives on Settings > General; the per-version import controls live on Settings > Updates (the System Updates page).
On This Page
Azure Container Registry only, self-updates only
- Only Azure Container Registry is supported. Other registry types are not.
- The initial StratoLens installation always bootstraps from the vendor registry. Only self-updates honor your private registry.
How It Works
Three ideas shape everything on this page:
- Import ≠ install
- Copying a version into your registry (import) and deploying it to your running instance (install) are separate actions. Nothing is deployed as a side effect of importing.
- Installs fail closed
- With the feature on, a version that isn't actually present in your registry is refused before anything changes. There is no silent fallback to the vendor registry.
- Managed or Manual
- Managed mode has StratoLens import images for you (needs write access to the registry). Manual mode keeps StratoLens read-only and you copy images in yourself.
No fallback while enabled
While Private Registry Sourcing is enabled there is no fallback to the vendor registry. A version must be present in your registry before it can be installed, or the update is refused.
Prerequisites
You need an administrator role with StratoLens's update-management permission, the same one that gates the System Updates page. Without it, the Private Registry card is hidden and the version-import controls don't appear. You also need a registered StratoLens installation, which the update system requires generally.
On the Azure side, grant the StratoLens managed identity RBAC on your ACR. The Setup Instructions modal generates the exact commands for whichever mode you pick:
- Managed mode
- AcrPull plus registry read plus the importImage action (via Contributor, or a minimal custom role).
- Manual mode
- AcrPull plus registry read only (via Reader, or a read-only custom role). No write access anywhere.
AcrPull alone is not enough
Registry read (registries/read) is required by the Registry reachable check and is not included in AcrPull. That is why the grant is always AcrPull plus a read-capable role, never AcrPull alone. Grant AcrPull by itself and validation still fails on the first check.
Configure the Registry
All configuration is on Settings > General, in the collapsible Private Registry card. Its header shows an Enabled or Disabled badge. Setup is a strict sequence: enter the registry details, grant access, then run Validate & Sync, which turns the feature on for you when it passes.
- Open Settings > General and expand the Private Registry card.
- Enter your Registry resource ID, the full Azure resource ID of your ACR. Find it in the Azure portal under your registry's JSON View (top-right of the Overview page), or with
az acr show -n <registry-name> --query id -o tsv. - Set the Target repository, the path inside your registry where images are imported. The default is
stratolens; you don't need to pre-create it, as it's created on first import. - Choose an Import mode: Managed — StratoLens imports images for you or Manual — you copy images yourself.
With the registry details entered, the last two steps each have their own section below: Grant Access (open Setup Instructions and run the generated az commands), then Validate & Sync (which enables the feature on success).
Defaults on a fresh install
- Feature
- Disabled
- Import mode
- Managed
- Target repository
stratolens- Auto-import
- Off, at the Release (stable) threshold
Changing the target resets the feature
Saving a different Registry resource ID or Target repository clears the validation result and the imported-version badges and turns the feature (and auto-import) off. Changing the Import mode also resets validation and disables the feature, but keeps your imported versions, since the registry contents didn't change. Either way you must re-run Validate & Sync and re-enable against the new target. A warning is shown before each of these saves.
While validated but off
If validation has passed but the feature is off, a persistent notice states that self-updates will use the public StratoLens registry. Your validated registry and imported images are untouched, and you can turn it back on any time.
Grant Access
The Setup Instructions button opens a modal titled Grant StratoLens access to your registry. It shows the StratoLens managed identity's Client ID and Principal ID, each with a Copy button, and provides copy-ready az commands that follow the mode you selected. Each command block has its own Copy button and a one-line description of what it grants.
- Managed mode
- Grants AcrPull and the importImage permission, either via Contributor (option A) or a minimal custom role with just registry read plus the importImage action (option B).
- Manual mode
- Grants AcrPull and registry read only, via Reader (option A) or a read-only minimal custom role (option B). No write access anywhere.
Prefer least privilege
If you want the smallest possible grant, use the custom-role option (B) rather than Contributor or Reader. The modal generates a minimal custom role for both modes.
Validate & Sync
Validate & Sync is the one button that saves any pending edits, runs the validation checks against those saved settings, reconciles the In registry badges, and enables the feature on success. It runs three checks:
- Registry reachable
- Confirms the resource ID is real and StratoLens can see the registry.
- Pull access (AcrPull)
- Confirms StratoLens can pull images from the registry.
- Import permission (importImage)
- Confirms StratoLens can copy vendor images into the registry by importing the most recent eligible version, which stays in your registry and gets an In registry badge. In Manual mode this check is shown as skipped, since importImage isn't required.
A Registry sync line below the checks reports whether the In registry badges were reconciled. It never fails validation.
Estimated time: several minutes in Managed mode
Managed-mode validation is asynchronous: the Import permission check imports a real image to prove the permission, which can take several minutes the first time. The card polls for completion, so leaving the page is safe, as the import finishes in Azure. If you return much later, click Validate & Sync again to record the result (near-instant on re-run). Manual-mode validation is synchronous and completes immediately.
Import & Install Versions
When the feature is enabled, the Available Versions list on Settings > Updates gains private-registry controls. Versions already in your registry carry a green In registry badge. A Sync registry button (top-right of the heading) rebuilds those badges from what's actually in your registry right now.
- Import (Managed)
- Click Import on a version row to copy it into your registry. Only one import runs at a time; all Import buttons disable while any import is in progress.
- Copy import command (Manual)
- Click Copy import command to copy a digest-pinned
az acr importcommand, then run it with your own credentials and click Sync registry. - Update to Selected Version
- Installs the selected version. Disabled when that version isn't in your registry, with a tooltip telling you to import it first (Managed) or copy it in and Sync (Manual).
The In registry badge is advisory
The badge is a cached view; the real authority is a live presence check at install time. A stale badge can never cause a bad install. Worst case, a version you thought was present blocks the update button until you click Sync registry.
Use a digest-preserving copy tool (Manual mode)
az acr import, oras cp, and crane copy preserve the image digest exactly. docker pull + docker push can rewrite the manifest (especially multi-arch) and change the digest. A mismatched digest never gets a badge and fails closed at install. If a version you copied in shows no badge or won't install, re-copy it with a digest-preserving tool, then click Sync registry.
Automatic Imports
In Managed mode you can turn on Automatically import new versions and pick an Import up to threshold (Release (stable), Beta, or Alpha). Newly discovered eligible versions are then copied into your registry on the version-check schedule. Auto-import never installs anything; it only makes versions available for install.
Import automatically, install on your own schedule
Auto-import and auto-update are controlled separately, on separate pages. Auto-import lives on this card; automatic installs are governed by the Automatic Updates card on Settings > Schedules. To have StratoLens stage every new version in your registry (ready for scanning) but never install one on its own, turn Automatically import new versions on here and turn automatic updates off on Settings > Schedules. You then install each version manually when you're ready.
Auto-import needs write access
Auto-import is Managed-mode only, since it inherently needs the importImage permission. In Manual mode the toggle is locked. Auto-update only installs versions already present in your registry, so if auto-update is on but auto-import is off, new versions won't install until you import them. See Automatic Updates.
Everything lands in your activity log
Registry settings changes, validation runs, syncs, and every import (manual, automatic, and validation) are recorded in the Activity Log. Scheduled auto-imports are attributed to a system actor; manual ones to the admin who triggered them.
Troubleshooting
Validation fails on "Registry reachable"
Answer
The resource ID is wrong, or the managed identity lacks registry read (AcrPull alone doesn't include it). Re-run the Setup Instructions grant with Reader or a read-capable custom role, then validate again. The verbatim Azure error is shown on the check.
Validation fails on "Pull access (AcrPull)"
Answer
The AcrPull role isn't assigned, or hasn't propagated yet. Grant it and re-validate.
Validation fails on "Import permission (importImage)"
Answer
The managed identity can't import (Managed mode). Grant Contributor or the custom importImage role, or switch to Manual mode if you won't grant write access.
"Import permission" is stuck spinning
Answer
The proof import can take several minutes. It's safe to leave the page; return and click Validate & Sync again to record the result.
The Enable toggle is greyed out
Answer
Run Validate & Sync successfully first. The toggle mirrors a server-side gate that refuses to enable against an unvalidated registry.
"Update to Selected Version" is disabled
Answer
The selected version isn't in your registry yet. In Managed mode, click Import on its row. In Manual mode, copy the import command, run it, then click Sync registry.