checkId: check.integration.oci.credentials plugin: stellaops.doctor.integration severity: fail tags: [registry, oci, credentials, secrets, auth]

OCI Registry Credentials

This Doctor check validates that the registry credentials configured for Stella Ops authenticate successfully against the OCI registry. It is aimed at operators and DevOps engineers and is most useful for catching expired or rotated tokens before they silently break promotions and ingestion.

What It Checks

Determines the authentication method from configuration: bearer token (OCI:Token / Registry:Token), basic auth (OCI:Username + OCI:Password / Registry:Username + Registry:Password), or anonymous. For cataloged tenants, tenant overrides under Doctor:TenantOverrides:<tenant>:<key> or Tenants:<tenant>:<key> are checked before the global keys, so a default tenant pass cannot mask a second tenant with broken registry credentials. Immediately fails if a username is provided without a password. Then validates credentials by sending an authenticated HTTP GET to <registryUrl>/v2/. The check passes on 200 OK, or on 401 if the response includes a WWW-Authenticate: Bearer challenge and basic credentials are configured (OAuth2 token exchange scenario). It fails on 401 (invalid credentials) or 403 (forbidden), and fails on connection errors or timeouts.

Transient network exceptions while reaching /v2/ are retried with bounded ProbeRetry; returned 401/403 credential results are not retried. Evidence includes aggregate per-tenant status and retry attempt counts when tenant fan-out is active.

Why It Matters

Invalid or expired registry credentials cause image pull/push failures across all deployment pipelines. Because credentials are often rotated on a schedule, this check provides early detection of expired tokens before they silently break promotions, SBOM ingestion, or attestation storage. A username-without-password misconfiguration indicates a secret reference that failed to resolve.

Common Causes

How to Fix

Docker Compose

# Check credential configuration
grep 'OCI__USERNAME\|OCI__PASSWORD\|OCI__TOKEN\|REGISTRY__' .env

# Test credentials manually
docker login registry.example.com

# Rotate credentials
echo 'OCI__Username=stellaops-svc' >> .env
echo 'OCI__Password=<new-password>' >> .env
docker compose restart platform

Bare Metal / systemd

# Check credential configuration
cat /etc/stellaops/appsettings.Production.json | jq '.OCI | {Username, Password: (if .Password then "****" else null end), Token: (if .Token then "****" else null end)}'

# Test with curl
curl -u stellaops-svc:<password> https://registry.example.com/v2/

# Update credentials
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oci:
  registryUrl: https://registry.example.com
  existingSecret: stellaops-registry-creds   # Secret with username/password keys

# Create or update the secret
kubectl create secret generic stellaops-registry-creds \
  --from-literal=username=stellaops-svc \
  --from-literal=password=<new-password> \
  --dry-run=client -o yaml | kubectl apply -f -

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor --check check.integration.oci.credentials