Internal documentation only

This page has been marked as draft.

ITRS Analytics Embedded Cluster air-gapped installation guide

ITRS Analytics is an observability platform that stores and analyzes metrics, logs, and events. Geneos collects real-time monitoring data from servers, databases, networks, and applications, then feeds this data to ITRS Analytics for processing and transformation into actionable insights through apps such as Entity Viewer, Dashboards, and Alerting, accessible via the Web Console.

Connecting Geneos with ITRS Analytics enables you:

• Store and analyze historical monitoring data at scale, correlating real-time data with historical trends to improve troubleshooting and gain deeper insights.
• Access advanced analytics and visualization capabilities through web-based interfaces for comprehensive monitoring and analysis.
• Centralize monitoring data from multiple Gateways and Netprobes in a single platform for unified visibility across your infrastructure.
• Enhance alerting capabilities with historical context and trend analysis to identify patterns and prevent issues before they impact operations.
• Scale your monitoring infrastructure to handle large volumes of metrics, logs, and events as your environment grows.

This guide covers installing ITRS Analytics using the Embedded Cluster air-gapped deployment option and connecting it to Geneos. This option provides a quick way to get started with ITRS Analytics publishing, ideal for smaller deployments, initial testing, or proof-of-concept scenarios. Start with a small number of Gateways to verify everything works correctly before rolling out to production. For large-scale production deployments requiring all apps and maximum resiliency, use the Bring-Your-Own-Cluster (BYOC) deployment option.

Note

This guide assumes you already have Geneos installed. If not, see the Geneos Quickstart Guide for installation instructions.

Plan your ITRS Analytics installation Copied

Before installing ITRS Analytics and connecting it to Geneos, it’s important to plan your deployment carefully. This ensures a smooth installation and optimal performance for your environment. In this section, you will prepare your license and determine the server sizing and requirements for your setup.

Get your ITRS Analytics license Copied

You can request an ITRS Analytics license from Support or from your Account Managers.

Note

ITRS Analytics comes with a bootstrap license which allows users to use the platform for five days for free.

Determine your server size and requirements Copied

Proper sizing is essential for ITRS Analytics to run efficiently and handle your monitoring data at scale. Ensure smooth operation by allocating the recommended hardware and resources. First, get the message rate, then use the ITRS Analytics Sizer to determine your environment’s requirements.

Get the message rate Copied

The required size by ITRS Analytics depends mainly on the message rate it needs to handle.

For existing Geneos customers, the message rate generated by any Gateway (version 5.14.0 or later) can be obtained by configuring ITRS Analytics publishing in statistics-only mode. For example:

The messageRate shown in the Gateway dataview does not indicate the total message rate of your Gateway. It only reflects the number of messages that were successfully sent during the last sampling interval. To calculate the overall required message rate, check the gateway.log file or sum the message rates from all Gateways connected to the same ITRS Analytics instance. For example:

If these statistics are not available, you can initially refer to the sizing guidelines. The recommended number of servers for ITRS Analytics is based on specific assumptions (outlined in the table below) and an analysis of message rates from existing Gateways. You may use these estimates as a starting point, but validate them with actual statistics from your Gateways as soon as possible, since message rates can vary significantly between different plugins.

For more information on t-shirt sizing, refer to Resource and hardware requirements.

Estimate cluster requirements with ITRS Analytics Sizer Copied

Once you have the message rate, use the interactive ITRS Analytics Sizer tool to calculate additional infrastructure requirements, including cluster size, if you plan to enable Linkerd, Trust Manager, or install apps. The results will display an overview of the expected resource usage, drawing data from the latest available version of ITRS Analytics.

Install ITRS Analytics Copied

With your license ready and server requirements determined, you are now ready to install ITRS Analytics. This section covers installing ITRS Analytics in an Embedded Cluster air-gapped deployment so that it can receive data from Geneos Gateways and Netprobes.

Download the installation package Copied

Since this is for Embedded Cluster, request the download link from Support or your Account Managers.

The link will vary depending on your chosen deployment option.

Set up your system for embedded cluster installation Copied

This guide outlines the requirements to prepare your environment for the installation of the Embedded Cluster. Follow the guidelines below to ensure that your system is properly configured and fully ready for the installation process.

System requirements summary Copied

Directories created by Embedded Cluster Copied

The cluster and its components will automatically create files and directories in the following paths:

Network access for online installations Copied

If you’re installing Embedded Cluster with an internet connection, make sure your system can connect to these websites or a custom domain provided by your company:

