Installing the host agent on OpenShift
- Supported Versions
- Installation methods
- Install by using the Operator
- Install by using the Helm Chart
- Install by using the OpenShift command line
- 4.1 to 4.10
The installation of the Instana Agent on OpenShift is similar to Kubernetes, but with some extra security steps required. There are several available methods to install the
instana-agent onto an OpenShift cluster namely via Operator, Helm chart or YAML file (DaemonSet).
Choosing the proper installation method
For OpenShift we propose to install the Instana agent via the Operator. In addition, consult the general Kubernetes documentation regarding the proper installation method.
Current versions of installation methods
New versions of the Operator, Helm chart or YAML DaemonSet file are released fairly frequently. To keep up with the latest updates for fixes, improvements and new features, ensure you are running the latest version of the Operator, Helm chart or YAML DaemonSet file.
This information can be found in the following locations:
Install by using the Operator
The installation of the operator on OpenShift is similar to Kubernetes but with an additional installation method option and some prerequisites
Please perform the prerequisites steps before proceeding with installing the operator. There are two ways to install the operator:
- Using the Operator Lifecycle Manager (OLM) (preferred on OpenShift),
- creating the required resources manually as outlined in Kubernetes.
You need to set up a project for the Instana Agent and configure it's permissions.
instana-agent project and set the policy permissions to ensure the
instana-agent service account is in the privileged security context.
oc login -u system:admin oc new-project instana-agent oc adm policy add-scc-to-user privileged -z instana-agent -n instana-agent
New Installation (Version 2.x and above)
In case you do a fresh Instana Agent Operator installation, no additional steps need to take place.
Upgrading a 1.x operator to 2.x
If you upgrade the operator from a version 1.x to 2.x it requires the
cert-manager operator to be installed in your cluster. This will enable the 2.x operator to convert the existing Instana agent CRD into its new format. See the
Cert Manager docs for how to install and configure the Cert-Manager properly.
Install Operator by using OLM
Install the Instana agent operator from OperatorHub.io, or OpenShift Container Platform.
If you don't already have one, create the target namespace where the Instana agent should be installed. The agent does not need to run in the same namespace as the operator. Most users create a new namespace
instana-agentfor running the agents.
Follow Step 4 in the Install Operator Manually section to create the custom resource for the Agent and install it.
The Instana Agent custom resource supports the exact same configuration as the Instana Helm Chart. For a detailed list of all the configuration parameters, see Helm Chart configuration.
Install by using the Helm Chart
The Instana Agent Helm chart version 1.2.0 and above supports OpenShift 4.x.
Sign in to Instana, click More -> Agents -> Installing Instana Agents -> Kubernetes.
From this page, you'll need your host agent endpoint and your agent key.
From the Technology list, select Helm chart.
Enter the cluster name and (optionally) the agent zone.
The cluster name (
INSTANA_KUBERNETES_CLUSTER_NAME) is the customised name of the cluster monitored by this daemonset.
The agent zone (
INSTANA_ZONE) is used to customize the zone grouping displayed on the infrastructure map. It also sets the default name of the cluster.
All of the other required parameters are pre-populated.
Run the following command with Helm 3:
kubectl create namespace instana-agent && \ helm install instana-agent --namespace instana-agent \ --repo https://agents.instana.io/helm \ --set agent.key='<your agent key - as described above>' \ --set agent.endpointHost='<your host agent endpoint - as described above>' \ --set cluster.name='<your-cluster-name>' \ --set zone.name='<your-cluster-name>' \ --set openshift=true \ instana-agent
To configure the installation, specify the values on the command line using the
--set flag, or provide a yaml file with your values using the
For a detailed list of all the configuration parameters, see our Instana Helm Chart.
Install by using the OpenShift command line
The Instana Agent can be installed into OpenShift by following the steps as follows:
instana-agent-openshift.yaml file can be downloaded form the public GitHub repository. It gets rendered from the Helm chart with typical defaults.
Individual properties are defined as dangling anchors as layed out in the next step.
Download this file and view the latest changelog.
In the YAML file there are the following dangling anchors, which need to be replaced with actual values:
*agentKey: A base64 encoded Instana key for the cluster to which the generated data should be sent
echo YOUR_INSTANA_AGENT_KEY | base64
*endpointHost: The IP address or hostname associated with the installation.
*endpointPort: The network port associated with the installation.
*clusterName: The name to be assigned to your cluster in Instana.
*zoneName: The agent zone to associate with the nodes of your cluster.
For additional details relating to the agent endpoints, refer to the Host Agent Configuration.
Depending on your OpenShift environment you might need do some customizing.
If you cannot pull images from the IBM Cloud Container Registry (icr.io), you need to add two image streams. Open the OpenShift Container Registry, go to the
instana-agent namespace, and add the following image streams:
Name: instana-agent Image: icr.io/instana/agent
The resulting image stream should be:
Name: leader-elector Image: icr.io/instana/leader-elector
The resulting image stream should be:
Use the respective new image streams in the YAML.
With the node-selector you can specify where the instana-agent
DaemonSet should be deployed. Note that every worker host should have an agent install. If you configure the node-selector check if there are any conflicts with project
nodeSelector defined in
With using the
ConfigMap you can setup agent configuration that is necessary for proper monitoring.
See Kubernetes secrets for more details.
Why agent pod schedule is failing on OpenShift 3.9?
In OpenShift 3.9, it can happen that applying a DaemonSet configuration is resulting in unscheduled agent pods. If you see an error message similar to:
Normal SuccessfulCreate 1m daemonset-controller Created pod: instana-agent-m6lwr Normal SuccessfulCreate 1m daemonset-controller Created pod: instana-agent-vchgg Warning FailedDaemonPod 1m daemonset-controller Found failed daemon pod instana-agent/instana-agent-vchgg on node node-1, will try to kill it Warning FailedDaemonPod 1m daemonset-controller Found failed daemon pod instana-agent/instana-agent-m6lwr on node node-2, will try to kill it Normal SuccessfulDelete 1m daemonset-controller Deleted pod: instana-agent-m6lwr Normal SuccessfulDelete 1m daemonset-controller Deleted pod: instana-agent-vchgg
Then you're missing an additional annotation to make the
instana-agent namespace able to schedule pods:
oc annotate namespace instana-agent openshift.io/node-selector=""
Is the ServiceMesh bypass supported for OpenShift ServiceMesh?
Although the OpenShift ServiceMesh is based on Istio, we currently do not support tracing workloads deployed on the OpenShift ServiceMesh. This applies to both available versions (1.x & 2.x). To some extend this also applies to metrics collection, especially Java workloads and other sensors which require a bi-directional connection from the application pod to the Instana agent.