Skip to main content

Add Kubernetes Cluster

Overview​

Connect a Kubernetes cluster to OpsWorker so it can investigate alerts and answer questions about your infrastructure.

Prerequisites​

  • An OpsWorker account with a workspace
  • A Kubernetes cluster (EKS, GKE, AKS, or self-hosted, version 1.16+)
  • Helm 3.x and kubectl access to the cluster

Steps​

1. Start the Add Cluster Wizard​

  1. In the OpsWorker portal, navigate to Configurations -> Add Cluster
  2. The wizard guides you through the setup process

2. Choose the Workspace​

  • Select the workspace this cluster belongs to.
  • You do not name the cluster here. The name is derived from the agent after it connects.

3. Optionally Enable Grafana MCP​

The wizard offers an inline toggle to enable Grafana MCP for this cluster, which lets the AI query your Grafana metrics, logs, and dashboards during investigations and chat. Grafana MCP is separate from Grafana Alerting (which sends alerts to OpsWorker). You can configure other integrations later from the Integrations area. See the Grafana Integration guide for details.

4. Get the Install Command​

The wizard generates a Helm install command with the cluster token and API key auto-filled. Both are required and you do not type them manually. If you enabled Grafana MCP, the command includes extra flags for the Grafana sidecar.

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>

With Grafana MCP enabled, the command adds:

  --set grafana-mcp.enabled=true \
  --set grafana-mcp.grafana.url=https://grafana.example.com \
  --set grafana-mcp.grafana.apiKey=YOUR_GRAFANA_SERVICE_ACCOUNT_TOKEN

Copy this command; you will run it in the next step.

5. Install the Agent​

Run the Helm command in your terminal (with kubectl configured for your target cluster). See Install Kubernetes Agent for detailed instructions.

6. Verify Connection​

After installation, return to the portal. The portal automatically polls the agent status, so the cluster moves from Pending to a connected state within a minute. See Verify Cluster Connection for what to expect.

Resuming Setup​

A cluster that has not yet connected stays in Pending status. You can resume from Configurations and find it there. A cluster can only be deleted while it is in Pending status.

Network Requirements​

The agent requires outbound HTTPS access (port 443) to AWS SQS, AWS STS, api.opsworker.ai, and onboarding.ow-saas-prod-ext.opsworker.ai. No inbound ports need to be opened.

Next Steps​