Installing the host agent on OpenShift
- Supported versions
- Installation methods
- Installing by using the Operator
- Installing by using the Helm Chart
- Installing by using the OpenShift command line
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.
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:
Use the Operator Lifecycle Manager (OLM) (preferred on OpenShift).
Create the required resources manually as outlined in Kubernetes.
You need to set up a project for the Instana agent and configure its permissions.
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
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 is 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 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.
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
Uninstall the Instana host agent by removing the custom resource:
kubectl delete -f instana-agent.customresource.yaml
Uninstall the Operator by running the following command:
kubectl delete -f https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml
Installing by using the Helm Chart
The Instana agent Helm Chart version 1.2.0 and above supports OpenShift 4.x.
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.
From the Technology list, select Helm chart.
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.
Install the Instana agent by running the following command:
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 by using the
--set flag, or provide a yaml file with your values by using the
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 (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 is
Name: leader-elector Image: icr.io/instana/leader-elector
The resulting image stream is
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
nodeSelector that are defined in
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 openshift.io/node-selector=""
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.