Installing the Host Agent on Cloud Foundry

Supported Versions

  • cf-deployment v3.0 and above
  • BOSH directors version v255.4 and above

Supported Stemcells

Deploy the Instana agent using the BOSH release

Note: This page is relevant for you only if you use the open-source Cloud Foundry, as opposed to Pivotal Platform (formerly 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:
          tanzu:
            foundation:
              id: # (REQUIRED) A technical ID to identify this foundation
              name: # (REQUIRED) A name to identify this foundation
          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, not advised) the name of the zone of the host.
                # If unspecified, the value of `tanzu.foundation.name` 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 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 ZooKeeper 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: zookeeper
    version: "0.0.10"
    url: "https://bosh.io/d/github.com/cppforlife/zookeeper-release?v=0.0.10"
    sha1: "a6d227abceebf1e3e68ce4a3cabf68b0b93165d2"

addons:
  - name: instana-cf-sensor
    jobs:
      - name: instana-agent-configuration-cf-sensor
        release: instana-agent
        properties:
          tanzu:
            foundation:
              id: # (REQUIRED) A technical ID to identify this foundation
              name: # (REQUIRED) A name to identify this foundation
          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
      - name: zookeeper
        release: zookeeper
        properties:
          leader_serves: "yes"
          # 42600 is the legacy leadership election port and we wanna avoid incompatibilities over update
          leader_election_port: 42601
          quorum_port: 42602
    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 ZooKeeper job from the homonymous ZooKeeper 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.