Files

master c58a236d70 Doctor plugin checks: implement health check classes and documentation

Implement remediation-aware health checks across all Doctor plugin modules
(Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment,
EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release,
Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation,
Authority, Core, Cryptography, Database, Docker, Integration, Notify,
Observability, Security, ServiceGraph, Sources, Verification).

Each check now emits structured remediation metadata (severity, category,
runbook links, and fix suggestions) consumed by the Doctor dashboard
remediation panel.

Also adds:
- docs/doctor/articles/ knowledge base for check explanations
- Advisory AI search seed and allowlist updates for doctor content
- Sprint plan for doctor checks documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-27 12:28:00 +02:00

3.3 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

Docker Network

What It Checks

Validates Docker network configuration and connectivity. The check connects to the Docker daemon and lists all networks, then verifies:

Required networks exist: Checks that each network listed in Docker:RequiredNetworks configuration is present. Defaults to ["bridge"] if not configured.
Bridge driver available: Verifies at least one network using the bridge driver exists.

Evidence collected includes: total network count, available network drivers, found/missing required networks, and bridge network name.

If the Docker daemon is unreachable, the check is skipped.

Why It Matters

Docker networks provide isolated communication channels between containers. Stella Ops services communicate over dedicated networks for:

Service-to-service communication: Platform, Authority, Gateway, and other services need to reach each other.
Database access: PostgreSQL and Valkey are on specific networks.
Network isolation: Separating frontend, backend, and data tiers.

Missing networks cause container DNS resolution failures and connection refused errors between services.

Common Causes

Required network not found (not yet created or was deleted)
No bridge network driver available (Docker networking misconfigured)
Docker Compose network not created (compose project not started)
Network name mismatch between configuration and actual Docker networks

How to Fix

Docker Compose

Docker Compose normally creates networks automatically. If missing:

# List existing networks
docker network ls

# Start compose to create networks
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d

# Create a network manually if needed
docker network create stellaops-network

# Inspect a network
docker network inspect <network-name>

Configure required networks for the check:

environment:
  Docker__RequiredNetworks__0: "stellaops-network"
  Docker__RequiredNetworks__1: "bridge"

Bare Metal / systemd

For bare metal deployments, Docker networks must be created manually:

# Create required networks
docker network create --driver bridge stellaops-frontend
docker network create --driver bridge stellaops-backend
docker network create --driver bridge stellaops-data

# List networks
docker network ls

# Inspect network details
docker network inspect stellaops-backend

Kubernetes / Helm

Docker networks are not used in Kubernetes; instead, Kubernetes networking (Services, NetworkPolicies) handles inter-pod communication. Configure the check to skip Docker network requirements:

doctor:
  docker:
    requiredNetworks: []  # Not applicable in Kubernetes

Or verify Kubernetes networking:

# Check services
kubectl get svc -n stellaops

# Check network policies
kubectl get networkpolicy -n stellaops

# Test connectivity between pods
kubectl exec -it <pod-a> -- curl http://<service-b>:5000/health

Verification

stella doctor run --check check.docker.network

check.docker.daemon — Docker daemon must be running to query networks
check.docker.socket — Docker socket must be accessible to communicate with the daemon

3.3 KiB Raw Blame History