Installing and Configuring Dynatrace Full-Stack Add-on for Pivotal Platform

This topic explains how to install and configure the Dynatrace Full-Stack Add-on for Pivotal Platform.

Note: The syntax for the Dynatrace manifest is identical for PAS and PKS. As such, if no detailed include/exclude rules are used the same manifest can be utilized for both PAS and PKS. In deployments utilizing Pivotal Operations Manager (OpsMan) 2.5 or greater where both PAS and PKS are configured by the same OpsMan instance, this means both PAS and PKS can be monitored simulatenously via a single deployment of the Dynatrace Full-Stack Add-on.

Create the Dynatrace Manifest

Follow these steps to create the Dynatrace manifest for your deployment:

  1. Create a Dynatrace manifest file called runtime-config-dynatrace.yml, using the code below as a template to get started.
releases:
- {name: dynatrace-oneagent, version: 1.2.1}  
addons:
- name: dynatrace-oneagent-addon
  jobs:
  - name: dynatrace-oneagent
    release: dynatrace-oneagent
  include:
    stemcell:
    - os: ubuntu-trusty
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
    jobs:
    - {name: smoke-tests, release: cf}
    - {name: push-apps-manager, release: push-apps-manager-release}
    - {name: deploy-notifications, release: notifications}
    - {name: deploy-notifications-ui, release: notifications-ui}
    - {name: push-pivotal-account, release: pivotal-account}
    - {name: deploy-autoscaling, release: cf-autoscaling}
    - {name: register-broker, release: cf-autoscaling}
    - {name: nfsbrokerpush, release: nfs-volume}
    - {name: bootstrap, release: cf-mysql}
    - {name: rejoin-unsafe, release: cf-mysql}
    - {name: broker-registrar, release: cf-mysql}
    - {name: deregister-and-purge-instances, release: cf-mysql}
    - {name: smoke-tests, release: cf-mysql}
    - {name: install-hwc-buildpack, release: hwc-buildpack}
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      ###
      # optional properties below
      ###
      # Replace with your Dynatrace Managed URL, including the environment ID.
      # An example URL might look like the following
      apiurl: https://{your-managed-cluster.com}/e/{environmentid}/api
      # Set to 'all' if you want to accept all self-signed SSL certificates.
      sslmode: all
      # Specify a direct download URL for Dynatrace 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, see advanced configuration page for more details
      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
      # Enable validation of the download via certificate
      # Set this to true to active it
      validatedownload: false         
# optional: extra addon configuration for Windows cells
- name: dynatrace-oneagent-windows-addon
  jobs:
  - name: dynatrace-oneagent-windows
    release: dynatrace-oneagent
  include:
    stemcell:
    - os: windows2012R2
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      # All of the optional properties for the Linux addon shown above (for example, apiurl, hostgroup) can also be used here.
  1. Replace the values listed in the template as follows:

    • releases: - version: Specify the version number of your Dynatrace Full-Stack Add-on for Pivotal Platform download from Pivotal Network.
    • jobs: - name: Do not change the name of this job. It must be dynatrace-oneagent for Linux VMs.
    • include: stemcell - os<: Do not change the OS type.
    • environmentid: Replace with your Dynatrace environment ID.
    • apitoken: Replace with your PaaS token from the Dynatrace UI.
    • apiurl: Replace with your Dynatrace Managed URL, including the environment ID. An example URL might look like the following: https://{your-managed-cluster.com}/e/{environmentid}/api
  2. (Optional) The add-on supports additional configuration properties:

    • sslmode: Set to all if you want to accept all self-signed SSL certificates.
    • downloadurl: Specify a direct download URL for Dynatrace OneAgent. If this propery is set, BOSH will download OneAgent from this location.
    • proxy: Specify the proxy to be used for communication.
    • hostgroup: Specify hostgroup for VMs in this deployment.
    • hosttags: Specify host tags for VMs in this deployment.
    • hostprops: Specify custom properties for VMs in this deployment.
    • infraonly: Set to 1 to enable cloud infrastructure monitoring mode. This disables all deep process monitoring.
    • validatedownload: Set to true to enable validation of the download via certificate.
  3. If you also want to deploy Dynatrace to Windows Diego cells, configure a second add-on section for the dynatrace-oneagent-windows job. The properties for environmentid, apitoken, and apiurl remain the same as with the normal Linux configuration.

    • jobs: - name: For Windows cells, this must be dynatrace-oneagent-windows.
    • include: stemcell - os: For Windows cells, this must be windows2012R2 and/or windows2016.

Note: To modify the configuration of an existing deployment, you must update the manifest file and redeploy.

Download and Deploy the Dynatrace Full-Stack Add-on for Pivotal Platform

