Skip to main content

Installation

Overview​

Install the OpsWorker Kubernetes Agent using Helm from the public OCI registry. There is no helm repo add step. A default install runs three pods in the opsworker-agent namespace: the agent itself plus two bundled subcharts (the read-only kubernetes-mcp-server and grafana-mcp).

Steps​

1. Get the Install Command​

Use the command shown in the OpsWorker portal's Add Cluster wizard. The portal auto-generates and fills in both the clusterToken and the apiKey, so you do not type these yourself. The cluster token is the cluster's immutable identifier (there is no token rotation feature).

helm install opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  --timeout=90s \
  --namespace opsworker-agent \
  --create-namespace \
  --set clusterToken=<auto-filled by portal> \
  --set apiKey=<auto-filled by portal>

Both clusterToken and apiKey are required.

2. Verify the Pods are Running​

kubectl get pods -n opsworker-agent

A default install creates three pods (the agent, kubernetes-mcp-server, and grafana-mcp):

NAME                                          READY   STATUS    RESTARTS   AGE
opsworker-agent-xxxxxxxxxx-xxxxx              1/1     Running   0          30s
opsworker-agent-kubernetes-mcp-server-...    1/1     Running   0          30s
opsworker-agent-grafana-mcp-...              1/1     Running   0          30s

3. Check Agent Logs​

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

Look for messages indicating a successful connection to SQS.

4. Confirm in Portal​

Return to the OpsWorker portal. The portal automatically polls the agent status, so your cluster moves from Pending to a connected state within a minute. No manual verification step is required.

Custom Installation​

With a Proxy​

The chart has no proxy.* values. Set the standard proxy environment variables through the chart's env list:

helm install opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  --namespace opsworker-agent \
  --create-namespace \
  --set clusterToken=<auto-filled by portal> \
  --set apiKey=<auto-filled by portal> \
  --set env[0].name=HTTPS_PROXY --set env[0].value=http://proxy.example.com:3128 \
  --set env[1].name=NO_PROXY --set env[1].value=10.0.0.0/8\,172.16.0.0/12

With Grafana MCP​

To enable the AI to query Grafana during investigations and chat:

helm install opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  --namespace opsworker-agent \
  --create-namespace \
  --set clusterToken=<auto-filled by portal> \
  --set apiKey=<auto-filled by portal> \
  --set grafana-mcp.enabled=true \
  --set grafana-mcp.grafana.url=https://grafana.example.com \
  --set grafana-mcp.grafana.apiKey=YOUR_GRAFANA_SERVICE_ACCOUNT_TOKEN

With a Values File​

helm install opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  --namespace opsworker-agent \
  --create-namespace \
  -f values.yaml

See Configuration for the full list of values.

Upgrading​

helm upgrade opsworker-agent oci://public.ecr.aws/k1v3l8a8/opsworker-agent \
  --version=v0.9.3 \
  -n opsworker-agent \
  --reuse-values

Uninstalling​

helm uninstall opsworker-agent -n opsworker-agent
kubectl delete namespace opsworker-agent

Next Steps​