---
title: "Kubernetes Agent with Argo CD"
description: "Deploy the Middleware Kubernetes Agent via ArgoCD for automated installation and efficient cluster monitoring."
section: "Agent Installation"
breadcrumb: "Containers > Kubernetes > Argo CD"
canonical: "https://docs.middleware.io/get-started/agent/kubernetes/kubernetes-argocd"
---
# 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

```bash
kubectl version --client
kubectl cluster-info
kubectl get nodes
```

Check the current Kubernetes context:

```bash
kubectl config current-context
```

### Verify Argo CD installation

```bash
kubectl get pods -n argocd
```

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

```bash
kubectl create namespace argocd
```

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

Verify that the Argo CD pods are running:

```bash
kubectl get pods -n argocd
```

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

```bash
kubectl 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:

```bash
MW_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:

```yml
global:
  mw:
    apiKey: <MW_API_KEY>
    target: https://<MW_UID>.middleware.io:443
  clusterMetadata:
    name: your-cluster-name # Override
mw-autoinstrumentation:
  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.

#### 1 Log in to Argo CD

Open the Argo CD dashboard:

`https://localhost:8080`

For a new installation, retrieve the initial admin password:

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

Log in with the username `admin` and the retrieved password.

Click + **New App** to create an application.

#### 2 Configure the application

In the General section, enter:

#### 3 Configure the source and destination

In the Source section, configure the Middleware Helm chart:

In the Destination section:

#### 4 Configure Helm values

In the Helm configuration section, paste the contents of `generated_values.yaml` into the **VALUES** field.

Make sure you use **VALUES**, not **VALUES FILES**.

Verify that the API key, target URL, and cluster name are configured correctly.

#### 5 Configure Ignore Differences

Middleware updates certain OpenTelemetry ConfigMaps dynamically. Configure Argo CD to ignore changes to their data fields to prevent continuous OutOfSync status.

Click **EDIT AS YAML** and add the following configuration:

```yml
ignoreDifferences:
  - group: ""
    kind: ConfigMap
    name: mw-deployment-otel-config
    namespace: mw-agent-ns
    jsonPointers:
      - /data
  - group: ""
    kind: ConfigMap
    name: mw-daemonset-otel-config
    namespace: mw-agent-ns
    jsonPointers:
      - /data
```

#### 6 Deploy the Middleware Agent

1. Click **CREATE** to create the Argo CD application.
2. Open the newly created `mw-agent` application.
3. Click **SYNC**.
4. Select **Synchronize** to deploy the resources.

Wait for Argo CD to complete synchronization.

### Method 2: Install using declarative GitOps

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

#### 1 Create the Argo CD Application manifest

Create a file named `middleware-argocd-app.yaml`.

Add the following configuration:

```yml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mw-agent
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://helm.middleware.io
    targetRevision: 1.2.0
    chart: mw-kube-agent-v3
    helm:
      values: |
        global:
          mw:
            apiKey: <MW_API_KEY>
            target: https://<MW_UID>.middleware.io:443
          clusterMetadata:
            name: your-cluster-name
        mw-autoinstrumentation:
          enabled: false

  destination:
    server: https://kubernetes.default.svc
    namespace: mw-agent-ns

  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true
      - CreateNamespace=true

  ignoreDifferences:
    - kind: ConfigMap
      name: mw-deployment-otel-config
      namespace: mw-agent-ns
      jsonPointers:
        - /data
    - kind: ConfigMap
      name: mw-daemonset-otel-config
      namespace: mw-agent-ns
      jsonPointers:
        - /data
```

Replace the placeholders with your Middleware account details.

Set `targetRevision` to the Helm chart version you want to deploy. The example uses `1.2.0`; verify that this version is available before applying the configuration.

**Note**: For production GitOps workflows, avoid storing MW_API_KEY in plaintext. Use a Kubernetes Secret or a GitOps-compatible secret-management solution.

#### 2 Apply the configuration

Deploy the Argo CD Application:

```bash
kubectl apply -f middleware-argocd-app.yaml
```

Open the Argo CD dashboard and synchronize the mw-agent application.

#### Optional: Use an external Helm values file

If you manage Helm values in a separate Git repository, configure Argo CD to reference that repository.

Replace `source` with `sources` in your Application manifest:

```yml
sources:
  - repoURL: https://helm.middleware.io
    targetRevision: 1.2.0
    chart: mw-kube-agent-v3
    helm:
      valueFiles:
        - $values/mw-agent-values.yaml

  - repoURL: https://github.com/your-org/config-repo.git
    targetRevision: HEAD
    ref: values
```

This allows you to maintain the Middleware Agent configuration separately from the Helm chart.

## 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:

```bash
argocd app get mw-agent
```

### Step 2: Verify Kubernetes resources

Check that the Middleware Agent pods are running:

```bash
kubectl 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](https://app.middleware.io/logs).
- Create [alerts](/features/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:

```bash
  repoURL: https://helm.middleware.io
  targetRevision: <NEW_CHART_VERSION>
  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:

```bash
kubectl 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

```bash
argocd app delete mw-agent
```

Confirm the deletion when prompted.

### Using kubectl

For declarative installations, delete the Argo CD Application resource:

```bash
kubectl 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.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us page or join our Slack channel.