Install the Kompass Insights agent - Azure AKS

Prev Next

This topic describes how to install the Kompass Insights agent on an Azure AKS cluster. After installing, the cluster and the agent are “connected.”

The Kompass Insights agent (“agent”) provides visibility into your K8s cluster and workload costs, scaling performance, usage, and pattern history. With agent visibility, Kompass can make recommendations for your environment.

The agent requires read-only access to the services defined in the Insights agent YAML.

VictoriaMetrics settings

Kompass Insights uses VictoriaMetrics to store and query cluster metrics.

VictoriaMetrics can run in Single-Pod mode or Cluster mode, which determines the availability, resilience, and scalability of metrics storage and queries.

  • Single-Pod mode (default): runs a standalone VictoriaMetrics instance. This mode is suitable for small or non-production environments and provides no redundancy if the Pod becomes unavailable.

  • Cluster mode: runs a multi-component VictoriaMetrics cluster (vmselect, vminsert, and vmstorage) with multiple replicas. This mode provides higher availability, fault tolerance, and scalability.

Cluster mode is recommended for:

  • production clusters

  • large clusters (for example, 100+ nodes or 1,000+ Pods)

  • high-churn environments, where approximately 10% or more of workloads are Jobs, CI/CD pipelines, or other short-lived Pods

  • KEDA-heavy environments, where KEDA manages at least 10% of workloads

You select the deployment mode by editing values.yaml, as described in the next section.

How a cluster is connected to the agent

To connect a cluster, use the installation wizard. The wizard has the following steps:

  1. Permissions: provision Azure resources via Terraform

  2. Prepare values.yaml: configure the Helm chart

  3. Install Helm chart on cluster: deploy the agent

To see the details of how the wizard works, click here.

To connect to the agent, you install a Helm chart based on a values.yaml file.

