Container Based Installation

Supported OS

The following Linux distributions on x86/64bit processors are supported:

• Ubuntu 18.04
• Ubuntu 20.04
• Debian 10.x
• Debian 11.x
• Red Hat Enterprise Linux 7.9
• Red Hat Enterprise Linux 8.x with Docker CE
• CentOS 7.9
• Amazon Linux 2.x
• SUSE Linux Enterprise Server 12 SP5
• SUSE Linux Enterprise Server 15

Supported Docker versions

• 20.10+
• 19.03+
• 18.03+
• 1.13

Minimum Requirements

The machine you are installing Instana onto, must have 16 CPU and 64 GB available memory.

Network security notes

NEVER expose Instana without taking proper precautions.

Make sure to properly firewall an installation. The only ports you should be exposing from a self-hosted installation are:

• Port 80: Used to catch broken links and promote them to SSL
• Port 443: Primary application port for UI and API
• Port 86 and 446: EUM ports, please check the more detailed docs here
• Port 1444: Acceptor port for agents to connect to

Prerequisites

• To authenticate against our Docker repository, please make sure the server can connect to auth-infra.instana.io:443
• All installation and migration commands must be executed as root user.
• You must have Docker installed and at least 25GB of free space for docker images. For more information on how to install Docker, see the Docker CE or Docker EE documentation.

• Setup mount points and external volumes:

  • Data Stores (defaults to /mnt/data).
  • Cassandra, should not utilize the same volume for production installs (defaults to /mnt/metrics).
  • ClickHouse should not utilize the same volume for productions installs (defaults to /mnt/traces).
• Logs (defaults to /var/log/instana). If required, you can create a different directory.

Fresh Installation: Single Host

1. Install the Instana package

To install the Instana package on your machine, use the installation steps described below.

Ubuntu/Debian

As root, execute the following lines:

echo "deb [arch=amd64] https://self-hosted.instana.io/apt generic main" > /etc/apt/sources.list.d/instana-product.list
wget -qO - "https://self-hosted.instana.io/signing_key.gpg" | apt-key add -
apt-get update
apt-get install instana-console

To avoid getting major updates during automated upgrades, please execute

cat >/etc/apt/preferences.d/instana-console <<EOF
Package: instana-console
Pin: version <version to pin>
Pin-Priority: 1000
EOF

RedHat/CentOS

As root, execute the following lines:

cat >/etc/yum.repos.d/Instana-Product.repo <<EOF
[instana-product]
name=Instana-Product
baseurl=https://self-hosted.instana.io/rpm/release/product/rpm/generic/x86_64/Packages
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://self-hosted.instana.io/signing_key.gpg
priority=5
sslverify=1
#proxy=http://x.x.x.x:8080
#proxy_username=
#proxy_password=
EOF
yum makecache -y fast
yum install -y instana-console

To avoid getting major updates during automated updates, please execute

yum versionlock add instana-console

2. Install Instana

Handling of the root user

The instana command requires root for running. This is because we need to be able adjust some values in the kernel and ensure access rights are set correctly on the different mount points.

Our containers are implemented to be rootless. So even though we require root for the installer, the application itself will run under the provided instana-user.

1. To install Instana on your machine, run the following command:

   instana init

   Note: A settings.hcl file is generated in the same directory as where you run the instana init command.

2. Select single (single host installation).

3. Enter the following information:

   • Your tenant name and unit name.
   • Your agent key and sales key.
   • DNS name.

   • Path to your certificate files. If no path is defined, Instana generates a HTTPS TLS certificate for the UI (tls.crt) and key (tls.key) in the cert folder. If you would like to generate your own self-signed certificates, enter your hostname in the following command:

     openssl req -x509 -newkey rsa:2048 -keyout tls.key -out tls.crt -days 365 -nodes -subj "/CN=<hostname>"

4. You can now sign in to Instana using the credentials displayed.
5. Once Instana is deployed, activate your license.

Air-gapped Installation on a Target Host

Pre-requisite: make sure you have Docker installed on the target host that has no internet connectivity.

1. On a host with internet connectivity, install instana-console as described in the first section of this page.

2. Download the required binaries. Two files are required for an air-gapped installation:

   1. The instana-console binary.

   Ubuntu/Debian: run apt-get download instana-console.

   RedHat/CentOS: run yum install --downloadonly instana-console.

   Or mirror our repository accordingly.

   2. The archive with Instana Docker containers.

   Run instana images export to create an export-{version}.tar within the execution directory.

3. Copy the files to the target host that has no internet connectivity.
4. Install instana-console from the package that you previously downloaded and transferred.
5. Ensure you have Docker installed.
6. To import the containers, run instana images import -f <path/to/export-{version}.tar>.
7. Start the installation as described in the install section above.

To check a list of mandatory containers, run instana images version. This command lists all the Docker containers and their corresponding version.

Image commands

The installer comes with a set of commands for managing the instana docker images.

Export images to tar

All required images of an instana-console version can be exported to a tar file. instana images export -k ${agent_key}

Import images from tar

Imports an exported image tar into the local docker cache. instana images import -f /path/to/export.tar

