Documentation forSolarWinds Observability

Run the SolarWinds Observability Agent as a Docker image or Kubernetes deployment

You can deploy Agents using a Docker image and use the Agent for OTel integrations. When adding an integration, just select the deployed Agent to install the appropriate integration plugin on it.

SolarWinds Observability Agent support for Docker and Kubernetes

Agent is published as a Docker image with every build. The primary use case for the Docker image is to run it in a Kubernetes cluster to monitor nodes and/or pods. You can also just start a container with the docker run command.


Review the following differences between the regular Agent deployment and using the Agent Docker image.

Use Docker volumes

Use Docker volumes as the working directory of the SolarWinds Observability Agent running in the container to preserve the state of the application between runs of the container. See Run the SolarWinds Observability Agent as a Docker image or Kubernetes deployment.

Auto-update is disabled

Auto-update process for Agent in Docker would cause the process to stop and that leads to stopping the Docker container. This is why the auto-update functionality for Agent is disabled.

Auto-update for plugins is still enabled unless disabled in config.yaml.

Agent ID override

MAC Addresses and other properties used to calculate the Agent ID change with each run of the Docker container. This behavior would cause assigning a new Agent ID every time the Docker container starts.

There are the following options to handle this:

  • (Recommended): Copy the UAMS_CLIENT_ID_OVERRIDE from the code generated in the Add Host wizard (in Data Source, select SolarWinds Observability Agent > Configuration management tool > click Agent > provide token > Docker tab) and provide this environment variable to the Agent.

  • Use a UUID generator, such as, to generate the UAMS_CLIENT_ID_OVERRIDE. Provide this environment variable to the Agent. This ID is the same between runs and it is in the GUID/UUID format, such as 3ce8658f-343f-4d60-a382-cba1a1bc0e63.

  • Ensure that a unique and repeatable Agent ID is assigned to each Agent container by providing the UAMS_CLIENT_ID_OVERRIDE_SOURCE_NAME environment variable. This variable can contain arbitrary text used to generate the same UUID every time. For example:

    • When the Agent is part of a DeamonSet, set its value to spec.nodeName to ensure that the Agent ID is always the same on a particular node.

    • When the Agent is replicated within StatefulSet, set its value to to ensure that the Agent ID is always the same for a particular replica.

Enable host monitoring to use the Agent for database monitoring

If you want to use the Agent deployed in Docker/Kubernetes to monitor a database, add the host for monitoring first or enable host monitoring for the agent.

Supported environment variables

Configure the Agent container by providing the following environment variables:

  • UAMS_ACCESS_TOKEN - an access token used to register in the client (required)

  • UAMS_CLIENT_ID_OVERRIDE - a constant Client ID that does not change between runs (required if you do not want to register a new client after each run of a new docker container)

  • SWO_URL - the correct endpoint for your organization

  • UAMS_METADATA - custom metadata to be sent to cluster on the first registration (optional)

  • UAMS_CONTAINER_HOSTNAME - an environment variable used to set a custom hostname because the autodetection of hostnames in some container runtimes does not work as expected. For example, setting this variable addresses a situation where a container might return the hostname of the parent system. Using this variable is optional but strongly recommended.

  • UAMS_OVERRIDE_HOSTNAME - a customer client hostname (optional). It is required if you want to set a specific agent hostname. SolarWinds recommends that you use it together with UAMS_CONTAINER_HOSTNAME and set the same value for both variables.

Learn more