Installing the agent on Kubernetes

You can install the Instana agent in an online or offline (air-gapped) environment in a Kubernetes cluster. See the following list to check the prerequisite conditions, learn about all the available installation methods, and install the agent on Kubernetes.

Prerequisites

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

Choosing how you want to install the agent

Choose one of the following installation options, and then click the associated link to continue:

Installing the agent in an air-gapped environment

You can install the agent in an air-gapped environment by using two methods:

Install by using Helm chart in an air-gapped environment

To install the agent in an air-gapped environment, complete the following steps:

In the following installation steps, the CentOS Linux distribution is used, but the steps are valid for all the other supported distributions.

  1. Install Docker by running the following commands:

    sudo yum install -y yum-utils
    
    sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
    
    sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    
    sudo systemctl start docker
    
  2. Install Helm by running the following commands:

    sudo su
    
    yum install -y epel-release
    
    yum install -y snapd
    
    systemctl enable --now snapd.socket
    
    ln -s /var/lib/snapd/snap /snap
    
    snap install helm --classic
    PATH="$PATH:/snap/bin/"
    
    helm version
    
  3. Install Minikube by completing the following steps:

    These steps serve as an example to show the target environment.

    1. Add the Kubernetes repository:

      cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
      [kubernetes]
      name=Kubernetes
      baseurl=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/
      enabled=1
      gpgcheck=1
      gpgkey=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/repodata/repomd.xml.key
      exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
      EOF
      
    2. Install the kubectl command line tool:

      sudo yum install -y kubectl
      
    3. Download the Minikube RPM package:

      curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm
      
    4. Install the Minikube RPM package:

      sudo rpm -Uvh minikube-latest.x86_64.rpm
      
    5. Start a Kubernetes cluster by using Docker:

      minikube start --force --driver=docker
      
    6. Set up the Docker environment so that it can be used with Minikube:

      eval $(minikube docker-env)
      
    7. Check the Kubernetes cluster:

      kubectl cluster-info
      
  4. Pull the necessary Docker images for transfer to an air-gapped environment:

    1. Log in to the Instana Container Registry with your agent key:

      docker login https://containers.instana.io/v2 -u _ -p <agentKey>
      
    2. Pull the latest version of the agent from the Instana Container Registry:

      docker pull containers.instana.io/instana/release/agent/static:latest
      
    3. Pull the latest version of the Instana Kubernetes sensor:

      docker pull icr.io/instana/k8sensor:latest
      
    4. Log out of the Docker registry:

      docker logout
      
    5. Convert the Docker images into .tar files:

      docker images
      
      docker tag <instanaAgentImageID> instana/agent
      
      docker save instana/agent > instana-agent.tar
      
      docker tag <k8SensorID> instana/k8sensor
      
      docker save instana/k8sensor > instana-k8sensor.tar
      
    6. Copy files (instana-agent.tar and instana-k8sensor.tar) to the air-gapped host where you want to install the agent.

    7. Delete current images from the air-gapped host:

      docker rmi -f <instanaAgentImageID> <k8SensorID>
      
    8. Import images from .tar files (instana-agent.tar and instana-k8sensor.tar):

    docker load --input instana-agent.tar
    
    docker load --input instana-k8sensor.tar
    
  5. Run the Docker registry server and push images:

    docker run -d -p 5000:5000 --restart=always --name registry registry:2
    
    docker tag instana/agent:latest localhost:5000/instana-agent
    
    docker push localhost:5000/instana-agent
    
    docker tag instana/k8sensor:latest localhost:5000/instana-k8sensor
    
    docker push localhost:5000/instana-k8sensor
    
    #Delete all images related to the agent:
    docker rmi -f <instanaAgentImageID> <k8SensorID>
    
  6. Pull Instana Helm charts from the following repository:

    helm pull instana-agent --repo https://agents.instana.io/helm --untar instana-agent
    

    Check for the latest Instana agent Helm chart file in your current directory.

  7. Deploy the Instana agent into the Kubernetes cluster.

    Instana agent Helm charts version 2.0.0 and earlier do not have the instana-agent/crds folder. Therefore, the kubectl apply -f instana-agent/crds step is not required.

    kubectl apply -f instana-agent/crds && helm upgrade --install --create-namespace \
       --namespace instana-agent \
       --set agent.key=<agentKey> \
       --set agent.endpointHost=ingress-red-saas.instana.io \
       --set agent.endpointPort=443 \
       --set cluster.name='mip-back-test' \
       --set zone.name='mip-gke-zone' \
       --set k8s_sensor.deployment.enabled=true \
       --set k8s_sensor.image.name=localhost:5000/instana-k8sensor \
       --set k8s_sensor.image.tag=latest \
       --set k8s_sensor.image.pullPolicy=IfNotPresent  \
       --set agent.image.name=localhost:5000/instana-agent \
       --set agent.image.tag=latest \
       --set agent.image.pullPolicy=IfNotPresent  \
       instana-agent instana-agent/
    

    Enter <agentKey>, and edit <agent.endpointHost>, <agent.endpointPort>, <k8_senosr.image.name>, and <agent.image.name>. Also, replace instana-agent-1.2.61.tgz with the latest Instana agent Helm chart file in your directory.

  8. Check your pods with the following command:

    kubectl get all -n instana-agent
    

