Installing the host agent on OpenShift

Supported versions

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

Instana host agent supports managed Red Hat OpenShift on IBM Cloud, Microsoft Azure Red Hat® OpenShift® (ARO), and Red Hat® OpenShift® Service on AWS (ROSA). Follow this installation guide to install the Instana host agent on these managed Red Hat OpenShift offerings.

Installation methods

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

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

Choosing the proper installation method

For Red Hat 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 Red Hat OpenShift is similar to Kubernetes, but you need to complete an additional installation method option and some prerequisites steps.

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

  2. Install the Operator by using one of the following methods:

Prerequisites

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 convert 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 the Operator by using OLM

  1. Install the Instana agent Operator from OperatorHub.io, or the Red Hat OpenShift catalog of Containerized applications.

  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 picks up the configuration from the custom resource and deploys the Instana agent.

Installing the Operator manually

To install the Operator manually on Red Hat OpenShift, use the steps described for Kubernetes, except that in the Agent catalog of the Instana UI you click the tile 'OpenShift - Operator' to display the page for installing the Operator on Openshift.

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 https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml

  3. Delete the host agent's cluster level objects. For example, you can identify the cluster level objects by running the following command:

    oc get clusterrole,clusterrolebinding -n instana-agent -o name  | egrep 'instana-agent|k8sen'

Installing by using the Helm chart

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

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile OpenShift - Helm chart

  3. Enter the cluster name and (optionally) the agent zone that you want the cluster to be part of.

    The cluster name (<your_cluster_name>) is the customised name of the cluster monitored by this daemonset.

    The agent zone (<your_zone_name>) is used to customize the zone grouping displayed on the infrastructure map.

    The agent deployment code is updated with the values that you provide. All of the other required parameters are pre-populated in the agent deployment code, which looks like the following:

    helm install instana-agent
--repo https://agents.instana.io/helm \
--namespace instana-agent \
--create-namespace \
--set openshift=true \
--set agent.key='<your_agent_key>' \
--set agent.endpointHost='<your_host_agent_endpoint>' \
--set agent.endpointPort=443 \
--set cluster.name='<your_cluster_name>' \
--set zone.name='<your_zone_name>' \
instana-agent

  4. Copy and then run the agent deployment code with Helm 3.

    To configure the installation, you can specify the values on the command line by using the --set flag or can provide a YAML file with your values by using the -f flag. {: tip} Helm chart.

    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

You can install the Instana host agent into Red Hat OpenShift by following the steps as follows:

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile OpenShift - YAML

  3. Enter the cluster name and (optionally) the agent zone that you want the cluster to be part of.

    The cluster name (<your_cluster_name>) is the customised name of the cluster monitored by this daemonset.

    The agent zone (<your_zone_name>) is used to customize the zone grouping displayed on the infrastructure map.

    The agent deployment code is updated with the values that you provide. All of the other required parameters are pre-populated in the agent deployment code.

  4. Download (or copy and save) the agent deployment code as a YAML file; for example: deployment.yaml.

  5. To install the Instana host agent within your cluster, run the following command:

    kubectl apply -f deployment.yaml

    Where deployment.yaml is the name of the file that you created in the previous step.

    If you make any more edits to the deployment.yaml file, you must recreate the DaemonSet. To apply changes, run the following commands:

    kubectl delete -f deployment.yaml
kubectl apply -f deployment.yaml

For more information about the agent endpoints, see Host Agent Configuration.

Customizing

Depending on your Red Hat 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 Red Hat 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.

Secrets

See Kubernetes secrets for more details.

Checking the status of the host agent

After you install the host agent, you can check the status of the host agent in the Instana UI or on the host. For more information, see Checking the status of the host agent.

FAQ

Why agent pod schedule is failing on OpenShift 3.9?

In Red Hat 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 Red Hat 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.

Troubleshooting agent deployment

If installing the agent is not successful at first, you can check log messages and troubleshooting tips. If this troubleshooting section does not answer the questions you have, contact the IBM Instana support team with information about your experience, so that we can help you and update our documentation accordingly.

For troubleshooting information that is general to all host agents, see Managing host agents / Troubleshooting.

If reinstalling the agent fails with the following message, delete the agent's cluster level objects before reinstalling the agent:

installation Instana Agent failed: rendered manifests contain a resource that already exists. Unable to continue with install: ...

For more information about deleting the agent's cluster level objects, see Uninstalling the agent.