NebulaCR: Enterprise OCI Registry, Observability, and Compliance Without Compromise

Executive summary

NebulaCR is an open-source, cloud-native OCI container registry written in Rust. It pairs a standards-compliant nebula-registry service (port 5000) with a dedicated nebula-auth token service (port 5001), optional HashiCorp Vault integration for signing keys, pluggable object storage (filesystem, S3, GCS, Azure Blob), and first-class Kubernetes packaging with CRDs for tenants, projects, and policies. The upstream project positions the product around private, observable, and governable image distribution; see nebulacr.org for the public landing page and github.com/bwalia/nebulacr for source and releases.

Why enterprises adopt a private OCI registry

Container images are now the unit of deployment for most cloud-native teams. A registry that only lives inside your security boundary lets you enforce data residency, supply-chain controls, fine-grained RBAC, and predictable cost (especially when combined with pull-through caching for upstream registries). NebulaCR targets operators who need Docker-compatible workflows without surrendering identity, auditability, or multi-region resilience.

Rust workspace (Cargo.toml)

Upstream Cargo.toml declares a workspace of seven crates: nebula-common, nebula-auth, nebula-registry, nebula-controller, nebula-resilience, nebula-mirror, and nebula-replication. The README’s project tree maps each crate to binaries or libraries—registry and auth services, the Kubernetes reconciler, pull-through cache engine, resilience helpers, and multi-region replication. From source, run cargo build --workspace --release and cargo test --workspace before containerising with the root Dockerfile or optimised Dockerfile.scratch.

Architecture distilled from project documentation

Beyond the three core binaries/libraries described above, nebula-controller reconciles Tenant/Project/AccessPolicy/TokenPolicy CRDs, nebula-mirror implements pull-through caching for upstream registries, nebula-resilience carries retries and circuit breakers for replication paths, and nebula-replication backs multi-region async or semi-sync modes with failover described in docs/architecture.md. nebula-registry remains Axum-based with JWT enforcement per request; nebula-auth validates OIDC identity tokens and issues short-lived registry JWTs. Storage stays hierarchical per tenant/project while backends remain pluggable.

Ingress routes, health checks, and metrics

The README’s ASCII architecture shows traffic splitting: /v2 to the registry service (5000) and auth flows (often under /auth) to nebula-auth (5001), with OIDC providers external to both. Helm charts expose Prometheus metrics (examples include nebulacr_http_requests_total, nebulacr_http_request_duration_seconds, nebulacr_storage_operations_total, nebulacr_auth_tokens_issued_total) and document curl http://localhost:5000/health after kubectl port-forward to the registry Service.

Zero-trust authentication and CI integration

NebulaCR emphasises no long-lived registry passwords for automation. CI systems present OIDC identity tokens from trusted issuers; nebula-auth validates signatures, applies policy, and returns scoped JWTs with tight TTL defaults (commonly around five minutes). Human operators authenticate through standard OIDC authorization-code flows with PKCE against providers such as Azure AD, Okta, or Google Workspace.

CRDs, pull-through cache, and rate limits

Kubernetes operators manage Tenant (quotas, OIDC bindings), Project (repository groups and policies), AccessPolicy (RBAC), and TokenPolicy (TTL and robot accounts). The README documents pull-through pulls such as docker pull <host>:5000/library/nginx:latest, GHCR and Quay prefixes, and a containerd mirror stanza pointing docker.io at NebulaCR. Rate limiting applies per IP and per tenant using the governor crate.

Observability, auditing, and compliance

According to the project documentation set under docs/, NebulaCR exposes Prometheus metrics from registry and auth services, emits structured JSON logs, and supports OpenTelemetry tracing for deeper analysis. The embedded dashboard surfaces CPU, memory, disk, replication health, repository browsing, and filtered audit trails for pushes, pulls, and deletes—material evidence for security reviews. SCIM 2.0 provisioning automates joiner-mover-leaver cycles with identity providers, shrinking the window where former employees retain latent access.

High availability, multi-region, and pull-through cache

The README highlights stateless services with horizontal pod autoscaling, pod disruption budgets, and circuit breakers for replication paths. Multi-region replication is described as asynchronous with resilience controls so reads can fail over when a region degrades. Pull-through caching reduces bandwidth and pull latency for upstream registries including Docker Hub, GHCR, GCR, Quay.io, and registry.k8s.io.

Getting started

For a minimal local trial the README documents docker run -p 5000:5000 bwalia/nebulacr:latest, docker compose up -d for registry plus auth on 5001 with generated JWT keys, and Helm installs from oci://ghcr.io/bwalia/charts/nebulacr or the GitHub Pages repo. Multi-arch images ship as linux/amd64 and linux/arm64 on Docker Hub and GHCR. Production teams wire deploy/helm/nebulacr with ingress TLS, optional OIDC and S3, ServiceMonitor scraping, and NetworkPolicy templates from the chart.

How TenthMatrix can help

TenthMatrix designs and implements secure platform engineering patterns—private registries, GitOps promotion pipelines, policy as code, and SRE observability—across cloud and on-premises environments. For architecture reviews or delivery support, contact info@tenthmatrix.com.