Container Based Installation
TABLE OF CONTENTS
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
).
- Data Stores (defaults to
- 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
-
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 theinstana init
command. - Select
single
(single host installation). -
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 thecert
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>"
- You can now sign in to Instana using the credentials displayed.
- 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.
- On a host with internet connectivity, install
instana-console
as described in the first section of this page. -
Download the required binaries. Two files are required for an air-gapped installation:
- 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.
- The archive with Instana Docker containers.
Run
instana images export
to create anexport-{version}.tar
within the execution directory. - The
- Copy the files to the target host that has no internet connectivity.
- Install
instana-console
from the package that you previously downloaded and transferred. - Ensure you have Docker installed.
- To import the containers, run
instana images import -f <path/to/export-{version}.tar>
. - 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.
- Change your repository to the new one
- Install a supported Docker version.
- Install
instana-console
version 170.
DEB
apt update
apt install instana-console=170-7
RPM
yum install instana-console-170-7
-
Execute the migration command
containerize
.instana containerize
- 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:
- Checks for Docker to be available.
- Stops Instana.
- Removes packages.
- Downloads Docker images.
- Starts Instana.
Upgrade Your Multi Host Package-Based to Multi Host Container-Based
Please create a backup of your data.
- Install a supported Docker version on both hosts.
- Install
instana-console
on both hosts. -
Run the migration command
containerize
on the ClickHouse host.instana containerize -t dual-clickhouse
- Expose docker daemon port as described above.
-
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}