Install in an air-gapped Bring-Your-Own (BYO) cluster with KOTS

Prerequisites Copied

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. The supported managed service providers are listed below.

  Expand table

  Cluster type	Supported versions
  Azure Kubernetes Service (AKS)	1.29, 1.30, 1.31, 1.32
  Amazon Elastic Kubernetes Service (EKS)	1.29, 1.30, 1.31, 1.32
  Google Kubernetes Engine (GKE)	1.30, 1.31, 1.32
  Oracle Cloud Infrastructure Kubernetes Engine (OKE - Beta)	1.31, 1.32
  RedHat OpenShift Container Platform (OCP)	4.16, 4.17, 4.18, 4.19

  For compatibility details with earlier versions, please refer to the compatibility matrix.

• Check that resource and hardware requirements are met.

• Provide access to a Docker registry to pull and push container images. The host name must support Docker v2 protocol.

• 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, which is used in BYO air-gapped environments. Alternatively, you can choose to grant namespace-scoped RBAC permissions to KOTS.

• Before installing, you can deploy and scan ITRS Docker images. Refer to this sample list of images from the Docker registry.

• Make sure that you are not using ARM64 processors, which is currently not supported in airgap installations.

• For Medium and Large-sized deployments, you must assign the appropriate labels and taints to nodes designated for timescale to ensure proper scheduling and workload isolation.

  • For label command:

    kubectl label nodes <node_name> instancegroup=timescale-nodes;
    

  • For taint command:

    kubectl taint nodes <node_name> dedicated=timescale-nodes:NoSchedule;
    

Installing ITRS Analytics on strict PSS clusters Copied

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 Copied

If you opt to install ITRS Analytics in an existing cluster, you should choose the Bring-Your-Own (BYO) option. You can download the required components from the provided download portal.

Tip

If this is your first time downloading the required files, please refer to the Customer’s Download Portal. Otherwise, you can proceed to the next step.

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:

• Begin by downloading the required components from the download portal.

  • KOTS CLI – latest version of the kubectl plugin.
  • KOTS Admin Console Bundle – kotsadm.tar.gz. Ensure that the version matches the installed KOTS CLI. Refer to the replicatedhq/kots for version information.
  • ITRS Analytics App Bundle – choose the preferred version for deployment.

• Install the downloaded KOTS CLI and perform the following steps below.

  • Unarchive the downloaded file (kots_*.tar.gz) and run the appropriate command based on your OS and architecture.
  • Rename the extracted kots binary to kubectl-kots and move it to a directory in your system’s PATH. Note that you can run echo $PATH to view the list of directories in your PATH. This makes the executable accessible system-wide, so you can run KOTS CLI commands from any directory.
  • Verify the installation.

    kubectl kots version
    

    For detailed guidance, refer to the Manually Download and Install documentation.

• Push the images to your private registry.

  kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_HOST/REGISTRY_NAMESPACE \
    --registry-username RW_USERNAME \
    --registry-password RW_PASSWORD
  

  • REGISTRY_HOST must follow RFC 1123 hostname standards (see RFC 1123: Requirements for Internet Hosts - Application and Support). For example: example.com:5000.
  • REGISTRY_NAMESPACE is an identifier that follows the host.

In the example that follows, the namespace is itrs:

kubectl kots admin-console push-images ./kotsadm.tar.gz example.com:5000/itrs \
  --registry-username name \
  --registry-password ******

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

  kubectl kots install itrs-analytics \
    -n TARGET_NAMESPACE \
    --kotsadm-registry REGISTRY_HOST/REGISTRY_NAMESPACE \
    --registry-username RW_USERNAME \
    --registry-password RW_PASSWORD
  

  • TARGET_NAMESPACE is the namespace where ITRS Analytics will be deployed. It will be created if it doesn’t exist.

Log in to the Admin Console Copied

• 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. Note that the license file should have been previously provided to you. Contact your ITRS representative if you do not have the required information.

• Provide the required registry and access information as prompted under the Install in airgapped environment screen. Then, upload the ITRS Analytics App Bundle (previously downloaded) from your computer.

Tip

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

Configure ITRS Analytics Copied

Prerequisites Copied

• 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 Copied

• On the Cluster Settings section, select the appropriate cluster size based on your needs. For more information, see Sizing guidelines.

Host names Copied

• 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 Copied

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

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

  Expand table

  Required apps	Description
  Web Console	ITRS Analytics Web Console lets you easily track critical monitoring data of your always-on enterprise from a web browser.
  Query Service	ITRS Analytics Query Service app 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 provides a web-based interface for real-time monitoring, investigation, and analysis of entities tracked in ITRS Analytics.
  Commands	ITRS Analytics Commands app enables additional command functions in the Entity Viewer app.
  Public API	ITRS Analytics Public API provides a publicly accessible REST API to interact with the ITRS Analytics Platform.

  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 Copied

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

Storage Settings Copied

• On the Storage Settings section, click a checkbox to display configuration options. Note that modifying these settings may require advanced configuration to adjust correctly. When configuring storage classes, make sure that upgrades are supported, since these are performed independently from ITRS Analytics installation.

Advanced Settings Copied

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

• Under Uptrends Configuration, you can toggle Enable RUM 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, and use this guide to find the Site ID (SID).

  Enabling this option displays the RUM 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 linkerd is enabled, select Linkerd: custom linkerd certificates to use custom Linkerd certificates. You will need to provide a PEM file and a corresponding private TLS key.

• To use custom ITRS Analytics certificates, select ITRS Analytics: custom certificates. You will need to provide a PEM file and a corresponding private TLS key.

• Under Ingress Annotations, you must specify custom annotations for ingress resources. The required annotations will vary depending on the ingress controller installed. For example, if you’re using the default ingress-nginx controller, standard annotations apply. However, if you install or use a different ingress controller, you must provide the corresponding annotations specific to that controller.

• Under Preflight and Support Bundle Settings, select to enable Run Disk I/O Performance Test or Include Disk I/O Test for Support Bundle.

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

• Under Timescale Workload Scheduling, enable Enforce Timescale Node Selector to ensure Timescale workloads run only on nodes matching the defined selector. This option is enabled by default, and disabling it may result in performance or stability issues.

• Under Helm Install/Upgrade Options, you can configure the ITRS Analytics Helm Chart Timeout setting to be used during installation or upgrade operations.

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

Preflight checks and deploy Copied

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