Agent Installation
4.1: Instana Agent Deployment Options
Instana has a variety of agent installation options including the mirror repository and static agents that allow customers to meet strict change control processes. Some of the available options are listed below:
- OS specific installer (Linux, MacOS, Windows, UNIX)
- Container setup
- Docker (and other container managers)
- Kubernetes
- OpenShift
- Hosted Cloud Services
- Serverless component
All above mentioned methods are accessible via the wizard on the Instana UI
If you are unable to access the Instana Web UI you will need to go back through the previous lab and follow all the steps to ensure that the Instana server is up and running.
When installing Instana agent you have to select if you want the agent to be dynamic or static based on whether it can update itself or not. Here is the excerpt from the Instana agent documentation.
A Dynamic host agent downloads on startup the latest set of sensors from repositories. By default, a dynamic agent updates itself daily with the latest and greatest capabilities that are released. It is also possible to tightly control the updating of dynamic host agents by pinning a version
By default, dynamic host agents use the Instana repository to pull updates, but it is possible to set up your own managed mirror. Currently, the mirror must be a Nexus repository. This is probably the best option for must customers because it allows them the benefits of automatic updates, while at the same time controlling the content that is in the repository.
A Static host agent is a self-contained host agent that includes all the latest available components at the time of its release, and has no dynamic update capabilities. The static host agent has a stable "bill of materials" that never changes after the host agent's installation.
Static host agents require no internet connection to the Instana repository, and are recommended in restrictive network setups.
4.2: Installing a local Instana Agent on K3s for self monitoring
Self monitoring the Instana Backend when using the Standard Edition of Instana installed on K3s is very simple.
Open a new terminal tab by selecting File -> New Tab.
SSH to the Instana server with the stanctl cli tool installed:
ssh jammer@instana
Become the root user:
sudo su -
Run the following command:
stanctl agent apply
After a short time you should see the following output:
⠹ Applying instana-agent [5s] ✓
4.3: Installing Instana Agent on a Linux VM
We will start by installing the Instana Agent on the Linux VM that is running IBM MQ and ACE.
Open a new terminal tab by selecting File -> New Tab.
SSH to the ACE/MQ server as follows:
ssh jammer@mqace
When prompted if you want to continue connecting, type: yes
Use sudo to switch to the root user:
sudo -i
After logging into Instana for the first time you will be taken to the Agent Deployment page.
If you aren't on the Agent deployment screen you can get there by selecting the Home menu in the left navigation and then clicking the "Deploy Agent" button near the upper right corner.
A list of different environments where you can install the Instana Agent is shown. For example, on Linux, you can choose a automatic one-liner installation, RPM, or TAR file installation. For OpenShift/kubernetes, you have multiple options including operator, helm, and yaml installs. The easiest method is the default, "Automatic Installation (One-Liner)". The MQACE VM is a Linux server, so select Linux (One-liner).
There are a few other options including the use of different java versions, static vs. dynamic agents, etc. Leave the default settings.
Next, select the checkbox next to "Install and start as service". This will setup the systemctl autostart process and will also start the Agent immediately after it is installed.
Finally, copy and paste the curl command into the root@mqace terminal window
and answer y when prompted.
At this point the Agent is installed and up and running. You can confirm this by running:
ps -ef | grep instana
You should see a process running, the short version looks like this:
root 22012 1 99 12:35 ? 00:00:11 /opt/instana/agent/jvm/bin/java
The Agent will automatically start monitoring the operating system and start discovering key processes and middleware. In many cases it will automatically instrument those technologies. In the case of some technologies (eg. MQ an and App Connect Enterprise), there are manual configuration steps required due to the need to provide credentials for accessing those applications.
4.4: Installing Instana Agent on OpenShift Cluster
The next step is to install the Instana Agent into the Apps Sing Node OpenShift Cluster that in future labs we'll be using to host our demo applications Robot Shop and Quote of the Day.
Throughout this lab, we will be using the "oc" command to run commands within OpenShift. The "oc" command is similar to kubectl for other versions of Kubernetes. There are some minor syntax differences.
Open another tab in your terminal so you are back on the local bastion host admin@bastion-gym-lan.
Check to make sure you are in the right place by running the following:
cd ~
oc cluster-info --kubeconfig kubeconfig-apps
You should see the following output, specifically the url
https:api.sno.techzone.lan:6443. If you don't try opening a new tab or
terminal window and trying again.
Follow the steps below to install the Agent into the cluster:
Set the correct cluster to use:
export KUBECONFIG=~/kubeconfig-apps
Set permissions for the Instana Agent to allow the Agent to have access to monitor the entire cluster:
oc adm policy add-scc-to-user privileged -z instana-agent --kubeconfig kubeconfig-apps
From the Agent deployment screen select OpenShift, Helm chart from the list.
If you aren't on the Agent deployment screen you can get there by selecting the "Stan" robot icon in the upper left corner and then clicking the "Deploy Agent" button near the upper right corner.
Since this OCP cluster will be used for the Quote of the Day and Robot Shop demo application set the following:
- Cluster name:
SNO - Agent Zone:
Demo Apps
Setting these values will allow you to find your Agent and Kubernetes Cluster within the user interface and not get confused by data coming in from other agents.
Zones are used to organize the Instana Agents (and sensors). Many customers create zones for lines of business, data center locations, public cloud regions, etc
Copy the command from the Instana Web UI and run it as the admin user on the bastion host.
Be mindful when copying and pasting to ensure no extra lines are inserted by first copying the command to a text document.
You will see output similar to what's shown below
Next, view a list of the pods that are running in the agent namespace. There will be one pod for each worker node in your target cluster. This SNO cluster only has one worker node so you will only see one pod running.
oc get pods -n instana-agent --kubeconfig kubeconfig-apps
This completes the installation of Instana agent on OpenShift cluster.
4.5: Installing Instana Agent in a Docker Environment
You do not need to perform the actions in this section. This is for your information only. It may be useful if you install Instana using the Classic mode.
If you chose to run the Classic installation of Instana Server you might also want to deploy an Instana Docker agent locally to self monitor the Instana Backend.
You can navigate back to your first tab still logged into the instana host or from a terminal ssh to the Instana server again:
ssh jammer@instana
Switch to root
sudo -i
In the Instana UI, from the Agent deployment screen select Docker this time.
If you aren't on the Agent deployment screen you can get there by selecting the "Stan" robot icon in the upper left corner and then clicking the "Deploy Agent" button near the upper right corner.
At the top of the page you will see an entry box where you can specify a Zone. Specify a zone name such as TechZone. Then, copy the docker run command and paste it into the root@instana terminal window.
This will install the Instana Agent as a docker container running on the Instana Server machine.
Once complete you can issue a docker ps command, you'll see there is a new Instana agent container running.
docker ps | grep agent
Once installed, the Agent will begin to collect host metrics and will discover the various technologies like Cassandra, ClickHouse, ElasticSearch, Nginx, Node.js, and more. Many of these technologies will be monitored automatically without the need for configuration. In some cases, the sensors need to be configured in order to see the performance metrics.
4.6: View Instana Agents in the Instana UI
From the left navigation select Infrastructure.
You should see 3 nodes reporting. The Instana VM, the MQACE VM and the Single Node OpenShift (SNO) VM. If you don't see them yet, give the agents a few minutes to start up.
In an upcoming section we will learn how to update the name of the zone where the MQACE VM resides.
4.7: Troubleshooting Instana Agent Installation on Linux
If you cannot see the Instana or MQACE hosts in the Instana UI you
should read the Instana agent logs on the respective agent host located at
/opt/instana/agent/data/log/agent.log. Look for the current status and any
warnings or errors that may be shown.
4.8: Troubleshooting Instana Agent Installation on Kubernetes Cluster
If you don't see the SNO host in the Demo Apps zone after a couple of minutes, you need to troubleshoot the Instana Agent.
The following must be done from a terminal window on the bastion host (admin@bastion-gym-lan)
Check to make sure that all pods are running. Since Instana agent runs as a DaemonSet the number of pods should be equal to number of nodes in your cluster, in this case one.
oc get pods -n instana-agent --kubeconfig kubeconfig-apps
You can check the Instana Agent pod logs by running:
oc logs $(oc get pods -n instana-agent -o custom-columns=POD:.metadata.name --no-headers --kubeconfig kubeconfig-apps) -n instana-agent -c instana-agent --kubeconfig kubeconfig-apps
4.9: Configuring Proxy
This section is here for informational purposes. There are no steps to execute.
If there is no direct connectivity for the Instana agent you may need to setup a proxy. There are 2 connections with 2 different locations for configuration:
- Connection to Instana Backend - defined in INSTANA-AGENT-DIR/etc/instana/com.instana.agent.main.sender.Backend.cfg
- Connection to Agent/Sensor Repository - defined in INSTANA-AGENT-DIR/etc/mvn-settings.xml (This is used in case client wants to setup internal maven2 mirror repository)
Proxy configuration goes into the respective files. You can also use environment variables
For backend connectivity you have to define INSTANAAGENT_PROXY variables. For repository connectivity you have to define INSTANAREPOSITORY_PROXY variables.
4.10: Configuring Instana Agent
This section is here for informational purposes. There are no steps to execute.
There are multiple ways to configure the Instana agent. These instructions apply
to the Instana Agent installed on a traditional server. Instructions would be
different for docker or kubernetes versions of the Agent. Settings related to
agent functionality reside in configuration.yaml file located by default in
/opt/instana/agent/etc/instana directory. However, other settings related to
agent environment sits in other *.cfg files.
Agent will actually read and use ANY yaml file in that directory.
Some customers choose to have separate yaml files for each key technology. For
example, you could create a mq.yaml file and an ace.yaml file in the same
directory and it would read both files. configuration.yaml will contain sample
configuration entries and comments for ALL available sensors at the time of your
install, BUT it will not automatically add new sensor config as new sensors
become available.
For host based installation you can update configuration.yaml and agent should
pick up changes automatically (no restart required). For Kubernetes based
installations, there is instana-agent configmap where you can customize the
same content that you see in the configuration.yaml file. Using kubernetes/oc
commands, you can edit the configmap.
Instana agent configuration file must be a proper YAML - if your changes are not applied, make sure that it's not a formatting error
4.11: Agent Configuration Troubleshooting
This section is here for informational purposes. There are no steps to execute.
The first place to look when the agent does not start properly or does not work
as expected is agent log file. By default it is located in
/opt/instana/agent/data/log/agent.log . This is the path for a traditional
server.
In case of Kubernetes based deployment you have to look at logs of
instana-agent pods running in instana-agent namespace.
4.12: Configuring GitOps for Agents
This section is here for informational purposes. There are no steps to execute.
If you don't want to modify the Instana agent configuration files for each agent locally, you can setup a centralized git repository for configuration files and instruct Instana agent to use these files. To accomplish that, follow the steps from the documentation.
The Instana agent fetches configuration updates from the remote repository:
- Upon the startup or restart.
- Through a reboot initiated over the Agent Management Dashboard.
- Through a configuration change over the Agent Management Dashboard.
- Through the Web API as described in the Host Agent section and the integrations that rely on it like the GitHub Update Agent action.
Proceed to section 4, where you will install and instrument the Robot Shop application.