Installing Self-Hosted Classic Edition (Docker)

You can install Self-Hosted Classic Edition (Docker) by using either a single-host or dual-host.

About this task

The single-host installation means that all Instana components and data stores are installed on a single host as Docker containers.

The dual-host installation means that ClickHouse is deployed on one host with a ZooKeeper installation while the rest of the Instana components and data stores are deployed on a second host.

For more information about the benefits of each option, see Installation options.

Before you begin

You must meet the requirements about supported OS, supported Docker versions, minimum requirements, network security notes, and prerequisites as described in Requirements for Classic Edition.

Notes:

Installing in an air-gapped environment

To install Classic Edition on a target host in an air-gapped Docker environment, complete the following steps.

If the target host where you want to install the Instana backend has internet connectivity, skip these steps, and go to the Installing on a single host or Installing on dual hosts section directly.

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 apt-get download instana-console command.

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

      Or you can mirror the Instana repository.

    • The archive with Instana Docker containers

      Run the instana images export command to create an export-{version}.tar file 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. Import the containers by running the instana images import -f <path/to/export-{version}.tar> command.

  7. Start the installation as described in the Installing on a single host or Installing on dual hosts section.

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

For more information, see the Image commands section.

Image commands

The installer comes with a set of commands for managing the Instana Docker images.

Exporting images to tar

To export all required images of an instana-console version to a .tar file, run the following command:

instana images export -k ${agent_key}

Importing images from tar

To import an export image tar into the local Docker cache, run the following command:

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

Prepulling images

To prefetch all necessary images into the local Docker cache, run the following command:

instana images pull -k ${agent_key}

Pushing images to custom registry

To push containers from the local Docker cache to a custom hosted registry, run the following command:

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

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

Listing images and versions

To return a list of the currently required images for this version, run the following command:

instana images version

Pruning local image cache

To remove all containers from the local cache that are no longer required for the current version, run the following command:

instana images prune

Installing on a single host

1. Installing the Instana package

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

Ubuntu/Debian

As root, run the following commands to add the repository, and replace <download_key> with your download key:

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 -nv -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

Then, install instana-console by running the following commands:

apt update -y

apt install -y instana-console

To avoid getting major updates during automated upgrades, run the following commands:

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

Red Hat/CentOS

As root, run the following commands to add the repo, and replace <download_key> with your download key:

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

Then, install instana-console by running the following commands:

yum clean expire-cache -y

yum update -y

yum install -y instana-console

If the versionlock plug-in is not installed on your host, run the following command to install the plug-in.

yum install python3-dnf-plugin-versionlock

To avoid getting major updates during automated updates, run the following commands:

yum versionlock add instana-console

2. Installing the Instana backend

Important: 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. Install the Instana backend on your machine by running the following command:

    instana init

    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.

      • Tenant name must match the regular expression pattern ^[a-z][a-z0-9]*$.
      • Tenant name must not exceed a maximum length of 15 characters.
      • Tenant name must begin with an alphabetical character.
      • Tenant name can consist of alphanumeric characters.
      • Characters must be in lowercase.

    • 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. To generate your own self-signed certificates, run the following command, and replace <hostname> with the name of the host where you want to install the Instana backend:

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

  4. Sign in to the Instana UI by using the credentials that are displayed.

  5. After Instana is deployed, activate your license.

Installing on dual hosts

1. Optional: Copying data from existing machine

To migrate from a current installation, you need 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.

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. You need to expose this Docker Daemon port.

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?

To enable Docker engine api on the remote ClickHouse host, follow this instructions:

  • Navigate to /lib/systemd/system in your terminal and open docker.service file vim /lib/systemd/system/docker.service
  • Find the line which starts with ExecStart and adds -H=tcp://0.0.0.0:2376 to make it look like ExecStart=/usr/bin/dockerd -H=fd:// -H=tcp://0.0.0.0:2376
  • Save the modified File
  • Reload the docker daemon systemctl daemon-reload
  • Restart the container sudo service docker restart

4. Installing ClickHouse and Zookeeper on the first host

Interactive

Run the instana init command, select dual-clickhouse as type, and follow the interactive dialog.

Unattended

In the settings.hcl file, adjust type:

  type = "dual-clickhouse"

Install Instana by running the following command:

instana init -y

Securing ClickHouse server by using IPtables

To secure your ClickHouse server in a multihost environment, see the following example. This example ensures that only IO that originates from the Instana backend host has access to the ClickHouse host.

You need to SSH from the Instana backend server to the ClickHouse host afterward. Or you need to provide an extra IP from the box that 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

5. Installing the rest of Instana on the second host

Interactive

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

Unattended

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

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

Install Instana by running the following command:

  instana init -y

What to do next

Monitoring your self-hosted Instana backend

You are recommended to monitor the health of your self-hosted Instana backend by installing an Instana host agent in INFRASTRUCTURE mode. Then, a number of health checks and metrics can be collected for your Instana backend.

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

For more information about installing the host agent, see Installing host agents.

Enabling optional features

Some features are not enabled in a self-hosted backend by default. You can enable such features by using additional configuration options.

For more information about the optional features and how to enable them, see Enabling optional features.

Specifying a private Docker registry

To specify a private Docker registry as the registry for later backend migration or upgrading, run the following commands:

  • Single-host installation:

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

  • Dual-host installation:

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

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