Installing 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:

• Instana agent operator
• Helm chart (online)
• Helm chart (air-gapped)
• Static YAML file (This method is deprecated and is planned to be removed soon.)

Installing by using the operator

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

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

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

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

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:

1. On the home page of the Instana UI, click Deploy Agent.

2. On the agent deployment catalog page, 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 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:

   INSTANA_AGENT_NAMESPACE=instana-agent
   oc login -u system:admin
   oc new-project ${INSTANA_AGENT_NAMESPACE}
   oc adm policy add-scc-to-user privileged -z instana-agent -n "${INSTANA_AGENT_NAMESPACE}"
   helm install instana-agent \
   --repo https://agents.instana.io/helm \
   --namespace ${INSTANA_AGENT_NAMESPACE} \
   --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. 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:

     • Configuring additional backends
     • Configuring a proxy between the Instana agents and the Instana backend
     • Defining custom Kubernetes volumes and volumeMounts

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

5. 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 Helm chart in an air-gapped environment

Red Hat OpenShift provides an internal container registry that you can use in air-gapped environments to store images to run workloads in the cluster.

Make sure that you install the following software before installing the agent:

• OpenShift CLI (oc)
• jq
• skopeo

The following steps are tested on Red Hat Enterprise Linux 9.4, and are applicable to most Linux distributions.

To install the Instana agent by using Helm chart in an air-gapped environment, complete the following steps:

1. Log in to the Red Hat OpenShift cluster as administrator by running the following command:

   oc login --server=https://api.myopenshiftcluster.com:6443 -u kubeadmin -p $OPENSHIFT_PASSWORD 
   

2. Expose the internal container registry to be accessible from your jump host:

   oc patch configs.imageregistry.operator.openshift.io/cluster --type merge -p '{"spec":{"defaultRoute":true}}'
   

3. Retrieve the hostname that is used to access the registry externally:

   HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')
   

4. Create a project 'instana' (if it is not created earlier) in the Red hat OpenShift cluster to enable pushing images to the specified namespace:

   oc get project instana || oc new-project instana
   

5. Display the registry host information:

   echo "${HOST}" # default-route-openshift-image-registry.apps.myopenshiftcluster.com
   

6. Obtain the certificate of the trusted ingress operator and add it in the certificate authority (CA) directory of the system:

   oc extract secret/$(oc get ingresscontroller -n openshift-ingress-operator default -o json | jq '.spec.defaultCertificate.name // "router-certs-default"' -r) -n openshift-ingress --confirm
   

   Failing this step might result in certificate warnings (for example, tls: failed to verify certificate: x509: certificate signed by unknown authority) when you try to push the image to the target registry.

7. Import the CA into the system's trusted certificate authority store by using the following commands:

   sudo mv tls.crt /etc/pki/ca-trust/source/anchors/
   sudo update-ca-trust
   

8. Log in to both the source and destination registries by using Skopeo:

   skopeo login -u kubeadmin -p $(oc whoami -t) $HOST
   skopeo login -u _ -p $AGENT_DOWNLOAD_KEY containers.instana.io
   

9. Determine the latest versions available for each component:

   LATEST_OPERATOR_VERSION=$(skopeo inspect docker://icr.io/instana/instana-agent-operator:latest | jq -r ".Labels.version")
   LATEST_AGENT_VERSION=$(skopeo inspect docker://containers.instana.io/instana/release/agent/static:latest | jq -r ".Labels.version")
   LATEST_K8S_SENSOR_VERSION=$(skopeo inspect docker://icr.io/instana/k8sensor:latest | jq -r '.Labels["com.instana.commit.id"]')
   

10. Copy the required components to the local registry:

    skopeo copy docker://icr.io/instana/instana-agent-operator:latest "docker://${HOST}/instana/instana-agent-operator:${LATEST_OPERATOR_VERSION}"
    skopeo copy docker://containers.instana.io/instana/release/agent/static:latest "docker://${HOST}/instana/instana-agent-static:${LATEST_AGENT_VERSION}"
    skopeo copy docker://icr.io/instana/k8sensor:latest "docker://${HOST}/instana/k8sensor:${LATEST_K8S_SENSOR_VERSION}"
    

Installing by using a static YAML file

Installing the Instana agent by using static YAML method is deprecated and is planned to be removed in the future versions of Instana. Instead, you are suggested 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:

1. On the home page of the Instana UI, click Deploy Agent.

2. On the agent deployment catalog page, 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 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.

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

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

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