Skip to main content

Breeze Installation on Kubernetes (DaemonSet)

Install Cloudaware Breeze Agent as a Kubernetes DaemonSet so one Breeze Agent instance runs on each eligible Linux node. The integration is for Linux only.

Use Case​

Use this setup when you need to deploy Breeze Agent across eligible Linux nodes in an Amazon EKS, Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), or a self-managed cluster to collect host OS data from each node.

Before You Begin​

Make sure that:

How It Works​

The DaemonSet deploys a pod on each Kubernetes node with two components:

  1. Init container - Runs once per pod startup to install Breeze agent on the host:

    • Mounts host directories: /opt, /etc, /var/log, and /proc
    • Copies agent files from the container to /opt/breeze-agent on the host
    • Configures systemd timer (preferred) or cron job to run the agent every 15 minutes
    • Detects AL2023 hosts and installs required dependencies (libxcrypt-compat)
    • Uses nsenter to interact with the host's systemd

  2. Logger container - Runs continuously to stream agent logs:

    • Tails /var/log/breeze-agent.log from the host
    • Outputs logs to stdout for Kubernetes log collection

The agent runs natively on the host OS, not as a containerized application. The DaemonSet ensures every node in the cluster has the agent installed and keeps logs accessible via kubectl logs.

High-level Setup Flow​

  1. Download the Linux agent archive from Cloudaware.
  2. Prepare the Breeze Agent package and Kubernetes deployment files.
  3. Build and publish the Breeze DaemonSet image to a private container registry.
  4. Configure the DaemonSet manifest for the target cluster.
  5. Deploy Breeze Agent to Kubernetes.
  6. Verify agent deployment on the target nodes and check their Breeze data in Cloudaware.

Installation Steps​

Download the Breeze Agent Installer​

  1. In Cloudaware, go to Admin Console.
  2. Find Breeze in DevOps Integrations. Click CONFIGURED.
  3. Download the Linux agent archive (the archive name uses the following format: breeze-agent.<breeze_key>.<breeze_version>.<build_arch>.linux.tgz).

Create a Docker image​

  1. Unpack the Breeze Agent installer to the current directory:

    tar xvzf breeze-agent.<breeze_key>.0.x86_64.linux.tgz

    Where:

    • <breeze_key> is a placeholder for the customer-specific ID in the installer file name.
    • 0 is a Breeze version example.
    • x86_64 is a architecture build example.

    Replace breeze-agent.<breeze_key>.0.x86_64.linux.tgz with the name of the downloaded installer file.

  2. Remove TLS certificates from the unpacked directory to avoid baking secrets into the image:

    rm -f breeze-agent/etc/ssl/breeze-agent.crt
    rm -f breeze-agent/etc/ssl/breeze-agent.key
    note

    TLS certificates will be mounted from Kubernetes secrets at runtime (see Run DaemonSet section below).

    Alternative: Baking certificates into the image

    If you prefer to include TLS certificates in the image (not recommended for security):

    • Skip step 2 to keep certificates in the unpacked directory.
    • Build and push the image.
    • Comment out the TLS-related volumes and volumeMounts sections in breeze-agent-host-installer.yaml.

  3. Build the Docker image:

    docker build -t <registry_hostname>/breeze-agent:<tag> .

    Where:

    • Replace <registry_hostname> and <tag> with your actual registry hostname and desired image tag, respectively.
    • The example <registry_hostname> format for EKS: <aws_account_id>.dkr.ecr.us-east-1.amazonaws.com.

  4. Push the image to your private Docker container registry:

    docker push <registry_hostname>/breeze-agent:<tag>

    Where:

    • Replace <registry_hostname> and <tag> with your actual registry hostname and desired image tag, respectively.
    • The example <registry_hostname> format for EKS: <aws_account_id>.dkr.ecr.us-east-1.amazonaws.com.

Run DaemonSet​

  1. Create a Kubernetes secret with your TLS certificates:

    kubectl create secret tls breeze-tls-secret \
      --cert=path/to/breeze-agent.crt \
      --key=path/to/breeze-agent.key

  2. Update the image reference in breeze-agent-host-installer.yaml if using a different registry or tag.

  3. Create the DaemonSet:

    kubectl create -f breeze-agent-host-installer.yaml

Verify Deployment​

  1. Check DaemonSet status:

    kubectl get daemonset breeze-agent-ds

    DaemonSet status should show DESIRED = CURRENT = READY.

  2. View logs from a specific node:

    kubectl logs -l app=breeze-agent -c logger

    Logs should show periodic agent runs without errors.

  3. Verify agent is running on a node (SSH to node)

    systemctl status breeze-agent.service

Notes​

In Cloudaware, verify that the target nodes appear with data collected by Breeze.

Uninstalling​

To remove the DaemonSet:

kubectl delete -f breeze-agent-host-installer.yaml
note

This only removes the DaemonSet pods. The agent remains installed on the host nodes. To fully uninstall, SSH to each node and manually remove /opt/breeze-agent and the systemd timer or cron job.

For a DaemonSet example with sample manifests and registry settings, see the Kubernetes DaemonSet playbook.

On this page