Installing Instana backend on Docker

1. Installing the Instana package

To install the Instana package on your machine, use the following installation steps:

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

2. Installing Instana

Note: The Instana command requires the root user for running because it's needed to adjust some values in the kernel and ensure that access rights are set correctly on the different mount points.

Instana containers are implemented to be rootless. So even though the root user is required for the installer, the application itself runs in the provided instana-user.

1. To install Instana backend 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 an HTTPS TLS certificate for the UI (tls.crt) and key (tls.key) in the cert folder. If you want 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 by using the credentials that are displayed.

5. After Instana is deployed, activate your license.

Exporting images to tar

All required images of an instana-console version can be exported to a tar file by running the following command:

instana images export -k ${agent_key}

Importing images from tar

Import an export image tar into the local Docker cache by running the following command:

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

Prepulling images

Prefetch all necessary images into the local docker cache by running the following command:

instana images pull -k ${agent_key}

Pushing images to custom registry

Allow to push containers from the local Docker cache to a custom hosted registry by running the following command:

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

Afterward, the registry can be configured in the settings.hcl file and the installer uses it for installations and updates.

Listing images and versions

Return a list of the currently required images for this version by running the following command:

instana images version

Pruning local image cache

Remove all containers from the local cache that are no longer required for the current version by running the following command:

instana images prune

1. Optional: Copying data from existing machine

If you want to migrate from a current installation, you need to take the time to move existing data to the new machine.

To do so, it is best to copy the existing data and log directories from your original installation. You can check the original settings.hcl file to find where these directories are mounted.

After Instana is shut down, you can copy from these directories:

• All directories that are named clickhouse, such as /mnt/traces/clickhouse and /mnt/log/instana/clickhouse.
• All directories that are named zookeeper, such as /mnt/data/zookeeper and /mnt/log/instana/zookeeper.

Move the directories to the same directories on the new machine, and configure your new settings.hcl file.

Note: You are not required to delete the old directories, but you are suggested doing so after the new setup is up and running.

2. Installing the instana-console

Install instana-console from the repositories as previously described.

3. Exposing Docker Daemon port

The installer of the compute instance tries to connect to the port :2376 of this host to check prerequisites. For more information, see Enabling and accessing docker engine api on a remote docker host

If it's not set properly, you can 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?

4. Installing ClickHouse and Zookeeper on the first host

  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

5. Installing the rest of Instana on the second host

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

  instana init -y

BeeInstana Metric Pipeline (beta)

This feature includes a new data pipeline with additional Instana backend components and a datastore (BeeInstana) to the store of the infrastructure metrics. Based on this data, further features can be activated in the product.

• Custom Infrastructure Dashboards
• Infrastructure Explore

Note: Ensure that enough free space is available in the storage location for the metric data, and the entire system is not currently being operated at its capacity limits. This is because the additional components might endanger the stability.

An estimated disk size of 1 million metrics can be derived from this table:

To enable the pipeline and Custom Infrastructure Dashboards, enable the following feature flag in the settings.hcl file, and apply this change by using an instana update command to the system.

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

Furthermore, you can activate Infrastructure Explore by using the following feature flag:

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