Install the Middleware Agent on Kubernetes

This page covers how you can install the Middleware agent (mw-agent) on Kubernetes environment.

The installation process automatically deploys two sets of Middleware Agent pods in your cluster. One (a DaemonSet) so there’s an agent running on every node to collect OS‑level metrics, and another (a Deployment) to handle cluster‑wide telemetry. It also creates ServiceAccounts, Roles, and RoleBindings so those pods have just enough permissions to read pod, node, and namespace data without exposing anything extra, which can then be used by language-specific APM SDKs.

Prerequisites

1 Kubernetes Version

You are required to have Kubernetes version ≥ 1.21 which can be verified using the following command:

1kubectl version
Check Kubernetes version for Middleware Agent deployment with Argo CD

2 Kubernetes Access

kubectl ≥ v1.17.0 configured against your target cluster which can be verified with the following:

1kubectl version --client

3 CLI Tools

Helm v3.5+ (if using Helm) or a shell with bash, curl, and wget installed.

Installation

1 Access Kubernetes Installation

Log in to your Middleware account, open the Installation page (bottom‑left), and select Kubernetes.

Kubernetes cluster access and Middleware Agent installation steps via Argo CD

2 Identify Kubernetes Context

Now, get the current Kubernetes Context and ensure the cluster belonging to this Context is where you want to install the Middleware Agent which can be found using the given command:

1kubectl config current-context
Identify and select Kubernetes context for Middleware Agent deployment

Note the CLUSTER name which will be used this as input for clusterMetadata.name in the Helm installation.

3 Run Kubernetes Install Command

Copy the exact command (Helm, Bash, or Windows) from the Installation page so your <MW_API_KEY> and <MW_UID> are auto‑inserted.

Helm
Bash
.bat
1helm repo add middleware-labs https://helm.middleware.io  
2  helm install mw-agent middleware-labs/mw-kube-agent-v3 \
3    --namespace mw-agent-ns --create-namespace \
4    --set mw.apiKey=<MW_API_KEY> \
5    --set mw.target=https://<MW_UID>.middleware.io:443 \
6    --set clusterMetadata.name=<your-cluster-name>

This deploys both DaemonSet and Deployment, and creates the ClusterIP Service and RBAC resources

1MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 bash -c "$(curl -L https://install.middleware.io/scripts/mw-kube-agent-install-v3.sh)"

First, Download the Middleware Agent batch. Next, Open PowerShell, change the directory to the location of the download, and execute the following commands:

1set MW_API_KEY="<MW_API_KEY>"
2
3set MW_TARGET=https://<MW_UID>.middleware.io:443
4
5mw-kube-agent-install-windows.bat

Managing API keys via Secret:

You can use an existing secret from your secret manager with the below snippet, assuming that secret has the Middleware API Key:

1mw:
2  target: https://<MW_UID>.middleware.io:443
3  apiKeyFromExistingSecret:
4    enabled: true
5    name: name-of-your-secret
6    key: name-of-your-secret-key
7
8clusterMetadata:
9  name: my-cluster

4 Add Host Tags (Optional)

This is an optional step where you can create filterable custom tags by adding the MW_HOST_TAGS environment variable to the installation command as comma-separated key-value pairs. Use the tag name to create an alias for the host (e.g. production).

1MW_HOST_TAGS=key1:value1,key2:value2,... MW_API_KEY="<MW_API_KEY>"

5 Verify Installation

To verify the installation, you can check the current status of the Middleware agent using the following command:

1kubectl get daemonset/mw-kube-agent -n mw-agent-ns
2  kubectl get deployment/mw-kube-agent -n mw-agent-ns

6 Check Dashboard

Verify Middleware Agent status on Kubernetes dashboard after deployment

Once you have all the setup ready, you can finally check the dashboard for your Kubernetes cluster with default settings which can be later configured as per your liking (e.g, rules, conditions, etc.)

Switching Between Contexts

If you’re managing multiple clusters with a third‑party tool (e.g., Lens) and those clusters share similar names, it can be difficult to distinguish them in the Middleware UI. To ensure each agent reports under the correct cluster name, you can override the default by setting the MW_KUBE_CLUSTER_NAME environment variable to match the name used in your third‑party tool. Once set, the agent will pick up the specified name and report under that label automatically.

Bash
Windows PowerShell

First, name your cluster:

1export MW_KUBE_CLUSTER_NAME="your-cluster-name"

Re‑run the installer (inherits your API key, target, and cluster name):

1MW_API_KEY="<MW_API_KEY>" MW_TARGET="https://<MW_UID>.middleware.io:443" \
2  MW_KUBE_CLUSTER_NAME="your-cluster-name" \
3  bash -c "$(curl -L https://install.middleware.io/scripts/mw-kube-agent-install-v3.sh)"

Or, if you prefer to simply restart the existing pods instead of a full reinstall:

1kubectl rollout restart daemonset mw-kube-agent -n mw-agent-ns
2  kubectl rollout restart deployment mw-kube-agent -n mw-agent-ns

First, set the environment variables:

1$env:MW_KUBE_CLUSTER_NAME = "your-cluster-name"
2  $env:MW_API_KEY            = "<MW_API_KEY>"
3  $env:MW_TARGET             = "https://<MW_UID>.middleware.io:443"

Finally, re‑run the installer batch:

1.\mw-kube-agent-install-powershell.ps1

Upgrade

The Middleware Agent is frequently updated to add new features and improve performance. More information on recent changes can be found in our Newsletter. Select the option below that matches your original installation method.

Helm
bash

(Optional) Update your Helm repo to pull in the latest chart versions:

1helm repo update middleware-labs

Upgrade the release: reusing your existing values and pointing to the new config‑updater image:

1helm upgrade --reuse-values mw-agent middleware-labs/mw-kube-agent-v3 --set namespace.name=mw-agent-ns -n mw-agent-ns --create-namespace=false --set configUpdaterImage.repository=ghcr.io/middleware-labs/mw-kube-agent-config-updater --set configUpdaterImage.pullPolicy=IfNotPresent --set configUpdaterImage.tag=1.15.1 --set mw.configCheckInterval=60s

Run the upgrade script directly, which will detect your existing installation and apply the update:

1bash -c "$(curl -L https://install.middleware.io/scripts/mw-kube-agent-upgrade.sh)"
2  ``` :contentReference[oaicite:2]{index=2}

Tip: If you need to immediately pick up new configuration values, you can also restart the agent pods:

1kubectl rollout restart daemonset mw-kube-agent -n mw-agent-ns
2kubectl rollout restart deployment mw-kube-agent -n mw-agent-ns

Troubleshooting

Run only one Middleware Agent DaemonSet per cluster per host. Multiple agents will cause unexpected behavior.

Once the Middleware Agent is installed on your cluster, metrics should begin appearing in the Middleware application within a few minutes. If metrics do not appear, confirm that Kubernetes has access to the internet, either directly or through a proxy, and that only one MW Agent is running per cluster.

Uninstall

You can remove the Middleware Agent from your Kubernetes cluster using either Helm (if you installed via Helm) or the Bash uninstall script. Choose the method matching your original installation.

Helm
bash

First, remove the Helm release:

1helm uninstall mw-agent -n mw-agent-ns

Now, delete the namespaces:

1kubectl delete namespace mw-agent-ns

With bash, all you have to do is run the uninstallation script:

1bash -c "$(curl -L https://install.middleware.io/scripts/mw-kube-agent-uninstall-v3.sh)"

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.