---
title: "Install in an online Bring-Your-Own (BYO) cluster with KOTS"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/install-via-kots-online/index.html"
---
This procedure is for a client-managed cluster (Bring-Your-Own cluster). For all deployments, see [Deployment options](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/deployment-options/index.html#client-managed-cluster).

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

-  Ensure your Kubernetes version is compatible with the ITRS Analytics Platform version you are installing. For full details on compatibility, please refer to the  [Kubernetes clusters compatibility](https://docs.itrsgroup.com/docs/all/itrs-analytics/compat-matrix/index.html#kubernetes-clusters-compatibility) section.

-  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. 

-  Make sure that a load balancer is configured for your cluster.

-  Ensure cluster permissions are set. By default, KOTS uses [cluster-scoped RBAC](https://docs.replicated.com/enterprise/installing-general-requirements#cluster-scoped), which is used in BYO online environments. Alternatively, you can choose to grant [namespace-scoped RBAC permissions to KOTS](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/minimal-rbac/index.html).

-  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;
    ```

### Installing ITRS Analytics on strict PSS clusters

Clusters that enforce the highest level of Pod Security Standards (PSS) impose strict security restrictions on deployed workloads. Due to these limitations, the standard ITRS Analytics installation procedures cannot be used.

When deploying ITRS Analytics in such environments, you must manually install and manage the following prerequisites before proceeding with the installation:

- `cert-manager` — required for issuing and managing TLS certificates.
- `ingress-nginx` — provides the ingress controller for routing external traffic.
- `linkerd` (optional) — required only if mutual TLS (mTLS) is enabled in the cluster.

Before deploying ITRS Analytics, make sure all prerequisites are installed and running correctly. Clusters enforcing strict PSS may limit certain capabilities or security contexts, so verify that each prerequisite complies with these standards.


**Warning**


ITRS Analytics does not support upgrading a non-PSS-restricted (less secure) cluster to a PSS-restricted (more secure) cluster.

For ITRS Analytics 2.17.x, deployments targeting clusters that enforce the highest level of Pod Security Standards (PSS) must be installed as a new deployment, with all prerequisites managed manually.



## Start installation

If you opt to install ITRS Analytics in an existing cluster, you should choose the **Bring-Your-Own (BYO)** option. You can either download `kotscli` from the Customer's Download Portal or continue with the next installation steps.

Installing ITRS Analytics via Kubernetes Off-the-Shelf (KOTS) streamlines the process through the use of a `kubectl` plugin (KOTS CLI) and an admin console where you can upload your license file, choose install options, and
run pre-flight checks prior to deployment.

To install ITRS Analytics using KOTS, do the following:

-  Install the latest KOTS CLI, which is a `kubectl` plugin. Run: 
  
  ```
  curl https://kots.io/install | bash
  ```

-  Install the admin console on your desired namespace. To do this, run:

    ```
    kubectl kots install itrs-analytics/stable -n [namespace] 
    ```

## Log in to the Admin Console

-  Once the namespace has been created, you'll see a link to the admin console in the command line. Using the password you set in the previous step, log in to the admin console.

-  When prompted, upload your license file in the admin console.  

  - The license file should have been previously provided to you. Contact your ITRS representative if you do not have the required information.

-  Click **Download ITRS Analytics from the Internet**.


**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/wp5wfmwhnniq

## 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).

### Host names

-  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. This option is enabled by default for the larger cluster sizes, and disabling it may result in performance or stability issues.

  
**Warning**


If you are installing on an Embedded Cluster, or if your BYO cluster uses a storage driver that creates persistent volumes with node-level affinity, you must disable the ClickHouse node selectors in the KOTS Admin Console under **Advanced Settings > 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.


