Skip to main content

Troubleshooting Connectivity

Agent Shows as Disconnected​

Check Pod Status​

kubectl get pods -n opsworker-agent
Pod StatusLikely CauseAction
RunningAgent running but can't reach SQSCheck network/proxy
CrashLoopBackOffConfiguration error or resource issueCheck logs
ImagePullBackOffCan't pull agent imageCheck image registry access
PendingScheduling issueCheck node resources, tolerations
Not foundAgent not installedRun Helm install

Check Pod Logs​

kubectl logs -n opsworker-agent -l app.kubernetes.io/name=opsworker-agent

Look for:

  • Connection errors: network/proxy issue
  • Authentication errors: invalid cluster token or API key
  • Timeout errors: SQS endpoint unreachable

Verify Outbound Connectivity​

Test that the agent can reach AWS SQS:

kubectl exec -n opsworker-agent deploy/opsworker-agent -- \
  wget -q -O /dev/null https://sqs.us-east-1.amazonaws.com

If this fails, outbound HTTPS is blocked. Check:

  • Security groups (EKS)
  • Firewall rules (GKE)
  • NSG rules (AKS)
  • NetworkPolicy resources

The agent needs outbound HTTPS (443) to AWS SQS, AWS STS, api.opsworker.ai, and onboarding.ow-saas-prod-ext.opsworker.ai.

Check Credentials​

Verify the values used during installation:

helm get values opsworker-agent -n opsworker-agent

Both clusterToken and apiKey are required and are auto-filled by the portal Add Cluster wizard. The cluster token is the cluster's immutable identifier; there is no token rotation. If credentials are wrong, reinstall using the exact command from the portal.

Proxy Configuration​

The chart has no proxy.* values. If your cluster is behind a proxy, set the standard proxy environment variables through the chart's env list:

helm upgrade opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  -n opsworker-agent \
  --reuse-values \
  --set env[0].name=HTTPS_PROXY --set env[0].value=http://proxy.example.com:3128

Agent Connects but Goes Offline Intermittently​

Resource Limits​

Check if the pod is being OOM-killed:

kubectl describe pod -n opsworker-agent -l app.kubernetes.io/name=opsworker-agent | grep -A5 "Last State"

If you see OOMKilled, increase memory limits:

helm upgrade opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  -n opsworker-agent \
  --reuse-values \
  --set resources.limits.memory=512Mi

Node Stability​

Check if the node hosting the agent is stable:

kubectl get events -n opsworker-agent --sort-by='.lastTimestamp'

Network Intermittency​

Intermittent SQS connectivity can cause temporary disconnections. The agent automatically reconnects.

Next Steps​