Prepull images

Prefetch all necessary images into the local docker cache instana images pull -k ${agent_key}

Push images to custom registry

Allows to push containers from the local docker cache to a custom hosted registry. Afterwards this registry can be configured in the settings.hcl and the installer will use it for installations and updates. instana images push -u ${registry_user} -p ${registry_pass} -r ${registry_url}

List images and versions

Returns a list of the currently required images for this version. instana images version

Prune local image cache

Removes all containers from the local cache that are no longer required for the current version. instana images prune

Installation: Multi-Host

For the multi-host installation, ClickHouse has been moved to a separate host with a distinct ZooKeeper installation.

0. (optional) Copy data from existing machine

If you are migrating from an exisitng installation you should take the time to move existing data to the new machine.

To do so it would be best to copy the existing data and log-directories from your original instalaltion. To do so check the original settings.hcl to find where these directories have been mounted.

After shutting down instana you can now copy from these directories:

• all directories named clickhouse (e.g. /mnt/traces/clickhouse and /mnt/log/instana/clickhouse)
• all directories named zookeeper (e.g. /mnt/data/zookeeper and /mnt/log/instana/zookeeper)

Move these to the same directories on the new machine and configure your new settings.hcl accordingly.

Note: It is not required to delete the old directories but we would suggest to do so after the new setup is up and running.

Now continue with the next steps.

1. Install the instana-console

Install instana-console from the repos as described above.

2. Expose Docker Daemon Port

The installer of the compute instance will try to connect to port :2376 of this host to check prerequisites.

enabling and accessing docker engine api on a remote docker host

if not set properly you will see the following error message:

remote docker daemon is not reachable on host <clickhouse-host>:2376 : Cannot connect to the Docker daemon at tcp://<clickhouse-host>:2376. Is the docker daemon running?

3. Install ClickHouse and Zookeeper on the First Host

Interactive

Run instana init and select dual-clickhouse as type.

Unattended

In the settings.hcl file, adjust type:

  type = "dual-clickhouse"

Install Instana

  instana init -y

Secure ClickHouse server using IPtables

To secure your ClickHouse server in a multihost environment, see the example below. This example ensures that only IO originating from the Instana backend host has access to the ClickHouse host. Please note that you need to ssh from the Instana backend server to the ClickHouse host afterwards or you will need to provide an additional IP from the box you want to ssh from.

iptables -A INPUT -s $(instana backend host IP) -j ACCEPT
iptables -A OUTPUT -d $(instana backend host IP) -j ACCEPT
iptables -A INPUT -d $(ssh host IP) -j ACCEPT #optional
iptables -A OUTPUT -d $(ssh host IP) -j ACCEPT #optional
iptables -A INPUT -j REJECT
iptables -A OUTPUT -j REJECT

4. Install the Rest of Instana on the Second Host

Interactive

Run instana init, select dual-instana as type and follow the interactive dialogue.

Unattended

Adjust type and add ClickHouse IP additionally to the settings.hcl file

  type                    = "dual-instana"
  clickhouse_bind_address = <IP of ClickHouse box>

Install Instana

  instana init -y

Self-hosted Post-Installation - IMPORTANT

We recommend monitoring the health of your self-hosted Instana server with the use of an Instana agent running in Infrastructure- only mode.

This will allow a number of health checks and metrics to be collected for your server.

Note

Infrastructure mode is essential - APM mode can put unnecessary load on your self-hosted services.

Example configuration for one-liner installation described here

Upgrade Your Package-Based to Container-Based Installation

Please create a backup of your data.

To upgrade from a existing installation, execute the following steps.

1. Change your repository to the new one
2. Install a supported Docker version.
3. Install instana-console version 170.

DEB

apt update
apt install instana-console=170-7

RPM

yum install instana-console-170-7

4. Execute the migration command containerize.

   instana containerize

5. Update to the newest release.

This command is only needed the first time to migrate from a package-based to a container-based install.

Note: A settings.hcl file is generated in the same directory as where you run the instana containerize command.

The following steps execute automatically:

1. Checks for Docker to be available.
2. Stops Instana.
3. Removes packages.
4. Downloads Docker images.
5. Starts Instana.

Upgrade Your Multi Host Package-Based to Multi Host Container-Based

Please create a backup of your data.

1. Install a supported Docker version on both hosts.
2. Install instana-console on both hosts.

3. Run the migration command containerize on the ClickHouse host.

   instana containerize -t dual-clickhouse

4. Expose docker daemon port as described above.

5. Run the migration command containerize on the Instana host.

   instana containerize -t dual-instana

This command is only needed the first time to migrate from a package-based to a container-based install.

Upgrade with a private docker registry

Using an internal docker registry you can specify the docker registry for your migration process changing the containerize comand to:

Single-Host

instana containerize --type single -y --registryUrl {url} --registryUser {user} --registryPass {pass}

Dual-Host

instana containerize --type dual-clickhouse -y --registryUrl {url} --registryUser {user} --registryPass {pass}

instana containerize --type dual-instana -y --registryUrl {url} --registryUser {user} --registryPass {pass}