Installing the agent on Red Hat OpenShift

You can install the Instana agent on a Red Hat OpenShift cluster by using different methods depending on your requirements. See the following list to check the prerequisite conditions, learn about all the available installation methods, and install the agent on Red Hat OpenShift:

Prerequisites

Before you install the agent, ensure that the prerequisites are met.

Choosing how you want to install the agent

You can install the Instana agent on a Red Hat OpenShift cluster by using the following methods:

Installing by using the operator

To install the Instana agent on Red Hat OpenShift by using the operator, complete the following steps:

Complete the prerequisite steps before you proceed with installing the operator.
Install the operator by using one of the following methods:
- Install the operator by using Operator Lifecycle Manager (OLM) (preferred for Red Hat OpenShift).
- Install the operator manually.

Prerequisites

You must first 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

Installing the operator by using OLM

To install the Instana agent on Red Hat OpenShift by using OLM, complete the following steps:

Install the Instana agent operator from OperatorHub.io or the Red Hat OpenShift catalog of Containerized applications.
If you don't already have a target namespace, create a namespace where the Instana agent must be installed. For example, you can create a namespace instana-agent to run the operator. The agent does not need to run in the same namespace as the operator.
Follow Step 2 to Step 6 in the Installing the 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, complete the following steps:

Deploy the latest operator version by using the following command:
```
kubectl apply -f https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml
```
After you run this command, the operator is up and running in the namespace that you created, and waiting for the instana-agent custom resource to be created.
On the home page of the Instana UI, click Deploy Agent.
On the agent deployment catalog page, click the tile OpenShift - Operator.
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 customized name of the cluster that is monitored by this DaemonSet.

The agent zone (<your_zone_name>) is used to customize the zone grouping, which is displayed on the infrastructure map.
Create a custom resource YAML file by copying the YAML template provided in the Instana UI.

The YAML template is pre-filled with your agent key, host agent endpoint, cluster name, and agent zone.
Edit the custom resource YAML file. For an example of the YAML file, see instana_v1_extended_instanaagent.yaml.
1. The Instana agent custom resource supports the exact same configuration as the Instana Helm chart. For a detailed list of all the configuration parameters and examples, see Instana Helm chart.
  
  Also see the following topics:
2. If you want to install the agent in a self-hosted environment, and the agent key does not have authority to download from the Instana public artifactory, add the download key as downloadKey: <your_download_key>. For example:
```
agent:
  key: wPYpH7EGK0ucLaO0Nu7BYw
  downloadKey: m007YDoWNload6kE42yukg
  endpointHost: ...
```
1. If you want to add TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:
  
  Using existing secret
  
  You can use an existing secret of the type kubernetes.io/tls for TLS encryption. But the agent.tls.secretName must be provided in the custom resource YAML file.
  
  Use a certificate and private key
  
  Instead of an existing secret, a certificate and a private key can be used. The certificate and private key must be base64-encoded.
  
  To use this variant, add the following two parameters to the custom resource YAML file:
  - agent.tls.certificate
  - agent.tls.key
  If agent.tls.secretName is set, then agent.tls.certificate and agent.tls.key are ignored.
2. Optional: You can replace the following values:
  - agent.env: Use this field to specify environment variables for the agent, such as the proxy configuration for the agent. For more possible environment values, see agent configuration. See the following example:
```
spec:
    agent:
      env:
       INSTANA_AGENT_TAGS: staging
```
  - agent.configuration_yaml: Use this field to specify an agent configuration file configuration.yaml. See the following example:
```
spec:
    agent:
      configuration_yaml: |
        # Example of configuration yaml template
        # Host
        com.instana.plugin.host:
          tags:
            - 'dev'
            - 'app1'
```
    For more information, see Configuring host agents by using the agent configuration file.
3. If you want to deploy the static agent, configure the custom resource YAML file with the static agent image. To list the static agent image, set agent.image.name to containers.instana.io/instana/release/agent/static. See the following example:
```
spec:
 agent:
   image:
     name: containers.instana.io/instana/release/agent/static
```
Apply the custom resource YAML file:
```
kubectl apply -f instana-agent.customresource.yaml
```
where instana-agent.customresource.yaml is the name of your custom resource YAML file.

The operator picks up the configuration from the custom resource YAML file and deploys the Instana agent.

Now the agent is installed. For what you can do after the installation, go to the What to do next section.

To update the agent, see Updating an operator installation.

