Deploying Ceph in an air-gapped network with cephadm starts with the image supply chain
On an isolated site, the answer is to mirror every container image Ceph needs into a registry you control, then bootstrap and operate the cluster only from that registry. cephadm runs every Ceph daemon as a container, so the local registry, not the public internet, becomes the single source of every image the cluster will ever pull: the Ceph image itself, monitoring images for Prometheus, Grafana and related exporters, and any gateway or dashboard images you enable. If one image is missing or stale in that registry, a host cannot deploy or redeploy the daemon that depends on it, so the mirror is part of the cluster's operating dependencies from day one.
Ceph's source is licensed under LGPL-2.1 or LGPL-3, and the project itself offers no paid edition, so the air-gapped work is not a licensing purchase. It is planning, mirroring and verification. Confirm the exact release you intend to run against the active releases list, and record the image tag and digest you mirror. Also confirm which monitoring images your chosen release expects, since those versions are set by the cephadm release rather than by your team. Decide early whether the registry will be an existing enterprise registry, a dedicated one, or a registry that accepts only pulls from a transfer host, and who is accountable for each import.
Before anything crosses the isolation boundary, check each image's provenance and integrity against the source you pulled it from, and keep a manifest of what was imported and when. This is the same control logic that NERC CIP-013-2 applies to vendor software and patches in its supply chain requirements, and it is a useful model even if you are not a utility. Ask your partner or internal team to define how images are scanned and signed or checksummed before import, and who approves each batch. A written import procedure turns the mirror from a one-time copy into a controlled, repeatable process.
Choosing between an insecure and a TLS-secured local registry
A plain HTTP registry serves images without TLS, so clients do not verify the server identity and the transfer is not encrypted. It is the quicker option for a lab or pilot network, because there is no certificate to issue, renew or distribute. Teams usually mark the registry address as insecure in each host's container runtime, which lets pulls proceed without encryption. The trade-off is that anyone who can reach the registry address on the isolated network could serve a modified image.
- Setup effort: No certificate chain needs to be issued or rotated, so a pilot registry can run quickly.
- Trust model: Image integrity depends on digest checks and on your media handling, since the transport offers no server verification.
- Host configuration: Each container runtime needs an insecure-registry entry for the mirror address, and new hosts are easy to miss.
- Exposure: Any host or device that can reach the registry port can pull images, and can push them if write access is open.
Before choosing this option, confirm the insecure-registry settings for your container runtime and the registry settings for your cephadm release, and record who is allowed to push.
A TLS registry presents a certificate issued by your internal certificate authority, so every client can verify the server before pulling. It takes more planning, because the CA root and the registry certificate must be issued, stored and renewed on a schedule your operations team can sustain. The benefit is that the transfer is encrypted and the server identity is checked on every connection, which matches how most security teams expect internal services to behave.
- Certificate issuance: Issue the registry certificate with the names and addresses hosts use to reach it, or verification fails on every pull.
- Root distribution: Install the internal CA root on every host, including hosts added after the initial build.
- Renewal: Track certificate expiry and plan rotation, since an expired certificate stops pulls across the cluster at once.
- Key protection: Restrict access to the registry private key, because a copied key allows someone to impersonate the mirror.
Before committing to this model, check the TLS and login settings your cephadm release expects, and test a pull from a newly added host before the first bootstrap.
cephadm pulls container images on every host it manages, not only on the bootstrap node. Each host must resolve the registry name, trust its certificate or accept the insecure setting, and authenticate if the registry requires login. The same path serves Ceph daemon images and the monitoring images cephadm deploys. A host that cannot pull often shows only a failed daemon deployment, so test pulls early and on each new host.
- Name resolution: Every host needs the same stable DNS name or host entry for the registry.
- Bootstrap image: The bootstrap command should reference the Ceph image held in your local registry, and the reference must match what the mirror actually stores.
- Monitoring images: Mirror the monitoring images that cephadm deploys with Ceph, or those services will stay in a failed state.
- Added hosts: Hosts added later need the same trust and login setup, so include it in your provisioning standard.
Confirm which image settings your cephadm version reads from its configuration, and whether registry credentials are stored by cephadm or by the host, using the cephadm documentation.
Each option leaves a different record. A plain HTTP registry logs requests with client addresses and image names, but the transport gives no proof of who served the content. A TLS registry adds certificate issuance, renewal and handshake failure records, which auditors can follow when they ask how images entered the isolated network. In both cases, the most useful evidence is your own import log showing who brought each image across the boundary, from which verified source, and when.
- Access logs: Keep registry request logs with timestamps, client addresses and image names, and forward them to your central log store.
- Certificate records: For TLS, keep CA issuance and renewal records alongside the registry certificate inventory.
- Import records: Record the digest of every image imported across the boundary and the person who approved it. Utilities subject to NERC CIP-013-2 should map this to their software integrity verification process.
- Change history: Track changes to registry settings and host trust configuration in version control.
Ask your security and compliance team which of these records they need, and confirm the log format and retention options of your chosen registry software.
Which registry and bootstrap options fit which site
This table compares the registry type, bootstrap image source and mirror refresh method for common air-gapped situations, from a short-lived lab build to a long-lived regulated site. Read each row as a pairing: the registry choice sets how images reach the hosts, and the refresh method sets how upgrades arrive later. Check the cephadm documentation for the exact flags before you commit to an approach.
| Option | How it works | Trade-off | When it fits |
|---|---|---|---|
| Plain HTTP registry on the bootstrap network | Images are served without TLS and hosts are told to accept the registry as insecure | Fast to stand up, but image integrity depends entirely on how the images were loaded | Short-lived lab or proof-of-concept builds with few hosts and no change control |
| TLS registry with an internal certificate authority | Images are served over TLS and every host trusts the internal CA | Adds certificate distribution and renewal work, but gives transport protection and a clear trust chain | Long-lived sites where hosts already trust an internal CA and the registry is reviewed like other infrastructure |
| Bootstrap from a local image reference | The first node pulls the Ceph image from the local registry rather than a public one | Needs the image and its tag copied in advance, so the exact version must be chosen up front | Any air-gapped build, because bootstrap and every later host add must not reach the internet |
| Manual image load on each host | Image archives are copied to each host and loaded into the container runtime | No registry to run, but every host must be kept in step by hand, which is error-prone at scale | Very small clusters where the team accepts manual work for each upgrade |
| Periodic mirror refresh from approved media | New release and monitoring images are copied in from a reviewed transfer, then the registry is updated | Predictable and auditable, but upgrades wait for the next transfer window | Regulated sites with change control, where each imported image is checked before use |
| Continuous mirror sync through a controlled gateway | A mirror host pulls from upstream through a monitored path that is allowed by policy | Keeps the mirror current, but the gateway becomes part of the security boundary and needs its own review | Sites that allow a one-way, monitored sync and have a defined owner for that path |
Mirroring Ceph images and bootstrapping offline, step by step
This sequence takes an isolated network from no Ceph software to a first monitor and manager running from a local image, with every image checked before any host depends on it.
Confirm the target Ceph release
Before anything is downloaded, choose the Ceph release the cluster will run and confirm it against the active releases page. At the time of the supplied facts, Tentacle (20.2.x) and Squid (19.2.x) were the actively maintained series, with Tentacle's latest listed as 20.2.4 and Squid's as 19.2.7. Record the exact patch version, its end-of-life date and the release you will upgrade to later. Confirm the release again on the day you mirror, because point releases change. The output is a one-line release record that every later step references, so the mirror, the registry and the bootstrap command all use the same tag.
Inventory every image the deployment needs
Build a complete list of container images before mirroring, not only the Ceph image. Include the Ceph image itself, the monitoring stack that cephadm deploys (such as Prometheus, Grafana, Alertmanager and node-exporter), and any gateway or helper images for services you plan to add, such as the Ceph Object Gateway or the Dashboard's supporting services. Confirm the exact image names and tags for your release in the cephadm documentation, since defaults can differ between versions. Have the network or platform owner sign off on the list. The output is a reviewed manifest that the mirror job reads, so a missing image is caught here rather than during a failed bootstrap.
Mirror and verify the images on a connected host
On a staging host with internet access, pull each image in the manifest and push it to a transfer medium or a staging registry that your change process permits. Record the digest of every image, not only its tag, and store the digest list with the release record. Verify the artifacts against the source using the checksums or signatures your organization requires, which is the control behind NERC CIP-013-2 for software carried across a boundary if you operate in that sector. Keep the manifest and digest list in your change record. The output is a set of images with a matching digest list, and a sign-off that the transfer copy matches the source.
Stand up the local registry
On a host inside the isolated network, run the registry that will serve the images to every Ceph host. Decide first whether it will use TLS with a certificate issued by your internal certificate authority or run as an insecure registry on a trusted segment. TLS is the stronger default because it protects image pulls from tampering on the network. If you choose insecure access, document the exception and restrict the registry to the cluster network. Load the verified images into the registry and push them under the same tags and digests. The output is a registry listing every manifest image, checked from one Ceph host with a pull test.
Distribute registry trust to every host
Install the registry's CA certificate, or the insecure registry setting, on every Ceph host and on the admin host where cephadm runs, then restart the container runtime so it reads the change. Confirm that each host can pull a test image from the local registry and cannot reach the public internet. Record the host list and the result of each pull. This step is where most offline bootstraps fail, because a single host with a stale trust store will refuse images during later host addition. The output is a pull test passing on every host, with the results stored with the change record.
Bootstrap with the local image
Run the cephadm bootstrap on the first host using the local Ceph image reference, so cephadm pulls only from your registry. Pass the image name and the monitor IP on the cluster network, and set the bootstrap to use the exact release tag from step one. Confirm that the first monitor and manager start from the local image and that the monitoring images are read from the local registry too, by checking the container image list on the host. Save the bootstrap output, including the dashboard address and the generated admin key path, in your secrets system. The output is a running single-node cluster with one monitor and one manager, both running from the local image.
Run health checks before adding hosts
Before adding any other host or service, check the cluster from the admin host. Confirm that the cluster reports healthy or explains each warning, that the monitor and manager are up, and that the orchestrator can reach the host. Check that the monitoring images deploy from the local registry when their services start. Confirm the cephadm version and the Ceph release match the record from step one. Only proceed to adding hosts over SSH, placing services and creating OSDs once these checks pass. The output is a dated health report showing no unexplained warnings, which becomes the baseline for every later upgrade.
Keep the mirror current for upgrades
Treat the local registry as a managed copy of the vendor's images, not a one-time load. Before each upgrade, repeat the release check, the inventory and the mirror and verify steps for the new target version, and add the new digests to the record. Keep old tags in the registry until the upgrade is complete and rollback is no longer needed, so cephadm can still pull images if an upgrade stops partway. The output is an updated mirror and manifest for the target release, reviewed before any upgrade starts. Ask your upgrade planner to confirm the exact supported upgrade path for your starting version.
Security and supply chain controls for an isolated boundary
An isolated Ceph cluster is only as trustworthy as what crosses into it. The controls below cover the images you import, who can change the registry, how cluster and management traffic is protected, and how each change is recorded for review.
Verify image provenance and digests
Before any image leaves the connected side, record the digest of every Ceph and monitoring image and compare it with the values published by the release source. Carry the digest list across the boundary with the images, so the import can be checked against it. Confirm the digest manifest is signed or transferred through a channel your change process trusts. Repeat the check on the isolated side before the first bootstrap.
Control who writes to the registry
The local registry becomes the source for every host pull, so write access to it is a supply chain control in its own right. Limit push rights to the named mirror operators, separate them from the people who run cluster operations, and require a documented reason for each new tag. Ask your registry vendor how it enforces these roles and whether pushes are logged per user.
Protect traffic with msgr2 secure mode
Ceph daemons talk over the messenger v2 protocol on port 3300. Its secure mode encrypts all traffic after authentication and adds integrity checks, which matters when monitors, OSDs and clients share a segment that you do not fully control. Confirm that your firewall rules allow port 3300 only between the hosts that need it, and verify the mode in your cluster configuration after bootstrap.
Choose Dashboard single sign-on
The Ceph Dashboard supports single sign-on through SAML 2.0, and through OAuth2 when cephadm runs the Management Gateway and OAuth2 Proxy services. Choose the option that matches the identity provider already inside your boundary, and test that local fallback accounts are disabled or tightly controlled. Confirm the exact service versions your release supports before you plan the configuration.
Restrict host SSH access for cephadm
Cephadm manages hosts over SSH using a key held by the orchestrator, so anyone who can reach that key can change every daemon in the cluster. Limit the account and its sudo rights, restrict which source hosts can connect, and keep the key rotation procedure in your runbook. Review which administrators hold host login rights, since these are separate from Dashboard roles.
Log every image import
Each transfer into the isolated network should leave a change record: who carried the media, which image names and digests were imported, the time of import, and the reviewer who approved it. Keep these records alongside the registry's own push logs so that a later question about any running image can be traced to a specific import. Ask your auditor which evidence format they expect for transfers.
Keeping the mirror current for upgrades without internet access
Every Ceph point release and every major upgrade needs its own set of container images in the local registry before cephadm can use them. A mirror that was complete at bootstrap is out of date the first time a maintenance release lands, so the registry refresh has to be a planned, repeatable transfer through the same controlled import path you use for the original images, with the same checksum and signature verification at the boundary. Include the Ceph images, the monitoring stack images cephadm deploys (Prometheus, Grafana, Alertmanager and node exporter), and any gateway or dashboard helper images your service specifications reference. Record which tags you imported, when, and from which release, so an upgrade can be traced back to a known image set.
Plan the refresh cadence against the Ceph releases page. That page states that actively maintained releases receive periodic backports and security fixes, and it lists estimated end-of-life dates: Squid (19.2.x) is estimated to reach end of life on October 31, 2026, and Tentacle (20.2.x) on June 1, 2027. Those dates are estimates, so confirm them on the page before you commit to a schedule. Tie the refresh to the point releases you intend to run, and treat an end-of-life date as the point where you must have a supported upgrade path already staged, not the point where you start planning one. Ask your vendor or internal security team how quickly a security fix must reach the enclave, because that answer sets the minimum refresh interval more than the calendar does.
Test every refresh in a non-production copy of the cluster before it touches production. Stand up a lab with the same cephadm version, the same registry hostname and the same certificate trust, point it at the new image set, and run the upgrade with ceph orch upgrade start while watching ceph orch upgrade status and ceph health detail. Confirm that every monitoring image pulls, that the dashboard still loads, and that the daemons restart in the order cephadm expects. Keep the previous image set in the registry until the production upgrade is complete and verified, so a rollback does not depend on a new transfer across the boundary.
Limits to confirm in your environment before you commit
Each card is a decision or check that changes the mirror, the bootstrap command or the network design. Confirm them with your release plan and your registry owner before the offline transfer starts, because most are simple to settle now and costly to discover mid-build.
cephadm needs v15.2.0 or later
cephadm was introduced in v15.2.0 (Octopus) and does not support older releases. If your target cluster or any source system depends on an older Ceph version, plan the upgrade or migration before you start the air-gapped build. Confirm that your target is Squid or Tentacle, the two releases the project currently maintains with periodic backports and security fixes, and check the release status before you commit.
Image list for your release
Each Ceph release pulls a specific set of container images, and cephadm needs every image in that list in your local registry before bootstrap. Build the list from the release you will install, not from whatever tag you last saw online, and repeat the exercise for your planned upgrade target so the mirror does not fall behind. Ask the vendor contact or the cephadm documentation to confirm the image names and tags for that release before the transfer.
Monitoring image versions
The Dashboard monitoring stack runs its own container images, such as Prometheus, Grafana and Alertmanager, and each monitoring tag must exist in the mirror at the version your cephadm release expects. If you plan single sign-on through the Management Gateway and OAuth2 Proxy, those services need images as well. Confirm the exact monitoring tags during planning, because a missing tag may surface only when that service is deployed.
Registry storage capacity
A mirror holds every image for each release in scope, plus older tags you keep for rollback and the target of your next upgrade. Size the registry disk for the full set across all planned releases and leave room for growth. Then measure the transfer on a staging host before the isolated network is closed. Ask the team that owns the registry to confirm backup and retention for these images.
DNS and certificate naming
Every host and the registry must resolve by name, and the certificate the registry presents must match the hostname that clients use. A name mismatch fails the pull, so settle hostnames, short names and subject alternative names before bootstrap. Skipping certificate checks with an insecure registry removes that failure mode but moves trust into your change process, so choose TLS unless you have a documented reason to do otherwise.
Rook if you run Kubernetes
If the platform underneath is Kubernetes, the cephadm documentation points to Rook as the alternative route, and the CNCF lists Rook as a Graduated project since October 7, 2020. Decide before the mirror is built, because the image set, operators and storage consumers differ between the two models. Confirm which model your platform team can operate and support over the full upgrade lifecycle.
Questions buyers ask before deploying Ceph air-gapped
What drives the cost and effort of an air-gapped Ceph deployment?
The largest cost is usually staff time, not software, because Ceph is open source under LGPL-2.1 or LGPL-3 and carries no license fee from the project itself. Effort rises with the number of hosts, the size of the image set you must mirror (Ceph, monitoring and any gateway images), the number of transfer cycles across your isolation boundary, and the validation each package set needs before it enters the enclave. Recurring costs are the mirror refresh for every point release and the staff time for each upgrade window. Ask any quote to split one-time build work (registry, certificates, first bootstrap, runbooks) from recurring work (mirror updates, upgrade rehearsals, evidence collection), and to state which hardware and transfer media are client-supplied.
Can our internal team deploy Ceph air-gapped without outside help?
Yes, if your team already runs Linux, container registries, SSH-based automation and Ceph itself. The steps are documented in the cephadm guidance, and the hard parts are operational: building a repeatable mirror process, deciding between an insecure and a TLS-protected registry, and keeping the bootstrap image and monitoring images in step with the Ceph release you chose. Teams that have never bootstrapped Ceph usually spend their time on host preparation and network design, not on the registry. Before committing, confirm that at least two people can perform a full mirror refresh and a rehearsed upgrade without the original builder, and that someone owns evidence for your assessor.
How long does an air-gapped Ceph build take?
The duration depends on how many hosts you have, how many change approvals your organization needs, and how many transfer cycles the isolated network requires. A small cluster with a prepared registry host and pre-approved change windows moves much faster than a multi-room build that needs security review of every imported image. Ask for a timeline that separates the registry and certificate work, the host preparation, the bootstrap and service placement, and the post-build checks. Any timeline should name the change windows it assumes, because approval lead time often dominates the schedule.
What do we need to provide before the work starts?
You need to provide the hardware or approved virtual hosts, the network segments for the isolated cluster and the staging area, an internal certificate authority if you use TLS for the registry, and named contacts who can approve change windows. Temporary network access for staging is often needed to pull images in a controlled way before they cross the boundary, so define that path and its logging in writing. Also confirm which transfer media your policy allows and who verifies package integrity when files cross the boundary. Missing items in this list are the most common cause of schedule slips.
How do Ceph upgrades change the air-gapped mirror work?
Every upgrade needs a new set of images in the local registry before cephadm can move the cluster, so the mirror process repeats for each release you adopt. The Ceph releases page notes that active releases receive periodic backports and security fixes, which means refreshes are routine, not occasional. Monitoring images (for example Prometheus, Grafana and Alertmanager) must be refreshed alongside Ceph itself, and you must check each image's version against the release you are moving to. Plan the upgrade path and the mirror cycle together, and rehearse the full sequence in a non-production copy before the real window.
Can DeployOpen take over the cluster after go-live?
DeployOpen can provide ongoing support, upgrades and continuous testing under a retainer, and most engagements are fixed-scope with scope and deliverables agreed in writing before work begins. Handover is the part to plan: ask for runbooks covering the mirror process, the registry, certificate renewal, bootstrap recovery and upgrade steps, and for a rehearsed knowledge transfer. Decide before go-live who will perform each recurring task, whether your staff, a retainer or both. DeployOpen does not issue audit reports or certifications, so any evidence you need for an assessment will be prepared for your independent assessor to review.
What does a secure, verifiable image transfer process look like?
Each image or package that crosses the isolation boundary should be recorded with its source, version and digest, and checked against that record on the inside before it is loaded into the registry. This matters for supply chain controls: NERC CIP-013-2 requires procurement processes to address verification of software integrity and authenticity of vendor software and patches, and that is the control behind checking each package carried across the boundary. Keep the transfer log with the change record. If your sector has a different framework, confirm with your assessor which evidence they expect for the same step.
How DeployOpen scopes and delivers an air-gapped Ceph build
DeployOpen starts an air-gapped Ceph build with a written scope agreed before any work begins. The scope names the hosts, the Ceph release, the monitoring images, the registry design, the bootstrap method and the handover checks. It also records what the client's own team is responsible for, such as physical installation, network switch configuration and access to the isolated enclave. Because the scope is fixed, a client can compare it against an internal estimate line by line and see which items would otherwise fall to their staff. DeployOpen works inside the client's own infrastructure, in their data center or isolated network. It prepares the systems, configuration and evidence that a client's assessors may request, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations.
Delivery follows a sequence that the scope spells out. The first stage designs the image supply chain: which Ceph and monitoring images are mirrored, whether the local registry uses plain HTTP marked as insecure or TLS with an internal certificate authority, and how the image references are pinned to digests. The second stage performs the bootstrap with the local image and then runs verification, including ceph -s health output, daemon placement, dashboard access and a check that no component is trying to reach a public registry. The third stage produces the documentation that matters most after go-live: a runbook for refreshing the mirror from newer release media, validating each imported image, and staging the cephadm upgrade. Confirm with your own security team how images and packages are checked before they cross into the enclave, since that control is usually owned by your procurement and change processes.
Ongoing help is optional and sold separately. DeployOpen offers retainers for upgrades and ongoing support, so the mirror refresh and Ceph upgrade steps can be run again by a partner rather than being left to a team that built the cluster once. When you request a quote, ask for the scope to state the Ceph release it targets, the number of hosts and registries in scope, who performs image intake, and what evidence the handover pack contains. Ask whether the retainer covers the mirror refresh procedure, how upgrade windows are scheduled inside an isolated network, and what happens when the release you deployed reaches its end of life. A quote should separate one-time build work from recurring support so that both costs are visible.
