Deploy OneAgent on Cloud Foundry for full-stack monitoring

The following guidelines apply to the deployment of OneAgent to Cloud Foundry VMs, including Cloud Foundry components, Diego cells, and Windows Diego cells.

Before you begin

You'll need to

acquire DESK environment credentials.
review the list of supported applications and versions.
enable Garden and Winc for Windows Server container monitoring (Go to Settings > Process and containers > Container monitoring and in the Automatic container injection for deep monitoring section, enable the Garden containers and Winc for Windows Server containers switches.)
get the BOSH CLI
ensure you have access to the BOSH Director

Deployment instructions

There are two deployment approaches to deploy the OneAgent BOSH release: immutable and lightweight. Refer to OneAgent BOSH release page to decide which approach is right for you.

Immutable release lightweight release

Deploying the immutable OneAgent BOSH release

Get your environment ID and the PaaS token for your DESK environment.

How to get your environment ID and PaaS token

Environment ID

Login with your DESK account.
Select Deploy DESK from the navigation menu.
Click the Set up PaaS integration button. Your environment ID appears in the Environment ID text box.
Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.

API Token

The API token is used in combination with your environment ID to download OneAgent. Go to Deploy DESK > Set up PaaS integration to access the InstallerDownload token. For security reasons, it's recommended that you create a discrete token for each environment.

To generate a new token

Click the Generate new token button.
Type in a meaningful name for your token. A meaningful token name might be the name of the platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing tokens, go to Settings -> Integration -> Platform as a Service.
Click Generate to create the token. The newly created token will appear in the list below.
Click Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and clicking Show token next to the relevant PaaS token.

Deploy an Environment ActiveGate (SaaS customers only) according to the installation instructions.

Locate the download URLs located in the Environment API.

How to get deployment URLs

To download your DESK release via the command line

Select the user menu in the menu bar.
Click Environment API.
Select Deployment.

Get the latest versions of the BOSH release.

 curl -X GET https://{api-url}/api/v1/deployment/boshrelease/versions/unix -H /
 'Authorization: Api-Token {paas-token}'

Download the BOSH release.

DESK SaaS customers replace {api-url} with the address of the environment ActiveGate.

wget  -O desk-release.tgz --header="Authorization: Api-Token {paas-token}" /
https://{api-url}/api/v1/deployment/boshrelease/agent/unix/version/{version}?skipMetadata=true

Download Windows BOSH release

wget  -O desk-release.tgz --header="Authorization: Api-Token {paas-token}" /
https://{api-url}/api/v1/deployment/boshrelease/agent/windows/version/{version}?skipMetadata=true

Confirm the checksum of the release

DESK SaaS customers replace {api-url} with the address of the environment ActiveGate.

curl -H "Authorization: Api-Token {paas-token}"  /
https://{api-url}/api/v1/deployment/boshrelease/agent/windows/version/{version}/checksum?skipeMetadata=true

# this results in a response as follows (example):
{"sha256":"13658655d922aedc93951b545e8b881b76a77545ba6f8442828cfed53ffac3a8"}

# use the sha256 value to check against the file:
echo "13658655d922aedc93951b545e8b881b76a77545ba6f8442828cfed53ffac3a8 desk-release.tgz" | sha256sum -c

# if the checksum matches the response is:
desk-release.tgz: OK

# if the checksum does not match:
# desk-release.tgz FAILED
# sha256sum: WARNING: 1 computed checksum did NOT match

Ensure that your bosh CLI is successfully connected to the BOSH director. For details, please refer to Cloud Foundry documentation or Pivotal documentation.

Upload the BOSH release of OneAgent to the BOSH Director:

bosh -e my-env upload-release PATH-TO-BINARY/desk-release.tgz

Run the following command to retrieve your tenanttoken:

curl "https://{your-active-gate-url}/e/{environmentid}/api/v1/deployment/installer/agent/connectioninfo?Api-Token={paas-token}" -k

Create a runtime config named runtime-config-desk.yml with the appropriate settings for your environment.

Manifest runtime-config-desk.yml file

Download

releases:
- name: desk-oneagent
  version: 1.177.143
  #specify version of latest release

addons:
- name: desk-oneagent-addon
  jobs:
  - name: desk-oneagent
    release: desk-oneagent
  include:
    stemcell:
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
  properties:
    desk:
      environmentid: <environmentId>
      ###
      # The following keys are required for 1.177+ immutable OneAgent release
      server: https://{your-cluster-url.com}
      tenanttoken: <tenanttoken>
      ###
      # optional properties below
      ###
      # Set to 'all' if you want to accept all self-signed SSL certificates.
      sslmode: all
      # Specify a direct download URL for DESK OneAgent.
      # If this propery is set, BOSH will download OneAgent from this location.
      downloadurl: https://direct-download-url-for-agent
      # Specify the proxy to be used for communication.
      proxy: https://your-proxy-url
      # Specify in which hostgroup the VMs in this deployments belong
      hostgroup: example_hostgroup
      # Define host tags for the VMs in this deployment
      hosttags: landscape=production team=my_team
      # Define custom properties for the VMs in this deployment
      hostprops: Department=Acceptance Stage=Sprint
      # Enable cloud infrastructure monitoring mode.
      # Set this to 1 to activate it
      infraonly: 0