The agent is installed. For more information about the next steps, see the What to do next section.

Install by using an operator in an air-gapped environment

To install the agent in an air-gapped environment using an operator, complete the following steps:

  1. Pull the following images.

    docker pull containers.instana.io/instana/release/agent/static:latest
    docker pull icr.io/instana/k8sensor:latest
    docker pull icr.io/instana/instana-agent-operator:latest
    
  2. Re-tag pulled images to a local image registry.

    docker tag <public-image> <local-registry-image>
    
  3. Push re-tagged images to the local image registry.

    docker push <local-registry-image>
    
  4. Create an image pull secret (Docker secret) in your target Kubernetes namespace:

    kubectl create secret -n instana-agent docker-registry local-registry-image-pull-secret \
         --docker-server=<your_local_image_registry> \
         --docker-username= # Replace with ARTIFACTORY_USERNAME \
         --docker-password= # Replace with ARTIFACTORY_PASSWORD 
    
  5. Fetch the YAML from GitHub:

    curl -L -o instana-agent-operator.yaml https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml
    
  6. Replace image reference with the private registry. For example, icr.io/instana/instana-agent-operator:2.1.8 with a private registry operator image.

  7. Apply the configuration to deploy the operator.

    kubectl apply -f instana-agent-operator.yaml
    
  8. If you do not have OpenShift CLI (oc) installed, you can download it from Getting started with the OpenShift CLI and patch the service account to have access to the image pull secret that you created in the previous section:

    oc patch serviceaccount instana-agent-operator -p '{"imagePullSecrets": [{"name": "local-registry-image-pull-secret"}]} -n instana-agent'
    
  9. Create a file agent.yaml and update the agent custom resource to specific image versions:

    apiVersion: instana.io/v1
    kind: InstanaAgent
    metadata:
      name: instana-agent
      namespace: instana-agent
    spec:
      zone:
        name: # (optional) name of the zone of the host
      cluster:
        name: # cluster name.
      agent:
        image:
          name: # private registry static agent image.
          tag: # agent tag
          pullSecrets:
            - name: local-registry-image-pull-secret
        key: # fetch the download key from the Instana UI > Agents > Install Agent > Kubernetes Operator
        endpointHost: <your-ingress-endpoint>
        endpointPort: "443"
        env: {}
        configuration_yaml: |
          # You can leave this empty, or use this to configure your instana agent.
          # See https://docs.instana.io/setup_and_manage/host_agent/on/kubernetes/
      k8s_sensor:
        image:
          name: # private registry k8 sensor image.
          tag: # k8 sensor tag
    
  10. Deploy the custom resource:

