Installing the Instana Agent on BOSH

Deploy the Instana agent using the BOSH release

IMPORTANT: This page is relevant for you only if you use the open-source Cloud Foundry, as opposed to Pivotal Platform (formely known as Pivotal Cloud Foundry), or you use BOSH to deploy software other than Cloud Foundry. If you are using Pivotal Platform and Pivotal Ops Manager, we strongly recommend that you use the Instana Microservices Application Monitoring for Pivotal Platform tile.

Instana makes BOSH releases available via our public Artifactory repository. Logging into the repository requires basic HTTP authentication; use _ as username and a valid agent key as password.

Uploading the Instana agent BOSH release to the BOSH director

When the agent release is downloaded, upload it to the BOSH director by running this command:

bosh upload-release <path/to/agent-bosh-xyz.tar.gz>

Applying the Instana agent runtime configurations

To deploy the Instana agent BOSH release across your foundation, use a BOSH runtime configuration.

To deploy the Instana agent BOSH release across your deploymets, follow these steps:

  1. In the yml document below, enter the values for the fields marked (REQUIRED) and (Optional) that fit your use-case.
  2. To upload the runtime configuration to the BOSH director, run the bosh update-runtime-config command. After the runtime configuration is updated, all deployments are considered outdated.
  3. The Director applies the runtime configuration changes to each deployment during the next bosh deploy for that deployment.
releases:
- name: instana-agent
  version: # (REQUIRED) Fill in the value with the actual release version.
           # For example, if you downloaded the file
           # agent-bosh-1.157.31.tar.gz, the right value is: 1.157.31

addons:
- name: instana-agent-infrastructure
  jobs:
  - name: instana-agent
    release: instana-agent
  properties:
    instana:
      agent: &agent-configuration
        mode: INFRASTRUCTURE
        endpoint: # (REQUIRED) Instana ingress endpoint, e.g., ingress-red-saas.instana.io
        endpoint_port: # (Optional) Instana ingress endpoint port, default is 443
        key: # (REQUIRED) Fill this with the agent key for your Instana tenant unit
        download_key: # (Optional) Download key for downloading agent updates.
                      # This is necessary only in special cases, like running a private update repository.
                      # If not specified, the agent will fall back to the value 'instana.agent.key'.
        zone: # (Optional, advised) the name of the zone of the host.
              # If unspecified, the BOSH deployment id will be used instead.

        # (Optional) Add further configurations for the Agent's configuration.yaml files.
        # Activate support for the JREs used in the latest Java buildpacks
        custom_configuration: |

        # (Optional) Add more environment variables to be passed to the Instana agent.
        # Experimental flags of the Instana agent are activated using environment variables.
        # It is not advised to use these settings unless instructed by Instana's support.
        # Each environment variable must be entered in a text line.
        # This entire stanza can be omitted if there is no proxy between the Instana agents and the Instana backend
        environment: |
          USE_ATTACH_TOOLS=true
        proxy:
          type: # (Optional) Type of proxy to be used by the agent to connect to the Instana backend.
                # Valid values are 'http' (works also for HTTPS proxies), 'socks4' and 'socks5'.
                # Default is to use no proxy.
          host: # (Optional) Hostname of the proxy server, e.g., 'my.proxy' (without protocol).
                # This property is required if a value is set for 'instana.agent.proxy.type', and ignored otherwise.
          port: # (Optional) Port of the proxy server.
                # This property is required if a value is set for 'instana.agent.proxy.type', and ignored otherwise.
          user: # (Optional) User to be used to authenticate against the proxy server.
                # Default is not to use authentication.
                # This property is ignored if 'instana.agent.proxy.type' has no value set.
          password: # (Optional) Password to be used to authenticate against the proxy server.
                    # Default is not to use authentication.
                    # This property is ignored if 'instana.agent.proxy.type' or 'instana.agent.proxy.user' have no value set.
          dns: # (Optional) If set to 'true', DNS will be used to resolve the proxy address.
               # Default is 'true'.
               # This property is ignored if 'instana.agent.proxy.type' has no value set.
          updates:
            mode: dynamic # Whether the agent should update itself dynamically ("dynamic") or not ("static", default).
                          # Default is dynamic.
            dynamic:
              repository:
                hostname: artifact-public.instana.io # The hostname of the repository to tap for updates to agent and sensors.
                                                     # The agent will connect to the repository on port 80 and 443.
                version: # (Optional) Which version of the updates pack to use without further updates (version pinning).
                         # This setting overrides 'instana.agent.updates.dynamic.frequency' and 'instana.agent.updates.dynamic.time'.
                frequency: # (Optional) How often to update the agent.
                           # Valid values are "DAY" (default, means daily updates), "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY" and "SUNDAY".
                           # Default is 'DAY'.
                time: # Time of day when the update is executed, expected in hh:mm format in UTC.
                      # Default is '04:30'.
  include:
    stemcell: &supported-linux-stemcells
    - alias: ubuntu-trusty
      os: ubuntu-trusty
    - alias: ubuntu-xenial
      os: ubuntu-xenial
    - alias: ubuntu-bionic
      os: ubuntu-bionic
    - alias: centos-7
      os: centos-7
  exclude:
    jobs:
    - name: garden
      release: garden-runc
