Container Based Installation

Supported OS

To run the Instana Backend-Platform, the following Linux distributions are supported:

• Ubuntu 16.04, 18.04
• Debian 8.x, 9.x, 10.x
• RedHat 7.2+
• CentOS 7.x
• Amazon Linux 2.x

Supported Docker versions

• 19.03+
• 18.03+
• 1.13

Minimum Requirements

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

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

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

Fresh Installation: Multi-Host

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

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

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