Install OneAgent using Puppet

Preview

Dynatrace provides a Puppet module that you can use to orchestrate OneAgent deployment in your environment. The OneAgent Puppet module is released as a Preview.

Requirements

• Puppet 6.0+
• OneAgent version 1.199+
• Dynatrace version 1.204+
• Script access to OneAgent installer files

Dependencies

• puppet/archive
• puppetlabs/powershell (for Windows deployment)
• puppetlabs/reboot

Download OneAgent Puppet module

1. Select Deploy Dynatrace from the navigation menu and then select Start installation.

2. Select Puppet module to download the module tarball.
   This is a safe archive hosted in your Dynatrace environment. Place the resulting artifact on your server node.

3. optional On Linux, you can verify the authenticity of the archive using the separately provided signature file:

   • Select Signature to download the sig file.

   • Make sure the downloaded Puppet module tarball and the signature file are stored in the same directory.

   • Navigate to the directory where you have saved the files and run the following command, substituting the names of the files with the actual name of the downloaded files:

     shellcopydownload
     wget https://ca.dynatrace.com/dt-root.cert.pem; openssl cms \
     -verify -binary \
     -in dynatrace-oneagent-puppet-1.0.0.20200101-060000.tar.gz.sig \
     -inform PEM \
     -content dynatrace-oneagent-puppet-1.0.0.20200101-060000.tar.gz \
     -CAfile dt-root.cert.pem >/dev/null

     A successful verification will result in the following output:

     plaintextcopydownload
     --2020-09-25 12:40:47--  https://ca.dynatrace.com/dt-root.cert.pem
     Resolving ca.dynatrace.com (ca.dynatrace.com)... 99.84.94.48, 99.84.94.69, 99.84.94.59, ...
     Connecting to ca.dynatrace.com (ca.dynatrace.com)|99.84.94.48|:443... connected.
     HTTP request sent, awaiting response... 200 OK
     Length: 2172 (2.1K) [application/x-pem-file]
     Saving to: ‘dt-root.cert.pem’
     
     dt-root.cert.pem 100%[========================>]   2.12K  --.-KB/s    in 0s
     
     2020-09-25 12:40:48 (102 MB/s) - ‘dt-root.cert.pem’ saved [2172/2172]
     
     Verification successful

Install the OneAgent Puppet

1. Save the module tarball to a directory on your server node.

2. To install the dynatrace/oneagent module, navigate to the directory where you saved the module tarball and run the following command:

   shellcopydownload
   puppet module install dynatrace-oneagent-puppet-1.0.0.20200101-060000.tar.gz

   The module deploys OneAgent using a dedicated configuration. The configuration ensures that the OneAgent service remains in a running state. For more information, see Puppet module documentation.

Configure OneAgent Puppet module

The OneAgent Puppet module requires access to the appropriate OneAgent installer files.

• If your Puppet server node has access to your Dynatrace environment, you can configure the module to download the installer files directly from the Dynatrace environment.
• Alternatively, you can download the installer files yourself using the Dynatrace web UI, and upload them to the server node. This provides the script with local copies of the installers.

Option 1: Use direct download from Dynatrace environment

The module utilizes the Dynatrace Deployment API to download the platform-specific installers to the Puppet agent nodes. You will need to specify the variables to supply the information required to authenticate the API call in your environment:

• environment_url:

  • Dynatrace SaaS: https://{your-environment-id}.live.dynatrace.com
  • Dynatrace Managed: https://{your-domain}/e/{your-environment-id}

• paas_token

  • The PaaS token of your environment

  For example:

  yamlcopydownload
  class { 'oneagent':
      # Set environment variables
      paas_token => 'abcdefjhij1234567890',
      environment_url => 'https://your-environment.live.dynatrace.com',
      # (...)
    }

For more examples, see Examples.

Option 2: Use local installers

Use the Dynatrace web UI to download the required OneAgent installer files and then upload them to the appropriate mounting point on the server node. The Puppet module will then download the installers from the Puppet server to the Puppet agent nodes.

Use the local_installer variable to supply the module with the path of the installer within the specified mounting point. This requires a configured file server on the server node.

For example:

yamlcopydownload
class { 'oneagent':
     # Set environment variables
     local_installer => mounting_point/path/of/oneagent-linux-installer.sh
     # (...)
   }

Note that Windows, Linux, and AIX require their dedicated installers. The original installer names, as downloaded from Dynatrace, include target platform designations. If you change the installer names, make sure the module can distinguish them.
If you don't specify a local installer, the module will attempt to use the direct download method to download the installers from the Dynatrace environment.

Variables

The OneAgent Puppet module supports the following variables:

Logging

By default, Puppet logs messages to syslog (for Linux-based hosts) or to Event Log (for Windows-based hosts). However, Puppet can be configured to store deployment-specific logs in designated files.

• For Puppet Server, you can configure the logging location by editing /etc/puppetlabs/puppetlabs/logback.xml and replacing the locations, pointed to by the <file> elements:

yamlcopydownload
(...)
    <appender name="F1" class="ch.qos.logback.core.FileAppender">
        <file>/new/log/location</file>
(...)

For more details, see logback config.

• For Puppet Agents, edit the puppet.conf file and add the logfile key:

yamlcopydownload
(...)
logdest=absolute_path_of_log_location.log
(...)

The location of the configuration file varies with the operating system:

• /etc/puppetlabs/puppet/puppet.conf for Linux systems,
• C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf for Windows.

For more details, see configuring UNIX agent and configuring Windows agent.

Examples

This example manifest:

• Downloads the OneAgent installer of a specific version (version) and saves it to a custom directory (download_dir)
• Instructs the module to deploy OneAgent on Linux and Windows hosts with the given configuration.
• Instructs the module to use the ppcle installer architecture.
• Uses install_args to pass the OneAgent installation parameters that assign the hosts to the My.HostGroup_123-456 host group and to the my.network.zone network zone.

ymlcopydownload
# Download OneAgent installer in specific version to a custom 
# directory with additional OneAgent install parameters

$env_url = 'https://abc12345.live.dynatrace.com'
$paas_token = 'abcdefghijk1234567890'
$install_args = [ '--set-host-group=My.HostGroup_123-456', '--set-network-zone=my.network.zone' ]
$preserve_installer = true
$version = '1.219.0.20210422-111723'

if $::osfamily == 'Windows' {
  class { 'oneagent':
    environment_url => $env_url,
    paas_token => $paas_token,
    preserve_installer => $preserve_installer,
    install_args => $install_args,
    platform_install_args => [ 'INSTALL_PATH=C:\\dynatrace', 'USER=LocalService' ],
    download_dir => 'C:\\temp',
    version => $version
  }
} else {
  class { 'oneagent':
    environment_url => $env_url,
    paas_token => $paas_token,
    preserve_installer => $preserve_installer,
    install_args => $install_args,
    platform_install_args => [ 'INSTALL_PATH=/opt/dynatrace', 'USER=linux_user' ],
    download_dir => '/tmp',
    version => $version,
    installer_arch => 'ppcle'
  }
}

You can find more example manifests in the examples directory. The directory contains the following manifests:

• local_installer.yml — OneAgent installation using a local installer.
• advanced_config.yml — OneAgent installation with a custom installation path and a download directory.
• oneagentctl_config.yml — OneAgent configuration using the oneagentctl command.

For path issues when installing on Windows, review Path Formatting for Windows in Puppet documentation.