Installing the host agent on OpenShift

Supported versions

Instana supports Red Hat OpenShift versions that are described in the Life Cycle Phases documentation.

Note: Currently, IBM Cloud OpenShift (ROKS) is the only supported managed OpenShift platform. Other managed OpenShift platforms such as OpenShift in Azure and AWS are not supported.

Installation methods

The installation of the Instana agent on OpenShift is similar to Kubernetes, but you need to complete some extra security steps.

You can install the instana-agent in an OpenShift cluster by using Operator, Helm Chart, or YAML file (DaemonSet).

Choosing the proper installation method

For OpenShift, you are suggested to install the Instana agent by using the operator. In addition, see general Kubernetes documentation for 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 that you are running the latest version of the Operator, Helm Chart, or YAML DaemonSet file.

You can find the version information in the following locations:

Installing by using the Operator

The installation of the operator on OpenShift is similar to Kubernetes, but you need to complete an additional installation method option and some prerequisites steps.

Complete the prerequisites steps before you proceed with installing the operator.

You can use either of the following ways to install the operator:


You need to set up a project for the Instana agent and configure its permissions.

Create the instana-agent project, and set the policy permissions to ensure that the instana-agent service account is in the privileged security context. See the following example commands:

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 later)

In case you do a fresh installation of Instana agent operator version 2.x and later, no additional steps are needed.

Upgrading a 1.x operator to 2.x

If you upgrade the operator from a version 1.x to 2.x, you need to install the cert-manager operator in your cluster. The 2.x operator converts the existing Instana agent CRD into its new format. See the Cert Manager docs for how to install and configure the Cert-Manager properly.

You must first upgrade the Instana agent to version 2.0.9, which includes a webhook conversion to covert existing agent CRs into the newer format. This webhook is removed after version 2.0.9. You can upgrade the Instana agent again to a newer version once the conversion is complete.

Installing operator by using OLM

  1. Install the Instana agent operator from, or OpenShift Container Platform.

  2. If you don't already have one, create the target namespace where the Instana agent is installed. The agent does not need to run in the same namespace as the operator. Most users create a new namespace instana-agent for running the agents.

  3. Follow Step 4 in the Installing Operator Manually section to create the custom resource for the agent and apply the custom resource. The operator will pick up the configuration from the custom resource and deploy the Instana agent.

Configuring operator

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.

Uninstalling the host agent

  1. Uninstall the Instana host agent by removing the custom resource:

    kubectl delete -f instana-agent.customresource.yaml
  2. Uninstall the Operator by running the following command:

    kubectl delete -f

Installing by using the Helm Chart

The Instana agent Helm Chart version 1.2.0 and above supports OpenShift 4.x.

  1. Sign in to the Instana UI, and click More > Agents > Installing Instana Agents > Kubernetes.

    From this page, you need your host agent endpoint and your agent key.

  2. From the Technology list, select Helm chart.

  3. Enter the cluster name and the agent zone (optionally).

    The cluster name (INSTANA_KUBERNETES_CLUSTER_NAME) is the customised name of the cluster that is monitored by this daemonset.

    The agent zone (INSTANA_ZONE) is used to customize the zone grouping that is displayed on the infrastructure map. It also sets the default name of the cluster.

    All of the other required parameters are pre-populated.

  4. Install the Instana agent by running the following command:

    kubectl create namespace instana-agent && \
    helm install instana-agent --namespace instana-agent \
    --repo \
    --set agent.key='<your agent key - as described above>' \
    --set agent.endpointHost='<your host agent endpoint - as described above>' \
    --set'<your-cluster-name>' \
    --set'<your-cluster-name>' \
    --set openshift=true \

To configure the installation, specify the values on the command line by using the --set flag, or provide a yaml file with your values by using the -f flag.

For a detailed list of all the configuration parameters, see Instana Helm Chart.

Uninstalling the host agent

To uninstall the Instana host agent that is installed by using the Helm Chart, run the following command:

helm uninstall instana-agent

Then, all the resources that are related to the host agent are removed.

Installing by using the OpenShift command line

The Instana agent can be installed into OpenShift by following the steps as follows:

You can download a typical instana-agent-openshift.yaml file 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, you can see 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 is sent.

    echo YOUR_INSTANA_AGENT_KEY | base64
  • *endpointHost: The IP address or hostname that is associated with the installation.

  • *endpointPort: The network port that is 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 of the agent endpoints, see 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 (, 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

The resulting image stream is docker-registry.default.svc:5000/instana-agent/instana-agent.

Name: leader-elector

The resulting image stream is docker-registry.default.svc:5000/instana-agent/leader-elector:0.5.4.

Use the respective new image streams in the YAML.

By using the node-selector, you can specify where the instana-agent DaemonSet is deployed. Note that every worker host needs to have an Instana agent. If you configure the node-selector, check whether you can see any conflicts with project nodeSelector and nodeSelector that are defined in instana-agent.yaml.

By using the ConfigMap, you can set up 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 results in unscheduled agent pods. You can see the following error message:

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, it indicated that you missed an additional annotation to make the instana-agent namespace able to schedule pods. Run the following command to add the missing annotation:

oc annotate namespace instana-agent""

Is the ServiceMesh bypass supported for OpenShift ServiceMesh?

Although the OpenShift ServiceMesh is based on Istio, currently tracing workloads that are deployed on the OpenShift ServiceMesh is not supported. This applies to both available versions (1.x and 2.x). This also applies to metrics collection, especially Java workloads and other sensors that require a bi-directional connection from the application pod to the Instana agent.