The Connect cluster wizard will prepare values.yaml as it guides you through the following steps:

  1. Use the Connect cluster wizard to create unique Terraform code to generate the Managed Identity’s Client ID. (You can see the Terraform template at https://github.com/zesty-co/terraform-kompass-insights-azure)
    The client ID is needed to enable authentication between Kompass and Azure.
    You can find the Subscription ID, Resource Group, and Cluster name in Azure.
    The Resource group and Cluster name will be embedded inside the resultant code.
    When you run the code, it outputs the Managed Identity Client ID.

  2. Define specific values for the values.yaml file:

    • cert-manager (Mandatory): Is it installed or not?
      If it’s not installed, Kompass will install it during the Helm chart installation.

    • PVC storage class (Mandatory): The name of the PVC StorageClass.
      The agent is installed with a PVC, so this is required.
      If you don’t know the name, you can discover it by running this command:
      Kubectl get storageclass

    • Client ID: the ID for which the Azure token is being requested.
      This value is created by running the Terraform code.

    • You can see the full list of YAML parameters here.

  3. Download values.yaml to your terminal.
    At this point, you can make further modifications to values.yaml.

    • For best performance with Kompass, we recommend modifying disk usage parameters for Kompass Insights PVC size and VictoriaMetrics server volume size.

      For more information, click here.

      Based on our experience, setting these disk usage parameters based on workloads in the cluster yields the best performance:

      Parameter

      Workloads and value

      Code

      Kompass Insights PVC size

      • Up to 1,000 workloads = 1Gi

      • From 1,000 - 5,000 workloads = 3Gi

      • From 5,000 - 10,000 workloads = 10Gi

      • Above 10,000 workloads = 100Gi

      kompass-insights:
  persistence:
    spec:
      resources:
        requests:
          storage: “1Gi”

      VictoriaMetrics server volume size

      • Up to 1,000 workloads = 30Gi

      • From 1,000 - 10,000 workloads = 60Gi

      • Above 10,000 workloads = 100Gi

      victoriaMetrics:
  server:
    persistentVolume:
      size: "30Gi"

    • Set the VictoriaMetrics deployment mode in values.yaml:

      To enable this mode

      Set these values

      Single mode

      victoriaMetrics:

       enabled: true

      victoriaMetricsCluster:

       enabled: false

      victoriaMetricsAuth:

       enabled: true

       useSingle: true

      Cluster mode

      victoriaMetrics:

       enabled: false

      victoriaMetricsCluster:

       enabled: true

      victoriaMetricsAuth:

       enabled: true

       useSingle: false

      Ensure the selected mode matches your environment’s availability and scalability requirements before running the Helm installation. For more information, see VictoriaMetrics settings.

    • If you edit victoriaMetrics parameters, ensure that the values of these parameters are equal: victoriaMetricsNameOverride, victoriaMetricsRemoteUrl, and
victoriaMetricsRemoteWriteUrl.

    • You can control the nodes on which the Insights agent runs using the nodeSelector and tolerations configurations, here.

  4. Install the agent Helm chart, using the definitions in values.yaml.
    You must be connected to the same cluster that you are connecting to the agent.

  5. Tell Kompass that you’re done!

Prerequisites

To install the Insights agent on an Azure cluster:

  1. Permissions:

    1. Run the Connect cluster wizard to create Terraform code:

      1. From the Automations > Kompass > Clusters page, click Connect clusters.

      2. Choose Azure from the cloud provider list.
        The Connect cluster wizard begins, showing the Permissions tab.

      3. Enter these Azure details:

        • Subscription ID: your Azure subscription GUID

        • Resource group: resource group that contains the AKS cluster

        • Cluster name: name of the AKS cluster
          As you type, the Terraform code is updated with the cluster name and resource group.

    2. Run Terraform to generate the client ID:

      1. Create a dedicated directory for the Terraform configuration:
        mkdir -p ~/kompass-insights-tf && cd ~/kompass-insights-tf

      2. Copy the Terraform code from the wizard and save it as main.tf in the new directory.

        To see what the Terraform snippet does, click here.

        Code

        Description

        provider "azurerm" / provider "azuread"

        Authenticates Terraform to your Azure subscription and Azure AD tenant.

        data "azurerm_kubernetes_cluster"

        Reads the existing AKS cluster to extract the oidc_issuer_url, which is needed for Workload Identity.

        data "azurerm_resource_group"

        Reads the resource group to obtain its location and name for the managed identity.

        module "kompass_insights"

        Calls the zesty-co/insights-azure/kompass Terraform module. It creates a User Assigned Managed Identity, a Federated Identity Credential (binds the identity to the AKS OIDC issuer), a Custom Role Definition with minimal read permissions, and a Role Assignment.

        output "managed_identity_client_id"

        Outputs the Client ID of the created Managed Identity, which is needed in the next step

      3. Apply the Terraform configuration:
        terraform init
        terraform plan
        terraform apply

      4. Confirm to Terraform.

    3. Copy the client ID for the next step.
      If the client ID is not displayed, run this:

      terraform output managed_identity_client_id

    4. From the Connect cluster wizard, click Next.
      The Prepare values.yaml tab is shown.

  2. Prepare values.yaml:
    (For more details about these parameters, see How a cluster is connected to the agent.)

    1. Is cert-manager installed in the cluster?

      If cert-manager (https://cert-manager.io/) is running in the cluster, select Yes.

      If not, select No; Kompass will install it for you.

      If you don’t know whether cert-manager is installed, click here.

      To see if cert-manager is installed, run this:

      kubectl get pods -A | grep cert-manager

      If the command returns running pods, select Yes; otherwise leave the default No.

    2. PVC storage class: The agent is installed with a PVC, so a storage class is required.

      To see available the current storage classes in your cluster, run kubectl get storageclass

      On AKS, the typical choice is - default – Azure Disk (Standard HDD)

      Do not use azurefile-* classes — the agent requires a block-storage ReadWriteOnce) volume.

    3. Client ID: Paste the value of managed_identity_client_id from the Terraform output.

    4. Click Next.
      The Install Helm chart on cluster tab is shown.
      There are 2 Bash commands here:

  3. Install Helm chart on the cluster:

    1. Click the values.yaml icon and paste the code to the terminal.

    2. Run the code to download values.yaml.

      After you download, you can use a file editor to edit values in the file, as described in the dropdown details of How a cluster is connected to the agent.

      1. Configure the victoriaMetrics mode (default: Single mode).

      2. (Recommended) Edit the values of the Kompass Insights PVC size and the VictoriaMetrics server volume size.

    3. Click the install command icon and paste the code to the terminal.

      IMPORTANT

      Before installing, ensure that you are connected to the correct cluster and that the path to Helm is correct.

    4. Run the code to install the agent Helm chart.

    5. When the Helm chart installation is complete, click Helm install is done.
      A confirmation message is displayed.

  4. Verify the deployment by running the following command:
    kubectl get pods -n zesty-system
    All Pods should reach Running status within a few minutes.

Once the Insights agent is installed, Kompass starts collecting cluster data:

For the Pod rightsizing solution, it can take up to 24 hours before recommendations are displayed.

© 2026 Zesty. All Rights Reserved

info@zesty.co