Installing the host agent on Cloud Foundry

Supported Stemcells

• Ubuntu Trusty
• Ubuntu Xenial
• Ubuntu Bionic
• Ubuntu Jammy

Downloading the Instana agent BOSH release

Instana makes BOSH releases available on our public Artifactory repository. Logging into the repository requires basic HTTP authentication; use _ as username and a valid agent key as password. The download links in the Instana UI have the username and agent key pre-filled for you to use.

To download the Instana agent BOSH release, complete the following steps:

1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

   If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

2. Click the tile Cloud Foundry and BOSH

3. For Step 1: enter the Instana agent BOSH release that you want to download.

   To find the BOSH releases that are available, log in to the public Artifactory repository and then see the release directories.

4. For Step 2: Download the 'instana-agent' release archive.

Uploading the Instana agent BOSH release to the BOSH director

When the agent release archives have downloaded, upload them to the BOSH director by running the following 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 deployments, follow these steps:

1. In the yml document as follows, 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.

Co-locating 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

Notes:

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.