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

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.

oc login -u system:admin
oc new-project instana-agent
oc adm policy add-scc-to-user privileged -z instana-agent -n instana-agent

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 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 -f flag.

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

helm uninstall instana-agent

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.

Customizing

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 docker-registry.default.svc:5000/instana-agent/instana-agent.

Name: leader-elector
Image: icr.io/instana/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.

FAQ

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

oc annotate namespace instana-agent openshift.io/node-selector=""