Skip to main content

Instana Server Installation

3.1: Introduction

Instana backend is available as SaaS (preferred option) or self hosted (aka on-prem). For on-premises installations, Instana offers multiple containerized options:

  • Self Hosted Standard Edition Installs both the Instana backend and datastores on a single node K3s cluster.
  • Self Hosted Custom Edition Installs the backend Kubernetes Operator on a RedHat OpenShift or Kubernetes cluster. The datastores are not installed by the operator, they require manual installation either locally on the same cluster or remotely.
  • Self Hosted Classic Edition Install both the Instana backend and the datasotres on a single VM using Docker. Unlike the other options this deployment does not support multi-tenancy.
tip

On-premises (self-hosted) releases are delivered every 4 weeks. The release have odd numbers such as 225, 227, 229, etc. When upgrading, you may upgrade from N-1 or N-2, but you can't skip more than one release. So, you can upgrade from 225 to 229, but not to 231. Even numbered releases are for SaaS only. SaaS is upgraded every 2 weeks.

For the installation of the Instana server, we'll be following the instructions from the Instana documentation for a Self-Hosted Standard Edition. The instructions can be found here for your reference, but you can follow the steps below. You will be performing an online installation during this Tech Jam, but Instana does support off-line (air-gapped) installs.

The Classic Edition and Standard Editions are Instana's smallest on-premises installation option. Production and larger deployments are installed into kubernetes for horizontal scale and resiliency. For this lab the installation of Instana will be completed on the VM named instana.

install instana architecture

3.2: Prerequisites

Instana requires a Linux server with 16 cores, 64 Gig of RAM and few hundred Gig of disk space for a POC sized deployment. It also requires fast backend storage. For environments with even a few hundred servers, you'll need 6000 IOPS or more. For larger deployments, you'll need more capacity. Several different versions of Linux are supported. We have chosen Ubuntu 22.04 for this environment.

info

Normally, you would need to ensure that the virtual machine has the correct ports opened in the firewall for the agent, UI, and EUM communications. We have already done this work for you. For reference, here are the ports that need to be opened for the Instana Server for an on-prem deployment. The ports for SaaS are slightly different.

tip

If you are unsure how to get access to the Bastion host (Guacamole) see Accessing a Lab Environment

From the Bastion host (Guacamole), open a terminal window by selecting Activities at the top left of the screen and then the terminal icon.

open-terminal

Use the terminal to login to the Instana host:

ssh jammer@instana

When prompted if you want to continue connecting, type: yes

Use sudo to become root.

sudo -i

Prior to installing Instana, you must ensure there is no instance of Docker on the machine you will use as it can conflict with K3s.

Optional Tip

Due to the large number of requests that can be made to Docker Hub from the IBM network rate limiting may occur when you try to install Instana. You can prevent this by adding your own Docker Hub credentials.

  1. Sign up to Docker Hub if you don't already have an account.
  2. From the Instana VM export the following environment variables:
export DOCKER_HUB_USERNAME=<your-docker-hub-username>
export DOCKER_HUB_PASSWORD=<your-docker-hub-password>
  1. Run the following commands to create the authentication file for Docker Hub in the K3s directory:
sudo mkdir -p /etc/rancher/k3s
sudo tee /etc/rancher/k3s/registries.yaml <<EOF
configs:
registry-1.docker.io:
auth:
username: ${DOCKER_HUB_USERNAME}
password: ${DOCKER_HUB_PASSWORD}
EOF
  1. Confirm the new file is accurate by running:
cat /etc/rancher/k3s/registries.yaml

3.3. Preparing the server

There are few tasks that need to be run to prepare the server for the installation.

Set the required kernel parameters by running the following commands:

echo fs.inotify.max_user_instances=8192 >> /etc/sysctl.d/99-stanctl.conf && sudo sysctl -p /etc/sysctl.d/99-stanctl.conf
echo vm.swappiness=0 >> /etc/sysctl.d/99-stanctl.conf && sudo sysctl -p /etc/sysctl.d/99-stanctl.conf
sysctl --load
echo never > /sys/kernel/mm/transparent_hugepage/enabled

Set the firewall rules. In this lab we are in a restricted network so we don't need to worry about the firewall rules. You can simply run the following:

ufw disable

For production you can reference the Firewall Rules documentation for the exact rules you need to set for your Operating System.

Prepare the mount volumes. We will be using a single disk with multiple directories in this lab. In a production environment you will likely want to provision multiple disks to meet the IOPS requirements of Instana. If you use more than one disk you can refer to the documentaton for preparing additional disks for the Instana server.

mkdir -p /mnt/instana/stanctl/data
mkdir -p /mnt/instana/stanctl/metrics
mkdir -p /mnt/instana/stanctl/analytics
mkdir -p /mnt/instana/stanctl/objects

You are now ready to start the installation of the Instana Server.


3.4. Installing Instana

Export the Download key as an environment variables

export DOWNLOAD_KEY=<your-download-key>