• replicated.app — for the range of IP address, see IP list.
• proxy.replicated.com — for the range of IP address, see IP list.
• Port 443 (TCP protocol with HTTPS service)

k0s compatibility Copied

Embedded Cluster is built on k0s, so it inherits all k0s system requirements and external runtime dependencies.

Data directory Copied

The data directory is a necessary component of the ITRS Analytics application, containing both application data and logs. The allocated disk space for this directory must correspond to the t-shirt size chosen during deployment (for example, small, medium, large). For more information, see Resources and hardware requirements.

Default data directory Copied

By default, the data directory is set to /var/lib/embedded-cluster. If the default is used, ITRS Analytics will share disk space to other non-ITRS applications using the /var/lib/ or /var partition.

Custom data directory Copied

To configure a custom data directory path during installation, use the --data-dir flag with the Embedded Cluster installation command.

Notes and limitations Copied

The following constraints apply when using or configuring the data directory:

• You cannot change the data directory of the Embedded Cluster after installation.
• In multi-node setups, all nodes must use the same data directory specified during the initial installation. A different data directory cannot be selected when joining additional nodes to the cluster using the Embedded Cluster join command.
• If you specify a different data directory during installation using the --data-dir flag, you must use the same directory path when performing a disaster recovery restore.
• Symlinks are not supported for the Embedded Cluster data directory.

Port requirements Copied

Correct port configuration is important for the operation of Embedded Cluster. These ports need to be accessible for both single-node and multi-node installations.

Ports for local processes Copied

These ports must be accessible to local processes on the same node. No firewall rules are required.

Ports for inter-node communication Copied

The ports listed below are used for two-way communication between nodes.

• In multi-node setups, you must open these ports in the firewall to allow traffic between nodes.
• In single-node setups, these ports must still be available, even though no inter-node communication occurs.

Additional services Copied

Port for Admin Console Copied

Open port 30000/TCP in the firewall to allow end users to access the Admin Console. This port must also be reachable by any nodes joining the cluster.

If port 30000 is already in use, you can specify a different port during installation by running the --admin-console-port flag with the Embedded Cluster install command. For example:

sudo ./itrs-analytics install --license license.yaml --admin-console-port=20000

Port for Local Artifact Mirror (LAM) Copied

If port 50000 is already in use, you can choose a different port for the LAM during installation by running the --local-artifact-mirror-port flag with the Embedded Cluster install command. For example:

sudo ./itrs-analytics install --license license.yaml --local-artifact-mirror-port=40000

Summary of setup and requirements Copied

Ensure your system meets the hardware, OS, and disk performance specifications.

Set up directories, confirm system services (like systemd), and verify available disk space.

Consider important aspects of the data directory, including storage capacity and supported configurations.

Configure firewall rules or verify port availability for local and inter-node communication.

Make sure the system can reach necessary external domains like replicated.app.

Go through a final check to verify readiness for installation.

Execute the install command with optional flags for data directories and custom ports.

Perform the pre-flight checks Copied

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 --airgap-bundle itrs-analytics.airgap

For detailed information on the pre-flight checks, refer to Additonal preflight checks before embedded cluster installation.

Run the installer Copied

1. Install ITRS Analytics with the --airgap-bundle flag. For example:

sudo ./itrs-analytics install --license license.yaml --airgap-bundle ./itrs-analytics.airgap

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

Configure ITRS Analytics in Admin Console Copied

After installation, you need to configure ITRS Analytics through the Admin Console. This process involves securing the Admin Console with certificates, optionally configuring cluster nodes, setting up ITRS Analytics with your preferred apps and settings, and then deploying the platform.

Secure the Admin Console Copied

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

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

3. Log in to the Admin Console using the password you set in the command output during installation.

Tip

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

Configure the cluster (optional) Copied

On the Nodes screen, optionally add nodes before deploying ITRS Anaytics and then click Continue. To create a multi-node cluster with Embedded Cluster, see Multi-node clusters with Embedded Cluster air-gapped.

Configure ITRS Analytics Copied

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

