Kubernetes Agent with Argo CD

Argo CD deploys and manages the Middleware Kubernetes Agent through the Middleware Helm chart. The agent collects Kubernetes resource metrics and logs for cluster and workload investigations.

This method fits environments that manage Kubernetes deployments through GitOps. Argo CD lets you deploy, update, and maintain the Middleware Agent using either its UI or declarative Kubernetes manifests.

How it works#

Argo CD deploys the Middleware Agent using the Middleware Helm chart.

You can configure the installation using:

• Argo CD UI: Create and configure the Middleware application directly in the Argo CD dashboard.
• Declarative GitOps: Define the Middleware Agent as an Argo CD Application manifest and manage its configuration through Git.

Argo CD manages synchronization between the desired configuration and resources deployed in your Kubernetes cluster.

Prerequisites#

Before installing the Middleware Kubernetes Agent, verify the following requirements:

Verify Kubernetes connectivity#

1kubectl version --client
2kubectl cluster-info
3kubectl get nodes

Check the current Kubernetes context:

1kubectl config current-context

Verify Argo CD installation#

1kubectl get pods -n argocd

If Argo CD is not installed, create the namespace and deploy its components:

1kubectl create namespace argocd

1kubectl apply -n argocd \
2  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Verify that the Argo CD pods are running:

1kubectl get pods -n argocd

To access the Argo CD UI locally, forward port 8080:

1kubectl port-forward svc/argocd-server -n argocd 8080:443

Open https://localhost:8080 in your browser.

Note: The Argo CD CLI is optional. To check whether it is installed, run argocd version.

Generate Helm values#

Before creating the Argo CD application, generate the Helm configuration containing your Middleware credentials and cluster metadata.

Run:

1MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 bash -c "$(curl -L https://install.middleware.io/scripts/generate-helm-values.sh)"

Replace the placeholders with your Middleware API key and target URL.

The command generates a generated_values.yaml file with the following structure:

1global:
2  mw:
3    apiKey: <MW_API_KEY>
4    target: https://<MW_UID>.middleware.io:443
5  clusterMetadata:
6    name: your-cluster-name # Override
7mw-autoinstrumentation:
8  enabled: false

Update clusterMetadata.name with a unique name for your Kubernetes cluster.

Security note: The generated file contains your Middleware API key. Do not commit plaintext credentials to a Git repository. For GitOps deployments, use an approved secret-management solution.

Installation#

Choose one of the following methods to deploy the Middleware Kubernetes Agent.

Method 1: Install using the Argo CD UI#

Use this method to create and manage the Middleware Agent application directly from the Argo CD dashboard.

1kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

1ignoreDifferences:
2  - group: ""
3    kind: ConfigMap
4    name: mw-deployment-otel-config
5    namespace: mw-agent-ns
6    jsonPointers:
7      - /data
8  - group: ""
9    kind: ConfigMap
10    name: mw-daemonset-otel-config
11    namespace: mw-agent-ns
12    jsonPointers:
13      - /data

Method 2: Install using declarative GitOps#

Use this method if you manage Argo CD applications through Kubernetes manifests stored in Git.

1apiVersion: argoproj.io/v1alpha1
2kind: Application
3metadata:
4  name: mw-agent
5  namespace: argocd
6spec:
7  project: default
8  source:
9    repoURL: https://helm.middleware.io
10    targetRevision: 1.2.0
11    chart: mw-kube-agent-v3
12    helm:
13      values: |
14        global:
15          mw:
16            apiKey: <MW_API_KEY>
17            target: https://<MW_UID>.middleware.io:443
18          clusterMetadata:
19            name: your-cluster-name
20        mw-autoinstrumentation:
21          enabled: false
22
23  destination:
24    server: https://kubernetes.default.svc
25    namespace: mw-agent-ns
26
27  syncPolicy:
28    syncOptions:
29      - RespectIgnoreDifferences=true
30      - CreateNamespace=true
31
32  ignoreDifferences:
33    - kind: ConfigMap
34      name: mw-deployment-otel-config
35      namespace: mw-agent-ns
36      jsonPointers:
37        - /data
38    - kind: ConfigMap
39      name: mw-daemonset-otel-config
40      namespace: mw-agent-ns
41      jsonPointers:
42        - /data

