---
title: "Install in an online embedded cluster"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/install-embedded-cluster-online/index.html"
---
This procedure is for Application on VM (Embedded Cluster). For all deployments, see [Deployment options](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/deployment-options/index.html#application-on-vm).

## Prerequisites 


**Important**


ITRS Analytics versions prior to 2.15.4 will fail to deploy on online installations due to `bitnami/kubectl` image deprecation. Air-gapped deployments are unaffected. To prevent deployment failures, you must upgrade to version 2.15.4 or later. This release includes updates that replace `bitnami/kubectl` with `chainguard/kubectl`. 

For more information, refer to this [documentation](https://docs.itrsgroup.com/docs/itrs-analytics/latest/faqs/bitnami-kubectl-image-migration/index.html).



Before installing ITRS Analytics, ensure that all the prerequisites are met in the environment where you will deploy.


**Note**


Starting with ITRS Analytics 2.11.x, multi-node clusters are supported for Embedded Cluster. For more information, see [Multi-node clusters with Embedded Cluster online](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/configure-multi-node-clusters-embedded-online/index.html).



-  Follow these [additional preflight](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/resource-hw-requirements/index.html#additional-preflight-checks-before-embedded-cluster-installation) checks to validate system readiness before installing the ITRS Analytics Embedded Cluster.

-  Verify that your environment satisfies all prerequisites outlined in the [System requirements for Embedded Cluster installation](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/embedded-cluster-installation-setup/index.html) prior to installation.

-  Check that [resource and hardware requirements](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/resource-hw-requirements/index.html) are met.

-  Note the host name of the server, which will be used for accessing ITRS Analytics from outside the Kubernetes cluster.

-  Check that cluster permissions are set. You need to use `sudo` to [access the cluster](https://docs.replicated.com/vendor/embedded-overview#access-the-cluster).

-  For Medium and Large-sized deployments, you must assign the appropriate labels and taints to nodes designated for ClickHouse to ensure proper scheduling and workload isolation.
  
  -  For `label` command:
    ```
    kubectl label nodes <node_name> instancegroup=clickhouse-nodes;
    ```

  -  For `taint` command:
    ```
    kubectl taint nodes <node_name> dedicated=clickhouse-nodes:NoSchedule;
    ```

## Start installation

The installation bundle (`.tgz`) for the embedded cluster option includes the installer, license file, and the admin console and related tools for an airgap environment. To set up this option, you will need to deploy the bundle on the server where you want to run ITRS Analytics.


**Note**


When using an embedded cluster, the PVCs are stored in the `/var/lib/embedded-cluster/openebs/local` directory, which does not reserve a specific amount of space upfront. The folder will initially use close to no space until files are actually added even when there is allocated storage space.

Make sure that the total volume of your PVCs will fit within this directory. For example, if you have PVCs for ClickHouse metrics (400 GiB), ClickHouse logs (200 GiB), and Kafka (100 GiB), the directory needs to be at least 700 GiB.




**Tip**


When installing on an embedded cluster with limited space, you can [relocate the data directory by passing the `--data-dir` flag](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/resource-hw-requirements/index.html#embedded-cluster-installs).



To install ITRS Analytics in an online embedded cluster, do the following:

-  Download the installation bundle. Run:

  ```
  curl -f [download URL]/stable -H "Authorization: [authorization-key]" -o itrs-analytics-stable.tgz
  ```

-  Download the security tools preflight spec on the target host. Run:

  ```
  curl -LO https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/refs/heads/main/host/security-tools-preflights.yaml
  ```

-  Extract the installation bundle. Run: 

  ```
  tar -zxvf itrs-analytics-stable.tgz
  ```

-  Run this command to perform preflight checks. This step helps verify that your system and cluster meet the necessary requirements before proceeding with the installation.

  ```
  sudo ./itrs-analytics install run-preflights --license license.yaml
  ```

-  Run the security tools preflight check to detect antivirus or endpoint protection software that might interfere with the installation.

  ```
  sudo /var/lib/embedded-cluster/bin/kubectl-preflight security-tools-preflights.yaml --interactive=false
  ```

  If you use a custom data directory with `--data-dir`, replace `/var/lib/embedded-cluster` with that path.

-  Install ITRS Analytics. Run:

  ```
  sudo ./itrs-analytics install --license license.yaml
  ```

-  Once the installation is finished, go to the URL from the installation output to access the admin console. If you see a security warning in the browser, click **Advanced** and proceed to the URL.

-  When prompted, choose whether to use a self-signed certificate or your own custom certificate. If you choose to upload your own, you will need to provide a PEM file and a corresponding private TLS key.

-  Optionally, supply a hostname for accessing the ITRS Analytics UI. Click **Continue**.

## Log in to the Admin Console

-  Log in to the admin console using the password you set in the command output during installation.


**Tip**


For a visual walkthrough of the installation process, please watch the demo. If you prefer, you can follow the detailed instructions below.



https://app.storylane.io/demo/tzssrt2rszsl

## Configure the cluster (optional)

-  On the **Nodes** screen, optionally add nodes before deploying ITRS Analytics and then click **Continue**. To create a multi-node cluster with Embedded Cluster, see [Multi-node clusters with Embedded Cluster online](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/configure-multi-node-clusters-embedded-online/index.html).

## Configure ITRS Analytics

### Prerequisites

-  On the **Configure ITRS Analytics** screen, set your options and then click **Continue**.

-  On the **Prerequisites** section, verify that the required packages have been installed.

### Cluster Settings
 
-  On the **Cluster Settings** section, select the appropriate cluster size based on your needs. For more information, see [Sizing guidelines](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/resource-hw-requirements/index.html).

### Hostnames

-  On the **Host names** section, specify the paths to the apps and ingestion host names you will use.  

  
**Note**


Starting in ITRS Analytics version 2.12.0+2, you are required to enter a fully qualified domain name (FQDN) for both the **Apps external host name** and **Ingestion external host name** where the application will be accessible.



### ITRS Analytics Apps

-  Navigate to the **ITRS Analytics Apps** section, where you’ll find all required and optional production apps, as well as beta apps. From this list, select the apps you want to install.

  
**Note**


Starting with ITRS Analytics version 2.12.0+6, the option to select between production and beta apps or only production apps during setup up has been removed. For more details, see [Changes to App Installation Type selection](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/itrs-analytics-upgrade-notes/index.html#changes-to-app-installation-type-selection).



   The following apps are listed as **Required Apps** in the KOTS Admin Console.

  | Required apps | Description |
  |---|---|
  | Web Console | [ITRS Analytics Web Console](https://docs.itrsgroup.com/docs/itrs-analytics/app/webconsole/current/user-guide/prerequisites/index.html) lets you easily track critical monitoring data of your always-on enterprise from a web browser. |
  | Query Service | [ITRS Analytics Query Service app](https://docs.itrsgroup.com/docs/itrs-analytics/app/query-service/current/user-guide/app-query-service/index.html) provides a materialized view of the objects for entities stored in the ITRS Analytics Platform. It also exposes additional query capabilities that are not directly supported by the ITRS Analytics Platform.
  | Entity Viewer | [ITRS Analytics Entity Viewer app](https://docs.itrsgroup.com/docs/itrs-analytics/app/entities/current/user-guide/about/index.html) provides a web-based interface for real-time monitoring, investigation, and analysis of entities tracked in ITRS Analytics.
  | Commands | [ITRS Analytics Commands app](https://docs.itrsgroup.com/docs/itrs-analytics/app/commands/current/user-guide/commands/index.html) enables additional command functions in the Entity Viewer app.
  | Public API | [ITRS Analytics Public API](https://docs.itrsgroup.com/docs/itrs-analytics/app/api-gateway/current/user-guide/api-gateway/index.html) provides a publicly accessible REST API to interact with the ITRS Analytics Platform. |
  | IAM | [ITRS Analytics IAM app](https://docs.itrsgroup.com/docs/itrs-analytics/app/iam/current/user-guide/iam-configuration/index.html) sets up login and access control in ITRS Analytics, and publishes daily active user counts that you can view in the IAM app, in Entity Viewer, or on a dashboard. Beginning with installation package 2.18.13+p2.18.10, the IAM app is a required app and is selected by default. Upgrading to this version includes IAM in the app selection automatically. |

   The **Optional Apps** section includes recommended apps, as well as other apps you can install depending on your business requirements.  

   **Beta apps** are pre-release versions that are still in development and testing. They may offer new features that are not yet fully validated, which can introduce operational risks. Use beta apps only in non-production environments to avoid impacting business operations.

### Credentials

-  The **Credentials** section contains default login information for different user and admin levels, intended for informational purposes.

### Storage Settings

-  In the **Storage Settings** section, select **Show Storage Class Configuration** to display storage class options for Kafka, Kafka Controller, etcd, and ClickHouse Traces, Metrics, Logs, Keeper, and Platform.
  Note that modifying these settings may require advanced configuration. When configuring storage classes, make sure upgrades are supported, since these are performed independently from the ITRS Analytics installation.

-  In the **Disk Allocations** section, select **Show Disk Allocations Configuration** to display disk size options for Kafka and ClickHouse Traces, Metrics, Logs, Keeper, and Platform.

### Advanced Settings

-  On the **Advanced Settings** section, select **Show Advanced Configuration** to view advanced configuration options.

-  Under **Uptrends Configuration**, you can toggle **Enable Uptrends** to activate the Uptrends Real User Monitoring (RUM) integration for ITRS Analytics. 

  
**Note**


You can integrate Uptrends’ Real User Monitoring (RUM) with ITRS Analytics to gain detailed insights into how users interact with the platform in real-world conditions. You can monitor key pages and apps, such as Entity Viewer and Dynamic Thresholds, to better understand user experience, performance, and potential issues.

To get started with Uptrends RUM, follow the [Uptrends documentation](https://www.uptrends.com/support/kb/rum/setup), and use this [guide](https://www.uptrends.com/support/kb/rum/understanding-real-user-monitoring#what-does-a-rum-script-look-like) to find the Site ID (SID).



  Enabling this option displays the **Uptrends SID** field, where you must enter the SID or Site ID to complete the monitoring setup.
  
-  Under **Service Mesh**, select to install `trust-manager` for Linkerd integration (only available if `linkerd` installation is enabled).

-  Under **TLS Certificates**, you can choose between using self-signed certificates or deploying your own custom, non-self-signed certificates.
  - If you keep the default self-signed option, ITRS Analytics manages the certificates for you.
  - To use non-self-signed TLS certificates for ITRS Analytics endpoints, select **ITRS Analytics: custom certificates**. This displays the ITRS Analytics certificate and key fields where you can upload a PEM certificate file and the corresponding private TLS key.
  - If `linkerd` is enabled and you want to use custom certificates for the service mesh, select **Linkerd: custom linkerd certificates**. You must provide a PEM file and a corresponding private TLS key for the Linkerd certificates.

-  Under **Ingress Annotations**, you must specify custom annotations for ingress resources when using an alternative ingress controller. An ingress controller is mandatory for all deployments. Configuring annotations does not eliminate this requirement. 

- When to configure ingress annotations:
  - If you are using the default bundled `ingress-nginx` controller, no custom annotations are typically required.
  - Custom annotations are needed when you install and use a different ingress controller (such as HAProxy, AWS ALB, or a manually configured `ingress-nginx` with specific requirements).
  - Annotations configure how your chosen ingress controller handles traffic routing and cannot be used to bypass the requirement for an ingress controller.
  
- Example scenarios requiring custom annotations:
  - Using an internal Layer 7 load balancer with `ingress-nginx` configured as ClusterIP service with network endpoint groups (NEGs).
  - Integrating with cloud-specific load balancers (for example, AWS ALB, and GCP L7 LB).
  - Custom `ingress-nginx` installations with non-standard configurations.

-  Under **Preflight and Support Bundle Settings**, enable the following options as needed:
  - [Run Disk I/O Performance Test](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/preflight-checks/index.html#preflight-checks-for-disk-io-performance)
  - [Run Node Sysctl Checks](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/preflight-checks/index.html#preflight-check-for-inotify-limits)
  - [Include Disk I/O Test for Support Bundle](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/preflight-checks/index.html#support-bundle)

-  Under **Backup and Restore**, select **Enable IAX backup and restore** to activate backup and restore support for ITRS Analytics using Velero.

-  Under **Zone Spread**, enable **Enforce Zone Spread** only when the deployment spans at least three availability zones and requires zone-failure protection for production high availability. Leave this setting disabled for proof-of-value and other sub-3-AZ environments. This option is available starting with ITRS Analytics 2.17.12. For more information, see [Preflight check for Enforce Zone Spread setting](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/preflight-checks/index.html#preflight-check-for-enforce-zone-spread-setting).

-  Under **ClickHouse Workload Scheduling**, enable **Enforce ClickHouse Node Selector** to ensure ClickHouse workloads run only on nodes matching the defined selector. Beginning with ITRS Analytics 2.18.1 on Embedded Cluster, this option is permanently disabled and is no longer available for selection.

  
**Warning**


Before you start the upgrade on Embedded Cluster, explicitly disable the ClickHouse node selectors. In the KOTS Admin Console, disable **Enforce ClickHouse Node Selector**. See [Review storage driver node affinity](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/upgrading-to-version-2-18-0/index.html#review-storage-driver-node-affinity).



-  Under **Security Contexts**, you can configure security contexts for both pods and containers across all platform and app charts. This provides a centralized way to enforce security policies consistently in the KOTS Admin Console. For more information, see [Configure security contexts](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/security/security-contexts/index.html#configuration-reference).
  - The **Pod Security Context** defines security settings at the pod level and applies to all ITRS Analytics Platform and app pods. It is configured in YAML format, and the settings you define here are automatically merged into the `securityContext.pod` field for all charts. 
  - The **Container Security Context** defines security settings at the container level and applies to all ITRS Analytics Platform and app containers. It is configured in YAML format, and the settings you define here are automatically merged into the `securityContext.container` field for all charts.

-  Under **Helm Install/Upgrade Options**, you can configure the **ITRS Analytics Helm Chart Timeout** setting to be used during installation or [upgrade operations](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/itrs-analytics-upgrade-notes/index.html#helm-chart-timeout-adjustment-required).

-  Under **Status Informer Overrides**, leave **Audit ingestion**, **Logs ingestion**, and **Traces ingestion** selected unless that ingestion is intentionally disabled. These options are available starting with ITRS Analytics 2.18.13. Clearing a toggle removes those workloads from application status, so a disabled ingestion pipeline does not cause the KOTS Admin Console to show the application as unavailable. The ingestion pipeline stays in its current state. For more information, see [Status informer overrides](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/itrs-analytics-upgrade-notes/index.html#status-informer-overrides).

-  In the **Helm Chart Values Override** (formerly *Parameters Override*), input your desired configuration values to override the default Helm chart settings and then save your configuration. Starting with ITRS Analytics version 2.18.4, these overrides are merged at the chart values root instead of being wrapped under a static key matching the chart name.

  Use the chart name as the top-level key in the override YAML, then nest values exactly as they appear in the chart's default values. To confirm the expected key hierarchy for a chart, run `helm show values` against that chart and use the top-level key from the output as the nested alias in your override.

  
**Warning**


The previous format is no longer supported. Existing overrides that use the old structure can be silently ignored after installation or upgrade. For migration guidance and examples, see [Helm Chart Values Override format changed](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/itrs-analytics-upgrade-notes/index.html#helm-chart-values-override-format-changed).


  
## Preflight checks and deploy

-  Once you have verified that your environment has met the prerequisites during the preflight checks, click **Deploy**. Once the status of all resources are confirmed ready, the install is completed.


