Installing Instana backend on Docker

Supported OS

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

• Ubuntu 18.04
• Ubuntu 20.04
• Debian 10.x
• Debian 11.x
• CentOS / Oracle Linux / Red Hat Enterprise Linux 7.9
• CentOS / Oracle Linux / 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

The following Docker versions are supported:

• 20.10+
• 19.03+
• 18.03+
• 1.13

Minimum requirements

The machine where you want to install the Instana backend must have at minimum 12 CPUs and 48 GiB available memory. This is the lowest limit and only recommended for small installations. Production environments must have a minimum size of 16 CPUs and 64 GiB memory.

Network security notes

Note: Don't expose Instana without taking proper precautions.

Make sure to set the firewall properly for the installation. The only ports that you need to expose for a self-hosted installation are as follows:

• Port 80: Used to detect broken links and promote them to SSL.

• Port 443: Primary application port for UI and API.

• Port 86 and 446: EUM ports. For more information, see Exposing the monitoring endpoint to end users.

• Port 1444: Acceptor port for agents to connect to.

Prerequisites

• To authenticate against the Docker repository, make sure that the host machine that you want to install the Instana backend can connect to auth-infra.instana.io:443.
• All installation and migration commands must be run as root user.
• You must ensure that Docker is installed, and at least 25 GB of free spaces are available for Docker images. For more information about how to install Docker, see the Docker CE or Docker EE documentation.
• Set up mount points and external volumes:

  • Data stores

    Defaults to /mnt/data.

  • Cassandra

    It can't use the same volume for production installs. Defaults to /mnt/metrics.

  • ClickHouse

    It can't use 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

export DOWNLOAD_KEY=<download_key>

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 << EOF > /etc/apt/auth.conf
machine artifact-public.instana.io
  login _
  password $DOWNLOAD_KEY
EOF

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

apt update -y
apt install -y instana-console

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

export DOWNLOAD_KEY=<download_key>

cat << EOF > /etc/yum.repos.d/Instana-Product.repo
[instana-product]
name=Instana-Product
baseurl=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/rel-rpm-public-virtual/
enabled=1
gpgcheck=0
gpgkey=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-rpm-public-virtual
repo_gpgcheck=1
EOF

yum clean expire-cache -y
yum update -y
yum install -y instana-console

yum versionlock add instana-console

Air-gapped installation on a target host

Prerequisite: Make sure that Docker is installed on the target host that has no internet connectivity.

1. On a host with internet connectivity, install instana-console as described in the 1. Install the Instana package.

2. Download the required binary files.

   Two files are required for an air-gapped installation:

   • The instana-console binary

     For Ubuntu/Debian, run the command apt-get download instana-console.

     For Red Hat/CentOS, run the command yum install --downloadonly instana-console.

     Or you can mirror the Instana repository.

   • The archive with Instana Docker containers

     Run the command 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 that Docker is installed.

6. To import the containers, run the command instana images import -f <path/to/export-{version}.tar>.

7. Start the installation as described in the installation section.

To check a list of mandatory containers, run the command 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.

instana images export -k ${agent_key}

instana images import -f /path/to/export.tar

instana images pull -k ${agent_key}

instana images push -u ${registry_user} -p ${registry_pass} -r ${registry_url}

instana images version

instana images prune

Installation: Dual-host

For the dual-host installation, ClickHouse is moved to a separate host with a distinct ZooKeeper installation.

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?

  type = "dual-clickhouse"

  instana init -y

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

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

  instana init -y

Self-hosted postinstallation - important

You are recommended to monitor the health of your self-hosted Instana backend with the use of an Instana agent that is running in Infrastructure-only mode.

It allows a number of health checks and metrics to be collected for your Instana backend.

Note: Infrastructure mode is essential. APM mode can put unnecessary load on your self-hosted services. For more information, see Host agent modes.

For configuration of one-liner installation, see Additional parameters.

Upgrading with a private docker registry

To use an internal Docker registry, you can specify the Docker registry for your migration process by changing the containerize command:

• 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}
  

Optional Features

...
feature "beeinstana" {
  enabled=true
}
...

...
feature "infraEntityExplore" {
  enabled=true
}
...