1kubectl apply -f middleware-argocd-app.yaml

1sources:
2  - repoURL: https://helm.middleware.io
3    targetRevision: 1.2.0
4    chart: mw-kube-agent-v3
5    helm:
6      valueFiles:
7        - $values/mw-agent-values.yaml
8
9  - repoURL: https://github.com/your-org/config-repo.git
10    targetRevision: HEAD
11    ref: values

Verify the installation#

After deploying the Middleware Agent, verify its status in Argo CD and Kubernetes.

Step 1: Check Argo CD application status#

Open the mw-agent application in Argo CD.

Verify that:

• Sync Status: Synced
• Health Status: Healthy

Alternatively, use the Argo CD CLI:

1argocd app get mw-agent

Step 2: Verify Kubernetes resources#

Check that the Middleware Agent pods are running:

1kubectl get pods -n mw-agent-ns

Verify that the pods report a Running status and that their containers are ready.

Step 3: Verify data collection#

Go to Infrastructure Monitoring → Kubernetes in Middleware.

Allow a few minutes for telemetry to appear after installation.

After data collection starts, you can:

• View cluster, node, pod, and container metrics.
• View collected container logs in Log Monitoring.
• Create alerts for Kubernetes infrastructure metrics.

Upgrade the Agent#

You can upgrade the Middleware Agent by changing the Helm chart version in Argo CD.

Using the Argo CD UI#

1. Open the mw-agent application in Argo CD.
2. Click DETAILS → EDIT.
3. Update Target Revision to the desired Helm chart version.
4. Click SAVE.
5. Click SYNC to apply the updated configuration.

Using declarative GitOps#

Update targetRevision in your Argo CD Application manifest:

source:

1repoURL: https://helm.middleware.io
2  targetRevision: <NEW_CHART_VERSION>
3  chart: mw-kube-agent-v3

Commit the change to your Git repository and synchronize the application.

Troubleshooting#

Argo CD application is not syncing#

If the Middleware application remains OutOfSync or fails to synchronize:

• Verify that Argo CD can access https://helm.middleware.io.
• Check that the specified Helm chart version exists.
• Verify that Argo CD has the required permissions to create resources in mw-agent-ns.
• Review the application events in the Argo CD UI.

Agent pods are not running#

If the Middleware Agent pods fail to start:

• Check the pod status and Kubernetes events.
• Verify that the namespace has sufficient CPU and memory resources.
• Review the Agent logs:

1kubectl logs -n mw-agent-ns -l app.kubernetes.io/name=mw-kube-agent-v3

No Kubernetes metrics in Middleware#

If the Agent is running but metrics do not appear:

• Verify that the cluster can establish outbound connections to your Middleware target URL.
• Confirm that the Middleware API key and target URL are configured correctly.
• Check the Agent logs for connection or authentication errors.
• Ensure only one Middleware Infrastructure Agent is running per node.

Continuous OutOfSync status#

Middleware dynamically updates the following ConfigMaps:

• mw-deployment-otel-config
• mw-daemonset-otel-config

Verify that the ignoreDifferences configuration is applied correctly and that Respect Ignore Differences is enabled.

This prevents Argo CD from repeatedly attempting to overwrite the Agent-managed ConfigMap data.

Uninstall#

Remove the Middleware Agent using the same Argo CD management method used for deployment.

Using the Argo CD UI#

1. Open the mw-agent application.
2. Click DELETE.
3. Select the appropriate resource deletion policy.
4. Confirm the deletion.

Using the Argo CD CLI#

1argocd app delete mw-agent

Confirm the deletion when prompted.

Using kubectl#

For declarative installations, delete the Argo CD Application resource:

1kubectl delete application mw-agent -n argocd

Note: Deleting an Argo CD Application does not always remove its managed Kubernetes resources. Resource cleanup depends on the application's deletion finalizer and propagation policy. Verify that the Middleware Agent resources have been removed.

If the Application is managed by GitOps, also remove its manifest from the source repository to prevent it from being recreated.