Installing the Instana remote agent

Prerequisites

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

When you deploy the remote agent on Red Hat OpenShift, you must add Security Context Constraints (SCC) permissions for the remote agent by running the following command:

oc adm policy add-scc-to-user anyuid -z instana-agent-remote -n instana-agent

On Red Hat OpenShift, the Instana agent requires root access to read and write to specific directories within the container. Without root access, the agent does not start properly. The anyuid SCC grants this necessary permission.

Installing the remote agent on Kubernetes by using the operator

You can use the Kubernetes operator that Instana provides to install the remote agent by using the following steps:

If you're using Red Hat OpenShift, you can deploy the operator using OpenShift's Operator Lifecycle Management (OLM). The Instana Agent Operator is available in the Red Hat Catalog. If you choose this method, you can skip steps 1-3 and continue with step 4 to configure the custom resource.

1. On the home page of the Instana UI, click Set up a data source. On the Instana Agents tab, select Install agents.

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

3. 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 either an InstanaAgent or InstanaAgentRemote 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 the operator YAML to the latest version from the operator's GitHub Releases page.

4. Create and edit a custom resource YAML file instana-agent-remote.yaml by copying the YAML template provided below.

   • The Instana UI provides a YAML template for the standard agent (InstanaAgent), and not the remote agent (InstanaAgentRemote). Therefore, use the following YAML template and only copy your agent key, host agent endpoint, and if required, download key from the Instana UI.
   • Replace <edited-zone> with the agent zone that you want the cluster to be part of. The agent zone is used to customize the zone grouping, which is displayed on the infrastructure map.

   Sensor configurations can be specified either directly in the custom resource YAML file as shown in this example with the CVE sensor, or in the agent.configuration_yaml section as shown in a later example with the Turbonomic sensor.

   apiVersion: instana.io/v1
   kind: InstanaAgentRemote
   metadata:
     name: remote-agent
     namespace: instana-agent
   spec:
     zone:
       name: edited-zone # name of the zone of the host
     agent:
       key: replace-key # replace with your Instana agent key
       endpointHost: ingress-red-saas.instana.io # replace with your Instana endpoint
       endpointPort: "443"
       env: {}
       configuration_yaml: |
         # Remote Sensor Configurations
         # CVE
         com.instana.plugin.cve:
           enabled: true
           concert:
             base_url: '<INSERT_CONCERT_BASE_URL_HERE>'  # Concert base url
             instance_id: '<INSERT_INSTANCE_ID_HERE>'    # Concert instance id
             api_key: '<INSERT_API_KEY_HERE>'            # Concert API Key
             poll_rate: 10
   

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

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

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

   For configuration options, see Additional configuration options.

5. Apply the custom resource YAML file:

   kubectl apply -f instana-agent-remote.yaml
   

   where instana-agent-remote.yaml is the name of your InstanaAgentRemote custom resource YAML file.

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

   The remote agent is installed. For more information about configuring specific plugins, What to do next section.

   To update the remote agent, see Updating an operator installation.

Additional configuration options

See the following additional configuration options:

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

• 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
          # Turbonomic
          com.instana.plugin.turbonomic:
            enabled: true
            host: '<INSERT_TURBONOMIC_SERVER_HERE>'  # Turbonomic Server Host or IP address
            target: '<INSERT_TURBONOMIC_TARGET_NAME>' # Name of the target (Instana Server) as configured in Turbonomic
            auth:
              username: <INSERT_USERNAME_OF_TURBONOMIC_SERVER_HERE>  # User must have administrator, deployer, or automator authority.
              password: <INSERT_PASSWORD_OF_TURBONOMIC_SERVER_HERE>
            tags:
              - 'turbonomic'
    

    For more information, see Configuring host agents by using the agent configuration file.