checkId: check.agent.version.consistency plugin: stellaops.doctor.agent severity: warn tags: [agent, version, maintenance]

Agent Version Consistency

What It Checks

Groups all non-revoked, non-inactive agents by their reported Version field and evaluates version skew:

  1. Single version across all agents: Pass – all agents are consistent.
  2. Two versions with skew affecting less than half the fleet: Pass (minor skew acceptable).
  3. Significant skew (more than 2 distinct versions, or outdated agents exceed half the fleet): Warn with evidence listing the version distribution and up to 10 outdated agent names.
  4. No active agents: Skip.

The “majority version” is the version running on the most agents. All other versions are considered outdated. Evidence collected: MajorityVersion, VersionDistribution (e.g., “1.5.0: 8, 1.4.2: 2”), OutdatedAgents (list of names with their versions).

Why It Matters

Version skew across the agent fleet can cause subtle compatibility issues: newer agents may support task types that older agents reject, protocol changes may cause heartbeat or dispatch failures, and mixed versions make incident triage harder because behavior differs across agents. Keeping the fleet consistent reduces operational surprises.

Common Causes

How to Fix

Docker Compose

# Check agent image versions
docker compose -f devops/compose/docker-compose.stella-ops.yml ps agent --format json | \
  jq '.[] | {name: .Name, image: .Image}'

# Pull latest image and recreate
docker compose -f devops/compose/docker-compose.stella-ops.yml pull agent
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d agent

Bare Metal / systemd

# Update outdated agents to target version
stella agent update --version <target-version> --agent-id <id>

# Enable auto-update
stella agent config --agent-id <id> --set auto_update.enabled=true

# Batch update all agents
stella agent update --version <target-version> --all

Kubernetes / Helm

# Check running image versions across pods
kubectl get pods -l app.kubernetes.io/component=agent -n stellaops \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'

# Update image tag in Helm values and rollout
helm upgrade stellaops stellaops/stellaops --set agent.image.tag=<target-version>

# Monitor rollout
kubectl rollout status deployment/stellaops-agent -n stellaops

Verification

stella doctor run --check check.agent.version.consistency