Installing by using the Helm chart

You can use the Helm chart to install the agent. The Helm chart adds the Instana agent to all nodes that can be scheduled in your cluster by using a DaemonSet.

To install the Instana agent by using Helm chart, you must first install or upgrade to Helm version 3.

The Instana agent Helm chart supports Red Hat OpenShift 4.x.

To install the Instana agent on Red Hat OpenShift by using the Helm chart, complete the following steps:

On the home page of the Instana UI, click Deploy Agent.
On the agent deployment catalog page, click the tile OpenShift - Helm chart.
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 customized name of the cluster that is 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 the other required parameters are pre-populated in the agent deployment code, which looks like the following example:
```
oc login -u system:admin
oc new-project instana-agent
oc adm policy add-scc-to-user privileged -z instana-agent -n instana-agent
helm install instana-agent \
--repo https://agents.instana.io/helm \
--namespace instana-agent \
--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
```
Edit the agent deployment code.
- To configure the installation, you can 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 and examples, see Instana Helm chart. Also, see the following topics:
- Optional: To deploy the static agent, set the flag --set agent.image.name=containers.instana.io/instana/release/agent/static.
- The Kubernetes service that is created by default exposes the following items to the cluster:
  - OpenTelemetry endpoint for otlp ingestion over gRPC
  - the implementation of Prometheus' remote_write API
  - Trace Web SDK
  - other Agent APIs.
- Optional: If you want to add TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:
  - Using existing secret of type kubernetes.io/tls
    
    You can use an existing secret of the type kubernetes.io/tls for TLS encryption. But you must specify the secretName with --set 'agent.tls.secretName=<YOUR_SECRET_NAME>' during the installation. The files from the provided secret is then included in the agent.
  - Use a certificate and private key
    
    The certificate and private key must be base64-encoded. To use this variant, run helm install with the following extra parameters:
```
--set 'agent.tls.certificate=<YOUR_CERTIFICATE_BASE64_ENCODED>'
--set 'agent.tls.key=<YOUR_PRIVATE_KEY_BASE64_ENCODED>'
```
    If agent.tls.secretName is set, then agent.tls.certificate and agent.tls.key are ignored.
Copy and then run the agent deployment code.

Now the agent is installed. For what you can do after the installation, go to the What to do next section.

To update the agent, see Updating an operator installation.

Installing by using a static YAML file

Installing the Instana agent by using static YAML is not suggested because it is no longer updated. Instead, you are recommended to install the agent by using the Instana agent operator.

To install the Instana agent in your cluster by using a static YAML file, complete the following steps:

On the home page of the Instana UI, click Deploy Agent.
On the agent deployment catalog page, click the tile OpenShift - YAML.
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 customized name of the cluster that is 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 the other required parameters are pre-populated in the agent deployment code.
Create a custom resource YAML file by copying the YAML template provided in the Instana UI. For example: deployment.yaml.

The YAML template is pre-filled with your agent key, host agent endpoint, cluster name, and agent zone.
Edit the YAML file as required.
- The Instana agent requires the privileged Pod Security Standard. To enforce the Pod Security Standard with a built-in Pod Security Admission controller, run the following command:
```
kubectl label --overwrite ns instana-agent pod-security.kubernetes.io/enforce=privileged
```
- Optional: To deploy for Kubernetes versions before 1.8 with RBAC enabled, replace rbac.authorization.k8s.io/v1 with rbac.authorization.k8s.io/v1beta1 for RBAC API version.
To grant your user the ability to create authorization roles, for example in Google Kubernetes Engine (GKE), run this command:
```
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin --user $(gcloud config get-value account)
```
If you don't enable RBAC, you need to remove ClusterRole and ClusterRoleBinding from the instana-agent.yaml file.
- Optional: To enable a PodSecurityPolicy for the Instana agent, complete the following steps:
  - Create a PodSecurityPolicy resource as defined in Helm chart.
  - Authorize that policy in the instana-agent ClusterRole. You need to enable RBAC with ClusterRole and ClusterRoleBinding resources that are created in the previously mentioned instana-agent.yaml file.
  - Enable the PodSecurityPolicy admission controller on your cluster. For existing clusters, you are recommended to add and authorize policies before you enable the admission controller..
Install the Instana agent within your cluster by running 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 re-apply the agent deployment.

Now the agent is installed. For what you can do after the installation, go to the What to do next section.

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