Installing the Instana Agent on BOSH

Installing the Instana agent BOSH release on Cloud Foundry

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). 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., saas-us-west-2.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.

Since the BOSH release 1.161.0+rc1, the Instana agents can collect data about Cloud Foundry applicstions via the Cloud Controller API, which power the Cloud Foundry dashboards and the Infrastructure Map integration, and require in addition the instana-leadership-election release and the following runtime configurations:

- name: instana-pas-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

The UAA client needs to be manually created beforehand, see Creating and Managing Users with the UAA CLI. The runtime configurations above will make the Instana agents running on the Cloud Controller nodes collect the information. It is also possible to spawn a dedicated instance group to do so.

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.