Deploy OneAgent on OpenShift for application-only monitoring

To deploy OneAgent on OpenShift for application-only monitoring, read the instructions provided below.

Before you begin

You'll need to

Acquire DESK environment credentials.
Review the list of supported applications and versions.

Generate a PaaS token

The first step is to get your environment ID and PaaS token for your DESK environment.

How to get your environment ID and PaaS token

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. You'll need this ID to link your DESK account with your PaaS environment. Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.
To generate a PaaS token, click the Generate new token button. The PaaS token is essentially an API token that's used in combination with your environment ID to download DESK OneAgent. As you'll see, there's also a default InstallerDownload token available that you can alternatively use. However, for security reasons, it's recommended that you create several discrete tokens for each environment you have.
Type in a meaningful name for your PaaS token. A meaningful token name might be the name of the PaaS platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing PaaS tokens, go to Settings -> Integration -> Platform as a Service.
Click Generate to create the PaaS token. The newly created PaaS 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.

Integrate OneAgent into your application

The following steps explain how to integrate OneAgent into a binary build with a Dockerfile.

You have two integration options:

Integrate at container build time.
OneAgent version 1.149 and later Integrate at container run time.

Build time Run time

The build time integration consists of two steps:

Integrate OneAgent into the application image.
Build the application image.

Integrate OneAgent into the application image

Define variables with optional default values using ARG instructions, as shown in the code snippet below.

ARG DT_API_URL="https://<environmentID>.live.desk.com/api"
ARG DT_API_TOKEN="<token>"
ARG DT_ONEAGENT_OPTIONS="flavor=default&include=<technology1>&include=<technology2>"
ENV DT_HOME="/opt/desk/oneagent"

Notes:

You can override the default values within the OpenShift BuildConfig. Replace <environmentID> with your DESK environment ID. If you’re using DESK Managed, you need to provide your DESK Server URL (https://<YourDESKServerURL>/e/<environmentID>/api). Replace <token> with the PaaS token mentioned above.
Technology support is enabled via include parameters. Valid options for flavor=default are all, java, apache, nginx, nodejs, dotnet, php and go. Including specific technology-support options, rather than support for all technology options, results in a smaller OneAgent package.

What if my Docker image is based on Alpine Linux?

DESK OneAgent supports the flavor musl for Alpine Linux based environments. Valid options for flavor=musl are all, java, apache, nginx, and nodejs.

Add the following commands to your current Dockerfile to integrate OneAgent and activate instrumentation of your application.

ARG DT_API_URL="https://<environmentID>.live.desk.com/api"
ARG DT_API_TOKEN="<token>"
ARG DT_ONEAGENT_OPTIONS="flavor=default&include=<technology1>&include=<technology2>"
ENV DT_HOME="/opt/desk/oneagent"
RUN mkdir -p "$DT_HOME" && \
    wget -O "$DT_HOME/oneagent.zip" "$DT_API_URL/v1/deployment/installer/agent/unix/paas/latest?Api-Token=$DT_API_TOKEN&$DT_ONEAGENT_OPTIONS" && \
    unzip -d "$DT_HOME" "$DT_HOME/oneagent.zip" && \
    rm "$DT_HOME/oneagent.zip"
ENTRYPOINT [ "/opt/desk/oneagent/desk-agent64.sh" ]
CMD [ "executable", "param1", "param2" ] # the command of your application, e.g. java

Note: The commands above that use wget and unzip may fail if they aren't provided by the base image.

Build your application image

In an OpenShift context the above Dockerfile could be used for binary builds in the following way:

$ oc new-build --binary --strategy=docker --allow-missing-images yourapp
$ oc patch bc/yourapp --type=json --patch='[{"op":"remove","path":"/spec/strategy/dockerStrategy/from"}]'
$ oc start-build yourapp --from-dir=. --follow

Note: You can monitor your application containers with a different DESK environment. To do this, read the instructions below:

How to use a different DESK environment for images enriched with OneAgent

For OneAgent version 1.139 or higher, if you have an existing application image where you have already added the OneAgent code modules for a specific DESK environment, you can have the OneAgent report to another DESK environment without rebuilding your application image.

For this you need to make a call to the REST endpoint of your second DESK environment. Don't forget to adapt the respective placeholders <environmentID> and <token>.

$ curl "https://<environmentID>.live.desk.com/api/v1/deployment/installer/agent/connectioninfo?Api-Token=<token>"

In return, you get a JSON object that covers the required information that needs to be passed as environment variable to the application container. Make sure you set the environment variables of the application container as described below:

DT_TENANT: equals tenantUUID
DT_TENANTTOKEN: equals tenantToken
DT_CONNECTION_POINT: semi-colon separated list of communicationEndpoints

To use this feature you need OneAgent version 1.149 or later.

You can integrate OneAgent at container run time. With this option, your application image remains unaffected—OneAgent merely runs in the same container.

Extend your deployment template with initContainer, which will download OneAgent, and make it available as a volume. See the # initcontainer to download OneAgent and # Make OneAgent available as a volume sections of the example below.
Possible values for the DT_ONEAGENT_OPTIONS:
- <FLAVOR>: The flavor of your image. Use either default or musl.
- <TECHNOLOGY>: The OneAgent code module required for your application. Valid options are all, java, apache, nginx, nodejs, dotnet, php, and go. You can specify several code modules, use the &include=<technology1>&include=<technology2> syntax for that.
Add the newly created volume to the container of your application. See the # your application containers section of the example below.

# your application containers
      containers:
      - name: customer-app
        image: tomcat
        env:
        - name: LD_PRELOAD
          value: /opt/desk/oneagent/agent/lib64/liboneagentproc.so
        volumeMounts:
        - mountPath: /opt/desk/oneagent
          name: oneagent

# initcontainer to download OneAgent
      initContainers:
      - name: install-oneagent
        image: alpine:3.8
        command:
        - /bin/sh
        args:
        - -c
        - ARCHIVE=$(mktemp) && wget -O $ARCHIVE "$DT_API_URL/v1/deployment/installer/agent/unix/paas/latest?Api-Token=$DT_PAAS_TOKEN&$DT_ONEAGENT_OPTIONS" && unzip -o -d /opt/desk/oneagent $ARCHIVE && rm -f $ARCHIVE
        env:
        - name: DT_API_URL
          value: https://<Your-environment-ID>.live.desk.com/api
        - name: DT_PAAS_TOKEN
          value: <paastoken>
        - name: DT_ONEAGENT_OPTIONS
          value: flavor=<FLAVOR>&include=<TECHNOLOGY>
        volumeMounts:
        - mountPath: /opt/desk/oneagent
          name: oneagent

# Make OneAgent available as a volume
      volumes:
      - name: oneagent
        emptyDir: {}

Configure a proxy address (optional)

In case you run an environment with proxy, you need to set the DT_PROXY environment variable in the application container to pass the proxy credentials to OneAgent.

Note: You might need to update the wget shipped with the Alpine image to allow for proxy authentication for the download of OneAgent (see bugs.alpinelinux.org for more information).