Embedded Cluster air-gapped installation guide

ITRS Analytics is an observability platform that stores, analyzes, and visualizes metrics, logs, and events. One of the ways data can be ingested into ITRS Analytics is through Geneos, which collects real-time monitoring data from servers, databases, networks, and applications. ITRS Analytics processes and transforms your monitoring data into actionable insights through several dedicated apps such as Entity Viewer, Dashboards, and Alerting, all accessible via your Web Console.

This guide covers installing ITRS Analytics using the Embedded Cluster air-gapped deployment option and connecting it to Geneos to ingest data. This option provides a quick way to get started with ITRS Analytics publishing, ideal for smaller deployments, initial testing, or proof-of-concept scenarios. For large-scale production deployments requiring all apps and maximum resiliency, it is recommended to 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 is important to plan your deployment carefully. This includes preparing your license and determining 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. To determine your environment’s requirements, first obtain the message rate from your Geneos setup, then use the ITRS Analytics Sizer to calculate the recommended hardware and resource allocation.

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. To configure this in the Gateway Setup Editor:

1. Navigate to ITRS Analytics Connection.

2. Click Enable to enable publishing to ITRS Analytics.

3. Set the Mode to statisticsOnly to enable ITRS Analytics statistics.

   

Statistics are then recorded to the self-monitoring dataviews and to the gateway.log file.

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:

Note

The messageRate shown in the Summary 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.

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.

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.

Download the installation package Copied

Request the download link from Support or your Account Managers.

Note

The download link will vary depending on the deployment option. Make sure to inform Support or your Account Manager if you opt for a different deployment option.

Set up your system for Embedded Cluster installation Copied

Review the requirements 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:

• /etc/cni
• /etc/k0s
• /opt/cni
• /opt/containerd
• /run/calico
• /run/containerd
• /run/k0s
• /sys/fs/cgroup/kubepods
• /sys/fs/cgroup/system.slice/containerd.service
• /sys/fs/cgroup/system.slice/k0scontroller.service
• /usr/libexec/k0s
• /var/lib/calico
• /var/lib/cni
• /var/lib/containers
• /var/lib/kubelet
• /var/log/calico
• /var/log/containers
• /var/log/embedded-cluster
• /var/log/pods
• /usr/local/bin/k0s

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

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

Perform the preflight checks Copied

This step helps verify that your system and cluster meet the necessary requirements before proceeding with the installation.

Run this command to perform preflight checks:

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

Success

A successful preflight check will show Host preflight passed in the console.

Run the installer Copied

Install ITRS Analytics with the --airgap-bundle flag. Run the command:

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

Verify successful installation Copied

Once the installation is complete, the URL to the Admin Console will be displayed.

Configure ITRS Analytics in Admin Console Copied

The Admin Console is a web-based interface where you will configure ITRS Analytics after its successful installation. 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. Go to the URL from the installation output to open the Admin Console. Click Start.

2. If you see a security warning in the browser, click Advanced and proceed to the URL.

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

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

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

Configure the cluster (optional) Copied

On the Nodes screen, you can add nodes before deploying ITRS Anaytics. 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, 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. A fully qualified domain name (FQDN) is required for both the Apps external host name and Ingestion external host name where the application will be accessible.
   ITRS Analytics Apps	You will find in this section all required and optional production apps, as well as beta apps. You cannot select between production and beta apps or only production apps during setup. Refer to the table in Required ITRS Analytics apps for more information on the required apps.
   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.

2. Click Continue to proceed to Validate the environment and deploy ITRS Analytics section.

Required ITRS Analytics apps Copied

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

Validate the environment and deploy ITRS Analytics Copied

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

Enter your credentials to access the Web Console. When you first open the Web Console, 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. Save the file on your local folder so you can upload it to the Web Console. To upload:

1. On the Web Console side panel, click Admin.
2. Click the License Management tab.
3. Click Upload License, and then browse to the location where the .json file is saved.
4. Select the .json file.

You will see a confirmation when the file has been successfully uploaded.

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.

Connect to a Geneos Gateway Copied

After installing and configuring ITRS Analytics, you need to connect your Geneos Gateway to the platform so you can begin ingesting monitoring data to ITRS Analytics. This also enables you to:

• Store and analyze historical monitoring data at scale, correlating real-time and historical data for better troubleshooting and 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.

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.
3. Tick the Verify server certificate checkbox to enable the server certificate verification. This setting is applied in both the connection for publishing data to ITRS Analytics and for accessing data from ITRS Analytics.
4. Configure the following settings under Publishing and Data access sections:

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.

Verify successful Gateway connection Copied

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

You can do this in the Web Console by:

• Verifying that the Entity Viewer displays the same data visible in the Active Console.
• Running commands and ensuring they return a completed status.