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>
This commit is contained in:
104
docs/doctor/articles/docker/network.md
Normal file
104
docs/doctor/articles/docker/network.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
checkId: check.docker.network
|
||||
plugin: stellaops.doctor.docker
|
||||
severity: warn
|
||||
tags: [docker, network, connectivity]
|
||||
---
|
||||
# Docker Network
|
||||
|
||||
## What It Checks
|
||||
Validates Docker network configuration and connectivity. The check connects to the Docker daemon and lists all networks, then verifies:
|
||||
|
||||
1. **Required networks exist**: Checks that each network listed in `Docker:RequiredNetworks` configuration is present. Defaults to `["bridge"]` if not configured.
|
||||
2. **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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```yaml
|
||||
environment:
|
||||
Docker__RequiredNetworks__0: "stellaops-network"
|
||||
Docker__RequiredNetworks__1: "bridge"
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
For bare metal deployments, Docker networks must be created manually:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
doctor:
|
||||
docker:
|
||||
requiredNetworks: [] # Not applicable in Kubernetes
|
||||
```
|
||||
|
||||
Or verify Kubernetes networking:
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.docker.daemon` — Docker daemon must be running to query networks
|
||||
- `check.docker.socket` — Docker socket must be accessible to communicate with the daemon
|
||||
Reference in New Issue
Block a user