- name: instana-agent-apm
  jobs:
  - name: instana-agent
    release: instana-agent
  properties:
    instana:
      agent:
        <<: *agent-configuration
        mode: APM
  include:
    jobs:
    - name: garden
      release: garden-runc
    stemcell: *supported-linux-stemcells

For more information on the policies surrounding agent updates, see the Agent Versioning and Update Management documentation page.

Configuring the Cloud Foundry Sensor

The Instana agent is capable of retrieving data about Cloud Foundry applications, spaces and organizations from the Cloud Foundry API. Instana uses this information to power Cloud Foundry related features like:

If configured, every Instana agent is capable of collecting the necessary data from the Cloud Foundry API. However, we recommend only one agent to collect the data at any time. When using the PCF tile, we automate the collection by one Instana agent transparently, employing a leadership election mechanism to have multiple Instana agents in hot-standby to collect Cloud Foundry API data; this ensures continuity of the data retrieval over, for example, the rolling updates of BOSH deployments. However, when deploying the Instana agent directly via BOSH, the set up of the Cloud Foundry sensor needs to be expressly configured, and we support the following ways of doing so:

  1. Recommended: Have the Instana agents running on the Cloud Controller virtual machines collect the Cloud Foundry API data via a BOSH runtime configuration
  2. Spawn a dedicated BOSH instance_group running Instana agents specially configured to collect data from Cloud Foundry APIs

Co-locate on Cloud Controller machines

The following runtime configuration is going to enable the Instana agents running on the various instances of the Cloud Controller to collect the Cloud Foundry API data, coordinating which Instana agent does it at any one time through a leadership election mechanism provided by the instana-leadership-election release:

releases:
- name: instana-agent
  version: # (REQUIRED) Fill in the value with the actual release version.
           # For example, if you downloaded the file
           # agent-bosh-1.157.31.tar.gz, the right value is: 1.157.31
- name: instana-leadership-election
  version: # (REQUIRED) Fill in the value with the actual release version.
           # The version is usually the same as the 'instana-agent' BOSH release,
           # as we always release both in lock-step for a simpler user-experience.

addons:
- name: instana-cf-sensor
  jobs:
  - name: instana-agent-configuration-cf-sensor
    release: instana-agent
  - name: instana-leadership-election
    release: instana-leadership-election
  properties:
    cf:
      uaa:
        client: # (REQUIRED) A UAA client that has the 'cloud_controller.admin_read_only' authorities
        client_secret: # (REQUIRED) Client secret matching the above client
  include:
    jobs:
    - name: cloud_controller_ng
      release: capi

