Installing the agent on Red Hat OpenShift

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

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

• Instana agent operator (online)
• Instana agent operator (air-gapped)
• Helm chart (online)
• Helm chart (air-gapped)

To install the agent on Red Hat OpenShift on IBM Z or LinuxONE platform, use Helm chart (online).

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.

In a fully air-gapped environment, the cluster nodes cannot pull images directly from icr.io or containers.instana.io. Use a jump host (bastion) with internet access to copy all required images to a private registry that the cluster can access. Then, deploy the operator from the mirrored images.

The steps in this section use a private namespace in IBM Cloud Container Registry (ICR) as the target registry. Any OCI-compliant registry that is reachable from the jump host and from the target cluster works equally well, for example JFrog Artifactory, Red Hat Quay, Harbor, or a self-hosted Distribution registry. If you use a registry other than ICR, skip the ICR-specific steps and substitute your own registry URL and authentication credentials wherever icr.io appears.

[internet] ──pull──▶ jump host ──push──▶ <private-registry>/instana-airgap-mirror ◀──pull── OCP cluster
                      (skopeo)

The scripts/mirror-instana-images.sh script handles mirroring all three components in one invocation:

skopeo --version
jq --version
oc version --client

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 Agents & collectors. On the Instana Agents tab, select Install agents.

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}"
   oc adm policy add-scc-to-user anyuid -z instana-agent-remote -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. When you install the Instana agent on IBM Z or LinuxONE, configure distinct zones during the installation process. This separation is important because both the Instana agent and the application workloads it monitors is within the same cluster.

   Unlike other environments where Instana and the monitored applications are deployed separately, IBM Z or LinuxONE setups share the same cluster. It makes isolating zones essential. To isolate zones, ensure that the nodes where Instana is installed are properly labeled and tainted.

   If the label used is node-role.kubernetes.io/monitor=true. To verify that the Instana nodes are labelled correctly, run the following command:

   kubectl get nodes -l node-role.kubernetes.io/monitor=true

   To verify that the Instana nodes are tainted as expected with the sample taint node.instana.io/monitor=true, run the following command:

   kubectl get nodes -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.taints[*]}{.key}{"="}{.value}{"\t"}{end}{"\n"}{end}' | grep 'node\.instana\.io/monitor'

   After verifying Instana nodes are labelled and tainted, you can follow these steps:

   1. Label application worklad nodes Ensure that the nodes running application workloads are appropriately labeled to differentiate them from infrastructure nodes.

      NODE=<your node name>
      CLUSTER=<your cluster name>
      oc label node worker${NODE}.${CLUSTER_NAME} workload="true"

   2. Define Two Zones

      • Set the Instana nodes to the INFRASTRUCTURE mode.
      • Set the application workload nodes to the APM mode.
      • Create a YAML file agent_values.yaml and speify the zones along with their affinity and tolerations in the file.

      zones:
        - name: workloads
          mode: APM
          affinity:
             nodeAffinity:
             requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                  - matchExpressions:
                      - key: workload
                        operator: Exists
        - name: instana-nodes
          mode: INFRASTRUCTURE
          tolerations:
            - key: node.instana.io/monitor
              operator: Equal
              effect: NoSchedule
              value: "true"
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                  - matchExpressions:
                      - key: node-role.kubernetes.io/monitor
                        operator: In
                        values:
                          - "true"

      In this sample YAML file, it is assumed that the Instana nodes are labeled with node-role.kubernetes.io/monitor=true and tainted with key: node.instana.io/monitor=true. Update these values according to your own node labeling and tainting conventions.

      Append your custom yaml file at the end of agent deployment code as shown in 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}"
      oc adm policy add-scc-to-user anyuid -z instana-agent-remote -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 -f agent_values.yaml

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

       Note:

       If agent.tls.secretName is set, then agent.tls.certificate and agent.tls.key are ignored.

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

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

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["org.opencontainers.image.revision"]')

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}"