$ kubectl apply -f agent.yaml
  1. Watch for all pods starting correctly.

The agent is installed. For more information about the next steps, see to the What to do next section.

Installing the agent in an online environment

You are recommended to use the following methods to install the Instana agent onto a Kubernetes cluster:

If you are reinstalling the agent, ensure that the agent has been cleanly uninstalled, including deleting all the agent's cluster level objects. For more information, see Uninstalling the Instana agent on Kubernetes.

New versions of the Operator, Helm chart, and YAML file are released fairly frequently. To keep up with the latest updates for fixes, improvements, and new features, ensure that you are running the current version of either Operator, Helm chart or YAML file.

To find the current version of the Operator, Helm chart, or YAML file, see the following topics:

Install by using the operator

You can use the Kubernetes operator that Instana provides to install the agent. Follow the steps:

  1. Deploy the Operator as follows. The command installs the latest Operator.

    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 instana-agent, and waiting for an instana-agent custom resource to be created.

    The latest tag for the Instana agent Operator image in DockerHub and the Red Hat Registry is not supported.

    To get a new version of the Instana Agent Operator, update to the latest Operator YAML from the Operator's GitHub Releases page as mentioned previously.

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

  3. On the agent deployment catalog page, click the tile Kubernetes - Operator.

  4. Enter the cluster name and the agent zone (optionally) 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.

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

  6. Edit the custom resource YAML file:

    • 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 the Helm chart configurations.

    • 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>. See the following example:

      agent:
        key: wPYpH7EGK0ucLaO0Nu7BYw
        downloadKey: m007YDoWNload6kE42yukg
        endpointHost: ...
      
    • If you want to add TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:

      • Use an existing secret

        You can use an existing secret of the type kubernetes.io/tls for TLS encryption. But you must provide agent.tls.secretName in the custom resource YAML file.

      • Use a certificate and private key

        The certificate and private key must be base64-encoded. To use this variant, add the following 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.

    • If you want to deploy the static host agent, configure the custom resource YAML file with the static agent image. To list the static host 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
      
    • 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.

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

The agent is installed. For more information about the next steps, see to the What to do next section.

To update the agent, see Updating an operator installation.

Install by using the Helm chart

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

To install the Instana agent using a Helm chart, you must first install or upgrade your local helm CLI to version 3.

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

To install the agent by using 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 Kubernetes - 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, which 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.

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

    helm install instana-agent
    --repo https://agents.instana.io/helm \
    --namespace instana-agent \
    --create-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, see Instana Helm chart.

    • If you want to deploy the static host agent, set the flag --set agent.image.name=containers.instana.io/instana/release/agent/static.

    • If you want to set up TLS encryption for the agent endpoint, use an existing secret or use a certificate and private key:

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

The agent is installed. For more information about the next steps, see to the What to do next section.

To update the agent, see Updating an operator installation.

Install 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 suggested to install the agent by using the Instana agent operator.

To install the agent by using a 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 Kubernetes - 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, which is 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. 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.4

  5. Edit the YAML file based on your needs:

    • Instana host 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:

      1. Create a PodSecurityPolicy resource as defined in Helm chart.

      2. Authorize that policy in the instana-agent ClusterRole. You need to enable RBAC with the ClusterRole and ClusterRoleBinding resources that are created in the previously mentioned instana-agent.yaml file.

      3. Enable the PodSecurityPolicy admission controller in your cluster. For existing clusters, you are recommended to add and authorize policies before you enable the admission controller.

  6. Install the agent within your Kubernetes cluster by running the following command:

    kubectl apply -f deployment.yaml
    

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

    If you make any more edits to the deployment.yaml file, you must re-create the DaemonSet by running the following commands:

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

The agent is installed. For more information about the next steps, see to the What to do next section.