As you see above, the Instana agent needs a client for Cloud Foundry’s User Account and Authorization (UAA) with the cloud_controller.admin_read_only authority, which can be created either:

  • Manually, as shown on the Creating and Managing Users with the UAA CLI (UAAC) page of the Cloud Foundry documentation.
  • Recommended: Automatically using the instana-ensure-uaa-client job of the instana-agent BOSH release using the following, additional BOSH runtime configuration:
releases:
- name: instana-agent
  version: # (REQUIRED) Fill in the value with the actual release version.
           # For example, if you downloaded the file
           # agent-bosh-1.157.31.tar.gz, the right value is: 1.157.31

addons:
- name: instana-ensure-uaa-client
  jobs:
  - name: instana-ensure-uaa-client
    release: instana-agent
  properties:
    cf:
      uaa:
        client: # (REQUIRED) This entry must match the one of the `cf.uaa.client` property of the `instana-cf-sensor` runtime configuration
        client_secret: # (REQUIRED) This entry must match the one of the `cf.uaa.client_secret` property of the `instana-cf-sensor` runtime configuration
  include:
    jobs:
    - name: uaa
      release: uaa

The recommended method using the instana-ensure-uaa-client job has the added benefit to ensure that the UAA client is re-created automatically if deleted by mistake. Notice that the instana-ensure-uaa-client needs to be located on the virtual machines running the uaa job, in order to use the credentials available there.

Dedicated instance group

It is possible to deploy dedicated Instana agents configured to run the Cloud Foundry sensor by creating a dedicated BOSH instance group. We do not recommended it, however, as it leads to a significant waste of computing resources: the work the sensor does is lightweight and it is simply overkill to allot dedicated virtual machines for it. Anyhow, the following runtime configuration will yield a instance group with one dedicated virtual machine:

---
name: instana-cf-sensor

stemcells:
- alias: &stemcell_name bosh-aws-xen-hvm-ubuntu-xenial-go_agent
  os: ubuntu-xenial
  version: "621.29"

releases:
- name: instana-agent
  version: <instana-agent-bosh-release-version>

instance_groups:
- name: instana-cf-sensor
  azs:
    ...
  instances: 1
  jobs:
  - name: instana-agent-configuration-cf-sensor
    release: instana-agent
    properties:
      cf:
        api:
          url: <TODO> # e.g., https://api.sys.mypcf.qainfra.instana.io
        uaa:
          url: <TODO> # e.g., https://uaa.sys.mypcf.qainfra.instana.io
          client: <TODO>
          client_secret: <TODO>
  vm_type: t3.micro
  stemcell: *stemcell_name
  networks:
  # Your network setup may look different
  - default:
    - dns
    - gateway
    name: instana-cf-sensor

update:
  canaries: 1
  canary_watch_time: 30000-300000
  max_errors: 2
  max_in_flight: 1
  serial: false
  update_watch_time: 30000-300000

Notice that:

  1. This instance group contains one instance. If you want to scale it to more than one instance, to be resilient across rolling updates, you should additionally deploy on the machines the instana-leadership-election job from the omonymous instana-leadership-election release. The instana-agent-configuration-cf-sensor will automatically detect the presence of the leadership election mechanism (via its BOSH links) and adopt it transparently.
  2. You will need to configure manually the URI of the UAA and Cloud Foundry APIs. This means that you could technically run this deployment in a completely different network and even availability zone from the ones used by the Cloud Foundry deployment.
  3. You will need to create a UAA client and matching client secret with the cloud_controller.admin_read_only authority, as shown on the Creating and Managing Users with the UAA CLI (UAAC) page of the Cloud Foundry documentation.

Removing the Instana agent runtime configurations

To remove the Instana runtime configuration, upload the following by running the bosh update-runtime-config command:

releases: []
addons: []

After updating the runtime configuration, the Instana agent BOSH release is removed during the next bosh deploy for each deployment. When all deployments have been updated to remove the Instana agent BOSH jobs, we recommend that you run the bosh clean-up command to remove the now unnecessary release and its artifacts from the BOSH Director.