Installing the Host Agent on Cloud Foundry
TABLE OF CONTENTS
- Removing the Instana agent runtime configurations
cf-deploymentv3.0 and above
- BOSH directors version v255.4 and above
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.
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>
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:
- In the
ymldocument below, enter the values for the fields marked
(Optional)that fit your use-case.
- To upload the runtime configuration to the BOSH director, run the
bosh update-runtime-configcommand. After the runtime configuration is updated, all deployments are considered outdated.
- The Director applies the runtime configuration changes to each deployment during the next
bosh deployfor 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.
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:
- Cloud Foundry Dashboards,
- Service mappings based on Cloud Foundry application names (see Service Mappings: Predefined Rules, see
Cloud Foundry application name),
- Some aspects of the integration of Cloud Foundry applications in the Infrastructure map, such as Dynamic Focus and grouping.
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:
- Recommended: Have the Instana agents running on the Cloud Controller virtual machines collect the Cloud Foundry API data via a BOSH runtime configuration
- Spawn a dedicated BOSH
instance_grouprunning Instana agents specially configured to collect data from Cloud Foundry APIs
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
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-clientjob of the
instana-agentBOSH 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.
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
- 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-electionjob from the omonymous
instana-agent-configuration-cf-sensorwill automatically detect the presence of the leadership election mechanism (via its BOSH links) and adopt it transparently.
- 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.
- You will need to create a UAA client and matching client secret with the
cloud_controller.admin_read_onlyauthority, as shown on the Creating and Managing Users with the UAA CLI (UAAC) page of the Cloud Foundry documentation.
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.