Troubleshooting

Kubernetes

Agent pods are CrashLoopBackOff

kubectl logs -n spire -l app=spire-agent --previous

• Invalid Tenant ID — check the ConfigMap or Helm values
• Cannot reach Spire Server — ensure outbound HTTPS to prod.api.authsec.ai:443 is open

Workloads don't get SVIDs

1. Check the socket exists: kubectl exec -n spire <agent-pod> -- ls -la /run/spire/sockets/agent.sock
2. Check your pod can see it: kubectl exec -n production <your-pod> -- ls -la /run/spire/sockets/agent.sock
3. Check selectors match: kubectl logs -n spire -l app=spire-agent | grep selector
4. Verify the workload entry is registered for the correct namespace + service account

Permission denied on /proc

• Ensure hostPID: true on the DaemonSet
• Ensure SYS_PTRACE capability is allowed
• Check PodSecurityStandards aren't blocking hostPID

Docker

Agent container keeps restarting

docker compose logs spire-agent --tail=50

• Invalid Tenant ID — check ICP_AGENT_AGENT__TENANT_ID in your compose file
• Cannot reach Spire Server — ensure outbound HTTPS to prod.api.authsec.ai:443 is open
• Docker socket not mounted — ensure /var/run/docker.sock is mounted read-only

Workloads don't get SVIDs

1. Check the shared volume is mounted: docker exec my-ai-agent ls -la /run/spire/sockets/agent.sock
2. Check container labels match the registered selectors: docker inspect my-ai-agent --format '{{ "{{" }}.Config.Labels{{ "}}" }}'
3. Check agent logs for attestation: docker compose logs spire-agent | grep selector

Unix (VM / Bare Metal)

Agent won't start

sudo journalctl -u spire-agent --tail=50

• Invalid Tenant ID — check /etc/spire-agent/config.yaml
• Cannot reach Spire Server — ensure outbound HTTPS to prod.api.authsec.ai:443 is open
• Permission denied — ensure spire-agent is installed and required directories exist (/var/lib/spire-agent, /run/spire/sockets)

Workloads don't get SVIDs

1. Check the socket exists: ls -la /run/spire/sockets/agent.sock
2. Check your app user has read access to the socket
3. Check process selectors match: ps aux | grep your-app — verify the UID/path match the registered selectors
4. Check agent logs: sudo journalctl -u spire-agent | grep selector

Socket permission denied

# Check socket permissions
ls -la /run/spire/sockets/agent.sock

# Fix: add your app user to the socket group
sudo chgrp myapp-group /run/spire/sockets/agent.sock
sudo chmod 660 /run/spire/sockets/agent.sock

---

FAQ

Q: What does the customer need to provide? A: Infrastructure (Kubernetes v1.24+, Docker host, or Linux VM) with outbound HTTPS access. The Tenant ID comes from AuthSec.

Q: What if the Spire Server goes down? A: The agent caches SVIDs locally (AES-256-GCM encrypted). Existing workloads keep running. New attestations fail until connectivity is restored, with automatic retry + backoff.

Q: Can I run agents on specific Kubernetes nodes only? A: Yes. Add nodeSelector or nodeAffinity to the DaemonSet. Pods on nodes without an agent won't get SVIDs.

Q: Multiple tenants on one cluster? A: Deploy separate DaemonSets in separate namespaces (spire-tenant-a, spire-tenant-b), each with its own Tenant ID.

Q: Is it compatible with standard SPIFFE libraries? A: Yes. The agent implements the SPIFFE Workload API spec. go-spiffe, java-spiffe, etc. work alongside the AuthSec SDK.

Q: Can I mix environments? A: Yes. An AI agent on a VM can communicate with a service in Kubernetes — both get SVIDs from the same trust domain via their respective agents.

---

Support

For integration help, contact the AuthSec team and include agent logs:

# Kubernetes
kubectl logs -n spire -l app=spire-agent --tail=100

# Docker
docker compose logs spire-agent --tail=100

# Unix
sudo journalctl -u spire-agent --tail=100