2. Configure the following sections:

   Expand table

   Section	What you need to do
   Prerequisites	Verify that the required packages have been installed.
   Cluster Settings	Select the appropriate cluster size based on your needs. For more information, see Sizing guidelines.
   Host names	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 this 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. Refer to the table in Required ITRS Analytics apps for more information on the Required Apps. 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.
   Optional Apps	Review recommended apps, as well as other apps you can install depending on your business requirements.
   Beta apps	Review beta apps. These 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	Review default login information for different user and admin levels, intended for informational purposes.
   Storage Settings	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	Select Show Advanced Configuration to view advanced configuration options.
   Service Mesh	Select to install trust-manager for Linkerd integration (only available if linkerd installation is enabled).
   TLS Certificates	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.
   ITRS Analytics: custom certificates	Select ITRS Analytics: custom certificates to use custom ITRS Analytics certificates. You will need to provide a PEM file and a corresponding private TLS key.
   Ingress Annotations	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.
   Preflight and Support Bundle Settings	Select to enable Run Disk I/O Performance Test or Include Disk I/O Test for Support Bundle.
   Backup and Restore	Select Enable IAX backup and restore to activate backup and restore support for ITRS Analytics using Velero.
   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.
   Helm Install/Upgrade Options	Configure the ITRS Analytics Helm Chart Timeout setting to be used during installation or upgrade operations.
   Helm Chart Values Override	Input your desired configuration values to override the default Helm chart settings and then save your configuration. (Formerly Parameters Override.)

3. Click Continue to proceed to the next configuration section.

Required ITRS Analytics apps Copied

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

Validate the environment & deploy ITRS Analytics Copied

After completing all configurations, wait for the version to finish deploying, then access the ITRS Analytics Web Console.

When opening the Web Console for the first time, enter your credentials. Change your password to activate your account.

Post installation Copied

Upload the ITRS Analytics user license Copied

After installation, you must upload your ITRS Analytics user license to activate the platform. While ITRS Analytics comes with a bootstrap license that allows you to use the platform for five days, you need to upload the requested ITRS Analytics license file to continue using the platform beyond this period.

For detailed instructions on uploading the license through the Web Console, see Upload the ITRS Analytics license.

Note

When the license expires, data ingestion will continue but ITRS Analytics will stop serving data.

This is an example of the Web Console view showing that the licenses have been uploaded correctly:

Check the Roles in IAM app Copied

After uploading the license file to the Web Console, verify the roles configured in the IAM app, particularly the user role and its associated permissions. By default, the user role is granted full read access to all entities, which may need to be restricted in production environments.

For comprehensive information about managing roles and permissions in the IAM app, see Identity and Access Management (IAM) app.

Connect to a Geneos Gateway Copied

After installing and configuring ITRS Analytics, you need to connect your Geneos Gateway to the platform. This enables Gateways and Netprobes to publish monitoring data to ITRS Analytics, allowing you to store and analyze metrics, logs, and events.

For comprehensive information about connecting Geneos to ITRS Analytics, see Connect Geneos to ITRS Analytics.

Configure ITRS Analytics Connection in the Gateway Setup Editor Copied

To start publishing data from Gateway to ITRS Analytics, you must configure the ITRS Analytics Connection in the Gateway Setup Editor (GSE).

To configure ITRS Analytics Connection:

1. Tick the Enable checkbox.
2. Set Mode to connection, then tick the Verify server certificate checkbox.
3. Configure the following settings under Publishing and Data access sections:

Refer to the basic configuration in ITRS Analytics Connection for detailed settings information.

Configure Geneos commands Copied

To enable Gateway commands to work with ITRS Analytics, you must configure the Authentication section in the GSE. This allows users in ITRS Analytics to execute commands through the Entity Viewer app.

To configure the Geneos commands:

1. Navigate to the Authentication section of the GSE.

2. Create a Role that has permissions to execute all available commands.

3. Add the user role created in ITRS Analytics in the Role properties setting.

Note

• The user role created in ITRS Analytics can be added to an existing Gateway role that has permissions to execute commands.
• The example above gives ITRS Analytics access to all available Gateway commands. You can limit this access to specific Gateway commands by configuring Role > Permissions > Options > Command. See Command permissions - Gateway Authentication Technical Reference.

For comprehensive information about configuring Geneos commands and data for ITRS Analytics, see Configure Geneos commands and data for ITRS Analytics.

Verify successful Gateway connection Copied

After completing the configuration steps, confirm that the Gateway is successfully connected to ITRS Analytics.

In the Web Console, verify that the Entity Viewer displays the same data visible in the Active Console. Run Commands and ensure they return a completed status.

Other deployment options Copied

The options to deploy ITRS Analytics also depends what your environment supports. This can be identified by your available Kubernetes resources and the type of internet access as shown in the matrix below. Click the link on the options if you choose other deployment options.