Run the following commands to install the Instana package. Review the output of each command using cat to be sure the commands are successful before proceeding to the next step.

echo 'deb [signed-by=/usr/share/keyrings/instana-archive-keyring.gpg] https://artifact-public.instana.io/artifactory/rel-debian-public-virtual generic main' > /etc/apt/sources.list.d/instana-product.list
cat /etc/apt/sources.list.d/instana-product.list
cat << EOF > /etc/apt/auth.conf
machine artifact-public.instana.io
login _
password $DOWNLOAD_KEY
EOF
cat /etc/apt/auth.conf
wget -O- --user=_ --password="$DOWNLOAD_KEY" https://artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-debian-public-virtual | gpg --dearmor > /usr/share/keyrings/instana-archive-keyring.gpg
cat /usr/share/keyrings/instana-archive-keyring.gpg

Update the package list and install the Instana stanctl installation tool.

apt update -y
apt install -y stanctl

Hold the stanctl package to prevent it from being upgraded unintentionally.

apt-mark hold stanctl

Install Instana

  • We are installing Instana in demo mode.
  • DNS has already been configured in this environment for the Instana vm, it can be reached at instana.techzone.lan. Further details on required DNS entries can be found here.
  • Internally, Instana has tenants, which are merely a logical construct. Each tenant in turn has at least one or multiple tenant units. There are restrictions to the names that can be chosen. In this case the tenant is IBM and the unit is unit0.
  • The default administrator password for the admin.instana.local user is Passw0rd.
  • We are setting the volumes to the directories we created earlier.
  • We are skipping preflight checks as the environment does not have the storage required to meet the minimum requirements, it is satisfactory for a small demo instance though.
stanctl up \
--install-type="demo" \
--timeout="60m0s" \
--core-base-domain="instana.techzone.lan" \
--download-key=$DOWNLOAD_KEY \
--sales-key=$SALES_KEY \
--unit-tenant-name="ibm" \
--unit-unit-name="unit0" \
--unit-initial-admin-password="Passw0rd" \
--volume-analytics="/mnt/instana/stanctl/analytics" \
--volume-metrics="/mnt/instana/stanctl/metrics" \
--volume-objects="/mnt/instana/stanctl/objects" \
--volume-data="/mnt/instana/stanctl/data" \
--skip-preflight-check

The instana license is automatically applied during the installation process. You can view it by running the following command:

stanctl license info

3.5: Launch the Instana User interface

Once the installation finished and you are prompted with the message....

You can open a browser and login to the Instana user interface.

Open a firefox browser and select the Instana bookmark.

open firefox

info

You can safely ignore the warning about the certificate being untrusted.

untrusted-cert-advance

When prompted, enter the username and password that you updated earlier.

You will be taken to an Initial Screen where you can install the instana agents or navigate to the main product UI. We will install an Instana Agent in the upcoming section of the lab.


3.6: Setting up SMTP

Do not perform these steps

You should not perform any steps in this section, it is for information only.

You can configure SMTP settings when installing the cluster however as we have already installed the Instana server, we can now make modifications to the backend configuration using the stanctl tool.

stanctl backend apply \
--core-smtp-from="server@instana.com" \
--core-smtp-host="localhost" \
--core-smtp-password="Passw0rd" \
--core-smtp-port=25 \
--core-smtp-start-tls=false \
--core-smtp-use-ssl=false

You should see output similar to the below:

backend-apply

3.7: Turning on features

Do not perform these steps

You should not perform any steps in this section, it is for information only.

There are optional configurations that you will likely want to make to your installation of Instana.

These options are made available via optional 'feature flags'. For features such as VMware/vSphere monitoring, Power HMC monitoring, and zHMC monitoring which are disabled by default.

As an example to enable VMware/vSphere monitoring, you would run the following command:

stanctl backend apply --core-feature-flags feature.vsphere.enabled

You can view a full list of available feature flags here.


3.8: Upgrading the Instana server

Do not perform these steps

You should not perform any steps in this section, it is for information only.

Upgrades are made simple with the stanctl tool. The process for an upgrade is to first upgrade stanctl and then upgrade the Instana backend.

Upgrading the stanctl tool is different depending on the Operating System you are using. As an example for Ubuntu you would run the following commands:

# Unhold the stanctl package if it is held
sudo apt-mark unhold stanctl

apt update -y
apt install -y stanctl

# Hold the stanctl package again to prevent it from being upgraded unintentionally.
apt-mark hold stanctl

Then upgrade the backend:

stanctl up

The command will list the available updates. You can select Proceed with installing the updates to upgrade the backend.


3.9: Summary

In this portion of the lab, you have learned how to install a self-hosted docker based Instana server. For a POC, we recommend either SaaS or the single server self-hosted docker installation of the Instana server. For production deployments, customers will want the kubernetes based deployments to gain improved scalability and resiliency.

You have also learned how to configure the SMTP settings and how to enable feature flags.

Finally, you learned how to upgrade a docker based self-hosted Instana server.

You are now ready to learn how to install and configure an Instana Agent.