Installing the Host Agent on Kubernetes

Supported Versions

• Instana supports the current stable version of Kubernetes. If the current stable version of Kubernetes is 1.26, the Kubernetes sensor is pinned to version 1.24. According to Kubernetes version compatibility guarantee, Instana supports Kubernetes versions 1.22 to 1.26. However, the lowest 2 versions in that range are considered as a soft deprecation.

Installation methods

You can use several available methods to install the Instana agent onto a Kubernetes cluster. If you install the agent on a host manually, only containers and processes are monitored, and Kubernetes data is not collected. You are recommended to install the agent by using the Operator. Alternative methods are the Helm Chart or YAML file (DaemonSet) deployment.

Install by using the Operator

Instana provides a Kubernetes operator to install and manage the Instana agent.

For configuration options that you can set by using the Instana Agent Custom Resource Definition and environment variables, see Operator configuration.

Install by using the Helm Chart

Via a DaemonSet, the Helm chart adds the Instana agent to all schedulable nodes in your cluster.

1. Sign in to Instana, click More -> Agents -> Installing Instana Agents -> Kubernetes.

   From this page, you'll need your host agent endpoint and your agent key.

2. From the Technology list, select Helm chart.

3. Enter the cluster name and (optionally) the agent zone.

   The cluster name (INSTANA_KUBERNETES_CLUSTER_NAME) is the customised name of the cluster monitored by this daemonset.

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

   All of the other required parameters are pre-populated.

4. Run the following command with Helm 3:

   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>' \
   instana-agent
   

To configure the installation, specify the values on the command line using the --set flag, or provide a yaml file with your values using the -f flag.

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

--set 'agent.tls.certificate=<YOUR_CERTIFICATE_BASE64_ENCODED>'
--set 'agent.tls.key=<YOUR_PRIVATE_KEY_BASE64_ENCODED>'

helm uninstall instana-agent

Install as a DaemonSet

To install and configure the Instana agent as a DaemonSet within your Kubernetes cluster, customize the instana-agent.yaml file to create the instana-agent namespace in which the DaemonSet is created. This enables you to tag agents for quick identification or to stop all of them by deleting the namespace.

1. Sign in to Instana, click More -> Agents -> Installing Instana Agents -> Kubernetes.

2. From the Technology list, select DaemonSet.

3. Enter the cluster name and (optionally) the agent zone.

   The cluster name (INSTANA_KUBERNETES_CLUSTER_NAME) is the customised name of the cluster monitored by this daemonset.

   The agent zone (INSTANA_ZONE) is used to customize the zone grouping displayed on the infrastructure map. It also sets the default name of the cluster.

   All of the other required parameters are pre-populated.

4. Click Copy and save the YAML file.

5. Edit the YAML file, replacing with actual values the following dangling anchors:

   • *agentKey: A base64 encoded Instana key for the cluster to which the generated data should be sent

     echo YOUR_INSTANA_AGENT_KEY | base64
     

   • *endpointHost: The IP address or hostname associated with the installation.

   • *endpointPort: The network port 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.

6. To install Instana within your Kubernetes Cluster, run this command:

   kubectl apply -f instana-agent.yaml
   

   Note: Any additional edits you make to the instana-agent.yaml require that the DaemonSet is recreated. To apply changes, run the following commands:

   kubectl delete -f instana-agent.yaml
   kubectl apply -f instana-agent.yaml
   

kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin --user $(gcloud config get-value account)

kubectl label --overwrite ns instana-agent pod-security.kubernetes.io/enforce=privileged

Configure network access for monitored applications

Some types of applications need to reach out to the agent first. Currently they are

• Node.js
• Go
• Ruby
• Python
• .NET Core

Those applications need to know on which IP the agent is listening. As the agent will listen on the host IP automatically, use the following Downward API snippet to pass it in an environment variable to the application pod:

spec:
  containers:
    env:
      - name: INSTANA_AGENT_HOST
        valueFrom:
          fieldRef:
            fieldPath: status.hostIP

Monitor master nodes

Per default, the agent does not get scheduled on Kubernetes master nodes, as the deployment respects the default taint node-role.kubernetes.io/master:NoSchedule that is set on most master nodes. To overwrite these add the following toleration to the agent daemonset:

kind: DaemonSet
metadata:
  name: instana-agent
  namespace: instana-agent
spec:
  template:
  ...
    spec:
      tolerations:
        - key: "node-role.kubernetes.io/master"
          effect: "NoSchedule"
          operator: "Exists"
    ...

For more direct control install the Agent separately on the master nodes. Please contact support on advice for your environment.

Monitor Kubernetes NGINX Ingress

For guidelines on how to configure the Kubernetes NGINX Ingress and our Agent for capturing NGINX metrics, see the Monitoring NGINX page. Tracing of the Kubernetes NGINX Ingress is also possible via the OpenTracing project, see Distributed Tracing for NGINX Ingress on guidelines how to set that up.

Secrets

Kubernetes has built-in support for storing and managing sensitive information. However, if you do not use that built-in capability but still need the ability to redact sensitive data in Kubernetes resources the agent secrets configuration is extended to support that.

To enable sensitive data redaction for selected Kubernetes resources (specifically annotations and container environment variables), set the INSTANA_KUBERNETES_REDACT_SECRETS environment variable to true as shown in the following agent yaml snippet:

spec:
  containers:
      env:
        - name: INSTANA_KUBERNETES_REDACT_SECRETS
          value: "true"

Then configure the agent with the desired list of secrets to match on as described in the agent secrets configuration.

It is important to note that enabling this capability can possibly cause a decrease in performance in the Kubernetes sensor.

Report to multiple backends

To enable reporting to multiple backends from a Kubernetes agent, see the docker agent configuration.

Instana agent security considerations

Since the Instana agent needs to connect to application pods and list/open own ports on bridge networks on the node it is deployed to, it requires host network access and host level process ID lookup for infrastructure correlation. This is equivalent to the permissions granted on Linux & Unix host environments and requires the following flags as set in the DaemonSet deployment:

• privileged: true provides full access to /proc without overlay, change UID/GID for JVM attachment and access application namespaces.
• hostPID: true provides host level PIDs in /proc, required for infrastructure correlation.
• hostNetwork: true provides access to host level & bridge network interfaces.

In addition, when deploying to OpenShift, the Security Context Constraint (SCC) will be set to privileged to grant the afore mentioned permissions.

The following cluster role rules are required by the Kubernetes sensor to detect all resources and applications running in the Kubernetes cluster and making sure its monitored correctly:

rules:
  - nonResourceURLs:
    - "/version"
    - "/healthz"
    verbs: ["get"]- apiGroups: ["batch"]
    resources:
      - "jobs"
      - "cronjobs"
    verbs: ["get", "list", "watch"]
  - apiGroups: ["extensions"]
    resources:
      - "deployments"
      - "replicasets"
      - "ingresses"
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources:
      - "deployments"
      - "replicasets"
      - "daemonsets"
      - "statefulsets"
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources:
      - "namespaces"
      - "events"
      - "services"
      - "endpoints"
      - "nodes"
      - "pods"
      - "replicationcontrollers"
      - "componentstatuses"
      - "resourcequotas"
      - "persistentvolumes"
      - "persistentvolumeclaims"
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources:
      - "endpoints"
    verbs: ["create", "update", "patch"]
  - apiGroups: ["networking.k8s.io"]
    resources:
      - "ingresses"
    verbs: ["get", "list", "watch"]

Example YAML file

A typical instana-agent.yaml file can be downloaded form Instana 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.