Kubernetes

This guide walks you through installing the Middleware Agent (mw-agent) in a Kubernetes environment. These instructions can also be found on the Installation page in the Middleware application.

The installation will set up Middleware Agent as a DaemonSet and Deployment inside your Kubernetes cluster and add necessary components to appropriately permission the DaemonSet and Deployment pods. A Kubernetes service is also created to allow components to connect to the Middleware Agent via Cluster IP address and ports which can then be used by langague specific APM SDKs.

Prerequisites

kubectl version

kubectl version --client

Install

Step 1: Access Kubernetes Installation

Log in to your Middleware account, navigate to the Installation Page in the bottom left corner and select Kubernetes from the Infrastructure section

Step 2: Identify Kubernetes Context

Get the current Kubernetes Context and ensure the cluster belonging to this Context is where you want to install the Middleware Agent.

Use the following command to find out your current Kubernetes context:

kubectl config current-context

Note the CLUSTER name from the output of the command above. This name will be used as an input for clusterMetadata.name if you wish to use Helm option to install the Middleware Agent in the next step.

Step 3: Run Kubernetes Install Command

Install the Middleware Agent for Kubernetes with Helm, Bash or .bat. Copying the command directly from the Installation page ensures your API key and Target is inserted correctly.

helm repo add middleware-labs https://helm.middleware.io

helm install mw-agent middleware-labs/mw-kube-agent-v3 --set mw.apiKey=<MW_API_KEY> --set mw.target=https://<MW_UID>.middleware.io:443 --set clusterMetadata.name=<your-cluster-name> -n mw-agent-ns --create-namespace

mw:
  target: https://<MW_UID>.middleware.io:443
  apiKeyFromExistingSecret:
    enabled: true
    name: name-of-your-secret
    key: name-of-your-secret-key

clusterMetadata:
  name: my-cluster

MW_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)"

set MW_API_KEY="<MW_API_KEY>"

set MW_TARGET=https://<MW_UID>.middleware.io:443

mw-kube-agent-install-windows.bat

Step 4: Add Host Tags [Optional]

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).

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

Step 5: Verify Installation

Verify the status of the Middleware Agent with the following command:

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

Step 6: Check Your Dashboard

Navigate to Middleware and ensure metrics are appearing in the Kubernetes section on the Infrastructure tab. Depending on the size of your cluster, it can take up to a few minutes for metrics to appear. If metrics do not appear after this time head to our troubleshooting page for some common issues.

Upgrade

The Middleware Agent is frequently updated to add new features and improve performance. More information on new features can be found in our Newsletter.

Select one of the options below depending on your Middleware Agent installation method.

helm 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

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

Troubleshooting

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.

Switching Between Contexts

If you are using another thirdy-party resource for managing your Kubernetes Infrastructure (e.g. Lens) it's possible your cluster names are similar across clusters. This will make it hard to delineate between the clusters inside of Middleware.

To fix this, you can force a speicific cluster.name by setting the MW_KUBE_CLUSTER_NAME environment variable to the name(s) you are using in your thrid party resource. Once the cluster is renamed, it will automatically reset and start to catch the appropriately labeled environment variables.

Uninstall

helm uninstall mw-agent -n mw-agent-ns
kubectl delete ns mw-agent-ns

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