After deploying Ops Manager, do the following to download and deploy the Dynatrace Full-Stack Add-on for Pivotal Platform:

  1. Download the Dynatrace Full-Stack Add-on for Pivotal Platform software binary from Pivotal Network to your local machine.

  2. Copy the software binary to your Ops Manager instance.

    $ scp -i PATH/TO/PRIVATE/KEY dynatrace-release.tar.gz ubuntu@YOUR-OPS-MANAGER-VM-IP:

  3. Copy the Dynatrace manifest file to your Ops Manager instance.

    $ scp -i PATH/TO/PRIVATE/KEY runtime-config-dynatrace.yml ubuntu@YOUR-OPS-MANAGER-VM-IP:

  4. SSH into Ops Manager.

    $ ssh -i PATH-TO-PRIVATE-KEY ubuntu@YOUR-OPS-MANAGER-VM-IP

  5. On the Ops Manager VM, navigate to the software binary location in your working directory.

    $ cd PATH-TO-BINARY

  6. Log in to the BOSH Director.

    1. On the Ops Manager VM, create an alias in the BOSH CLI for your BOSH Director IP address. For example:
      $ bosh alias-env my-env -e 10.0.16.10
    2. Log in to the BOSH Director, specifying the newly created alias. For example:
      $ bosh -e my-env login

  7. Upload your release.

    $ bosh -e my-env upload-release PATH-TO-BINARY/dynatrace-release.tar.gz

  8. (Optional) From the command line, you can confirm that upload of the Dynatrace software binary is complete. You should see the Dynatrace binary file.

    $ bosh -e my-env releases

  9. Update your runtime configuration to include the Dynatrace Add-on for Pivotal Platform.

    Note: If you installed other BOSH add-ons, you must merge the Dynatrace manifest into your existing add-on manifest. Append the contents of runtime-config-dynatrace.yml to your existing add-on YML file.

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

  10. Verify your runtime configuration changes match what you specified in the Dynatrace manifest file.

    $ bosh -e my-env runtime-config
    For example:
    Acting as user 'admin' on 'micro'
    releases:
    - {name: dynatrace-oneagent, version: 1.2.1}
    addons:
    - name: dynatrace-oneagent-addon
      jobs:
      - name: dynatrace-oneagent
        release: dynatrace-oneagent
    ...
    

  11. Navigate to your Installation Dashboard in Ops Manager.

  12. Click Apply Changes.

Advanced Configuration

This section explains advanced configuration of the Dynatrace Full-Stack Add-on for Pivotal Platform.

About the Hostgroup Property

Dynatrace utilizes host group functionality to automatically group hosts. Host groups make it easier to apply unique configurations within Dynatrace to groups of hosts. Functionality that can be configured based on host group includes anomaly detection and OneAgent updates. Host groups also change how process groups are detected. When the same process is running in two different host groups, Dynatrace will create one process group for each host group. Additionally, automatic tagging can make use of host groups.

For more information read the full host group documentation.

Hostgroup Property Examples

An example use of the hostgroup property is to create hostgroups for individual Pivotal Container Service (PKS) clusters

  1. Log in to the BOSH Director.
    1. Log in to PKS. For example:
      $ pks login -a api.pks.somedomain.com -u someusername
  2. Determine the UUID for the PKS cluster (will begin with service-instance_)

    1. For example:
      $ pks cluster my-cluster
      output snipped for brevity:
       UUID:                     a4604071-07df-49e7-92d1-2effc9e3fe42

  3. Create a Dynatrace manifest file called runtime-config-dynatrace.yml, using the code below as a template to get started.

releases:
- {name: dynatrace-oneagent, version: 1.2.1}

addons:
- name: dynatrace-oneagent-addon
  jobs:
  - name: dynatrace-oneagent
    release: dynatrace-oneagent
  include:
    deployments:
    # enter the BOSH deployment name, in the format of service-instance_<UUID-OBTAINED-IN-PREVIOUS-STEP>
    - service-instance_a4604071-07df-49e7-92d1-2effc9e3fe42
    stemcell:
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      # Specify a hostgroup for this PKS cluster
      hostgroup: pks_cluster_xyz
  1. Update your runtime configuration to include the Dynatrace Add-on for Pivotal Platform.

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

  2. Navigate to your Installation Dashboard in Ops Manager.

  3. Click Apply Changes.

Multiple Deployment Host Group Example

When applying host groups to multiple deployments, the entire addon block is duplicated with unique job names, see below example:

releases:
- {name: dynatrace-oneagent, version: 1.2.1}

addons:
- name: dynatrace-oneagent-addon-xyz
  jobs:
  - name: dynatrace-oneagent
    release: dynatrace-oneagent
  include:
    deployments:
    # enter the BOSH deployment name, in the format of service-instance_<UUID-OBTAINED-IN-PREVIOUS-STEP>
    - service-instance_a4604071-07df-49e7-92d1-2effc9e3fe42
    stemcell:
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      # Specify a hostgroup for this PKS cluster
      hostgroup: pks_cluster_xyz
- name: dynatrace-oneagent-abc
  jobs:
  - name: dynatrace-oneagent
    release: dynatrace-oneagent
  include:
    deployments:
    # enter the BOSH deployment name, in the format of service-instance_<UUID-OBTAINED-IN-PREVIOUS-STEP>
    - service-instance_adee170c-21ba-4274-97a4-cab13ed07bb7
    stemcell:
    - os: ubuntu-xenial
  exclude:
    lifecycle: errand
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      # Specify a hostgroup for this PKS cluster
      hostgroup: pks_cluster_abc