#optional: extra addon configuration for Windows cells
- name: desk-oneagent-windows-addon
  jobs:
  - name: desk-oneagent-windows
    release: desk-oneagent
  include:
    stemcell:
    - os: windows2016
  properties:
    desk:
      environmentid: <environmentid>
      server: https://{your-active-gate-url}/
      tenanttoken: <tenanttoken>
      # All of the optional properties for the Linux addon shown above (for example, apiurl, hostgroup) can also be used here.

Notice there is a job defined for Linux (desk-oneagent) and a seperate one for Windows (desk-oneagent-windows).

Update the BOSH Director runtime configuration

bosh -e my-env update-runtime-config PATH/runtime-config-desk.yml

where PATH denotes the path to the runtime-config-desk.yml file.

This runtime configuration applies to all new BOSH deployments going forward.

If you have multiple BOSH runtime configs, with different OneAgent versions, you must delete the older ones using bosh delete-config. Consult the BOSH documentation for details.

Deploy your changes

Since existing BOSH deployments won’t be automatically updated with the jobs specified in the runtime configuration, you need to re-deploy those deployments so that BOSH rolls out the OneAgent:

bosh -e my-env -d deployment deploy

This version isn't recommended for controlled production environments as it automatically downloads the latest OneAgent release with each bosh deploy

The latest OneAgent release can be controlled on in the OneAgent updates section of your DESK environment.

Download the lightweight OneAgent BOSH release from the DESK Github repository

Ensure that your bosh CLI is successfully connected to the BOSH director. For details, please refer to Cloud Foundry documentation or Pivotal documentation.

Upload the BOSH release of OneAgent to the BOSH Director:

bosh -e my-env upload-release PATH-TO-BINARY/desk-release.tgz

Create a runtime config named runtime-config-desk.yml with the appropriate settings for your environment.

Manifest runtime-config-desk.yml file

Download

releases:
- name: desk-oneagent
  version: 1.1.0
  #specify version of latest release

addons:
- name: desk-oneagent-addon
  jobs:
  - name: desk-oneagent
    release: desk-oneagent
  include:
    stemcell:
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
  properties:
    desk:
      environmentid: <environmentId>
      apitoken: <token>
      ###
      # optional properties below
      ###
      # Replace with your DESK ActiveGate URL, including the environment ID.
      # An example URL might look like the following
      apiurl: https://{your-active-gate-url}/e/{environmentid}/api
      # Set to 'all' if you want to accept all self-signed SSL certificates.
      sslmode: all
      # Specify a direct download URL for DESK OneAgent.
      # If this propery is set, BOSH will download OneAgent from this location.
      downloadurl: https://direct-download-url-for-agent
      # Specify the proxy to be used for communication.
      proxy: https://your-proxy-url
      # Specify in which hostgroup the VMs in this deployments belong
      hostgroup: example_hostgroup
      # Define host tags for the VMs in this deployment
      hosttags: landscape=production team=my_team
      # Define custom properties for the VMs in this deployment
      hostprops: Department=Acceptance Stage=Sprint
      # Enable cloud infrastructure monitoring mode.
      # Set this to 1 to activate it
      infraonly: 0

#optional: extra addon configuration for Windows cells
- name: desk-oneagent-windows-addon
  jobs:
  - name: desk-oneagent-windows
    release: desk-oneagent
  include:
    stemcell:
    - os: windows2016
  properties:
    desk:
      environmentid: <environmentid>
      apitoken: <token>
      # All of the optional properties for the Linux addon shown above (for example, apiurl, hostgroup) can also be used here.

Notice there is a job defined for Linux (desk-oneagent) and a seperate one for Windows (desk-oneagent-windows).

Update the BOSH Director runtime configuration

bosh -e my-env update-runtime-config PATH/runtime-config-desk.yml

where PATH denotes the path to the runtime-config-desk.yml file.

This runtime configuration applies to all new BOSH deployments going forward.

If you have multiple BOSH runtime configs, with different OneAgent versions, you must delete the older ones using bosh delete-config. Consult the BOSH documentation for details.

Deploy your changes

Since existing BOSH deployments won’t be automatically updated with the jobs specified in the runtime configuration, you need to re-deploy those deployments so that BOSH rolls out the OneAgent:

bosh -e my-env -d deployment deploy