checkId: check.integration.oci.registry plugin: stellaops.doctor.integration severity: warn tags: [connectivity, oci, registry]

OCI Registry Connectivity

This Doctor check verifies that the Stella Ops control plane can reach its configured OCI registry over the Distribution API. It is aimed at operators and DevOps engineers diagnosing image-pull, SBOM, attestation, and promotion failures. It is the first check to run when any registry-backed workflow misbehaves; once it passes, drill into the credential and authorization checks listed under Related Checks.

What It Checks

Reads the registry URL from OCI:RegistryUrl or Registry:Url. For cataloged tenants, tenant overrides under Doctor:TenantOverrides:<tenant>:<key> or Tenants:<tenant>:<key> are checked before the global keys. Sends an HTTP GET to <registryUrl>/v2/ (the OCI Distribution Spec base endpoint). The check passes if the response is 200 (open registry) or 401 (registry reachable, auth required), warns on any other status code, and fails on connection errors.

Transient network exceptions are retried with bounded ProbeRetry; returned non-200/401 statuses are not retried. Evidence records per-tenant status and attempt counts when tenant fan-out is active.

Why It Matters

The OCI registry is the central artifact store for container images, SBOMs, attestations, and signatures. If the registry is unreachable, image pulls fail during deployment, SBOM scans cannot fetch manifests, attestation verification cannot retrieve signatures, and promotions are blocked. This is a foundational dependency for nearly every Stella Ops workflow.

Common Causes

How to Fix

Docker Compose

# Check registry configuration
grep 'OCI__REGISTRYURL\|REGISTRY__URL' .env

# Test the /v2/ endpoint from inside the network
docker compose exec gateway curl -sv https://registry.example.com/v2/

# Update registry URL
echo 'OCI__RegistryUrl=https://registry.example.com' >> .env
docker compose restart platform

Bare Metal / systemd

# Verify configuration
cat /etc/stellaops/appsettings.Production.json | jq '.OCI'

# Test connectivity
curl -v https://registry.example.com/v2/

# Fix configuration
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oci:
  registryUrl: https://registry.example.com

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor --check check.integration.oci.registry