Install SolarWinds Observability Agent as a Docker image

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.

Limitations

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 Use a volume as a working directory.

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 two options to handle this:

• Provide the UAMS_CLIENT_ID_OVERRIDE 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 metadata.name to ensure that the Agent ID is always the same for a particular replica.

Download the Docker image

The Agent Docker image is periodically pushed to the DockerHub repository. To pull it, run the following command:

docker pull solarwinds/swo-agent:latest 

You can also browse available tags on https://hub.docker.com/r/solarwinds/swo-agent.

Supported environment variables

Configure the Agent Docker 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)

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

• SWO_URL - the correct endpoint for your organization

• 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.

Run the image as a Docker container without using Docker volumes

When working with SolarWinds Observability Agents, SolarWinds recommends that you use Docker volumes to store local data, such as manifests, logs, or plugin data between the restarts of the Docker container. Sensitive information, such as encryption keys for credential support, must be stored locally for security reasons and should not be synchronized with SolarWinds Observability.

When running Agent Docker image with docker run, all the plugins, manifests, and logs will be destroyed after the container is stopped. After each start of the container, the Agent will communicate with the cluster and download a list of installed plugins and their configuration.

Run the following command to start the container and print the output from the uamsclient process:

docker run -it --rm -e UAMS_CLIENT_ID_OVERRIDE="<your uams client id override>" -e UAMS_ACCESS_TOKEN="<your access token to communicate with the cluster>" -e SWO_URL xx-yy.cloud.solarwinds.com solarwinds/swo-agent:latest

You need to provide an access token, an endpoint for your organization, and a Client ID override as the required environment variables.

Example command with UAMS_CONTAINER_HOSTNAME variable

sudo docker run -it --rm -e UAMS_CLIENT_ID_OVERRIDE=<client_id> -e UAMS_ACCESS_TOKEN=<access_token> -e UAMS_CONTAINER_HOSTNAME="customHostname"  -v ${PWD}/config-dev.yaml:/uamsclient/config/config.yaml uams

Logs

Logs from Agent and plugins are available in the following location in the container /var/log/solarwinds/uamsclient

Use Docker volumes

• Use a volume as a working directory
• Persist logs
• Provide a custom configuration

Use a volume as a working directory

SolarWinds recommends that you use a Docker volume as the working directory of the Agent running in the container. The Docker volume is used to preserve the state of the application (installed plugins, current manifests, credentials store) between runs of the container. This way, plugins don't need to be downloaded and installed after each start of the container, which speeds up the startup process.

To use the volume, create it first by running:

docker volume create uams-volume 

Then you can mount the volume in the following location in the container /uamsclient/workdir:

docker run -d --name=uams-client --rm=true -v uams-volume:/uamsclient/workdir -e UAMS_CLIENT_ID_OVERRIDE="<client id>" -e UAMS_ACCESS_TOKEN="<token>" -e SWO_URL xx-yy.cloud.solarwinds.com solarwinds/swo-agent:latest

Persist logs

To keep logs from the Agent, you need to mount your local directory to the logs location in the container /var/logs/solarwinds/uamsclient:

docker run -d --name=uams-client --rm=true -v ${PWD}:/var/logs/solarwinds/uamsclient -e UAMS_CLIENT_ID_OVERRIDE="<client id>" -e UAMS_ACCESS_TOKEN="<token>" -e SWO_URL xx-yy.cloud.solarwinds.com solarwinds/swo-agent:latest

Replace ${PWD} by global path to your local directory where you want save logs from the container.

Use docker-compose

To run the Agent Container using docker-compose, use the file below:

services: 
  uamsclient: 
    image: solarwinds/swo-agent:latest 
    environment: 
      UAMS_CLIENT_ID_OVERRIDE: <client id> 
      UAMS_ACCESS_TOKEN: <token> 
      SWO_URL: <organization endpoint> 
      UAMS_CONTAINER_HOSTNAME: <custom hostname>  
    volumes: 
      - ./config.yaml:/uamsclient/config/config.yaml 
      - uamsclient-volume:/uamsclient/workdir 
volumes: 
  uamsclient-volume: {}

Run as a Kubernetes deployment

When running the Agent as a Kubernetes deployment, you can leverage Kubernetes secrets to hide the access token.

To create a secret for an access token, run the following command:

kubectl create secret generic access-token --from-literal=ACCESS_TOKEN="<token>"

To persist the Agent working directory between pod restarts, you can use a persistent volume. For example, you can use the following file to create PersistentVolumeClaim that will be referenced later in the Deployment definition:

apiVersion: v1 
kind: PersistentVolumeClaim 
metadata: 
  name: uamsclient-pv-claim 
  labels: 
    app: router 
spec: 
  accessModes: 
    - ReadWriteOnce 
  resources: 
    requests: 
      storage: 1Gi

To apply the Agent as a Kubernetes deployment in your cluster, use the following file.

The restartPolicy setting must be set to OnFailure so that the Agent is able to perform restart procedures sent from the SolarWinds Observability.

apiVersion: apps/v1 
kind: Deployment 
metadata: 
  name: uamsclient-deployment 
  namespace: <namespace> 
  labels: 
    k8s-app: uamsclient 
spec: 
  replicas: 1 
  selector: 
    matchLabels: 
      app: uamsclient 
  template: 
    metadata: 
      labels: 
        app: uamsclient 
    spec:
      restartPolicy: OnFailure
      containers: 
      - name: uamsclient 
        image: solarwinds/swo-agent:latest 
        env: 
          - name: UAMS_ACCESS_TOKEN 
            value: <token> 
          - name: SWO_URL 
            value: <cluster endpoint> 
          - name: UAMS_CONTAINER_HOSTNAME 
            value: <custom hostname> 
          - name: UAMS_ACCESS_TOKEN 
            valueFrom: 
              secretKeyRef: 
                name: access-token 
                key: ACCESS_TOKEN 
        volumeMounts: 
          - name: uamsclient-persistent-storage 
            mountPath: /uamsclient/workdir 
      volumes: 
        - name: uamsclient-persistent-storage 
          persistentVolumeClaim: 
            claimName: uamsclient-pv-claim

Run as a Kubernetes DaemonSet

To apply the Agent as a DaemonSet in your multi-node cluster, use the following file.

The restartPolicy setting must be set to OnFailure so that the Agent is able to perform restart procedures sent from the SolarWinds Observability.

apiVersion: apps/v1 
kind: DaemonSet 
metadata: 
  name: uamsclient-daemonset 
  namespace: <namespace>
  labels: 
    k8s-app: uamsclient 
spec: 
  selector: 
    matchLabels: 
      name: uamsclient 
  template: 
    metadata: 
      labels: 
        name: uamsclient 
    spec: 
      restartPolicy: OnFailure  
      tolerations: 
      # this toleration is to have the daemonset runnable on master nodes 
      # remove it if your masters can't run pods 
      - key: node-role.kubernetes.io/master 
        operator: Exists 
        effect: NoSchedule 
      containers: 
      - name: uamsclient 
        image: solarwinds/swo-agent:latest 
        env: 
        - name: UAMS_ACCESS_TOKEN 
          value: <token> 
        - name: SWO_URL 
          value: <cluster endpoint>
        - name: UAMS_CONTAINER_HOSTNAME 
          value: <custom hostname>
        - name: UAMS_CLIENT_ID_OVERRIDE_SOURCE_NAME 
          valueFrom: 
            fieldRef: 
              fieldPath: spec.nodeName  
        volumeMounts: 
          - name: uamsclient-workdir 
            mountPath: /uamsclient/workdir 
  volumeClaimTemplates: 
  - metadata: 
      name: uamsclient-workdir 
    spec: 
      accessModes: [ "ReadWriteOnce" ] 
      resources: 
        requests: 
          storage: 1Gi

Run as a Kubernetes sidecar

To apply the Agent as a sidecar in a replicated workload, ensure that the Agent ID is not changing when the container is restarted or when a new pod for the same replica is started.

To achieve this, use StatefulSet which will always assign the same host name for a replica with a particular ordinal number. The hostname can then be used as UAMS_CLIENT_ID_OVERRIDE_SOURCE_NAME to ensure that each replica has always the same Agent ID.

The restartPolicy setting must be set to OnFailure so that the Agent is able to perform restart procedures sent from the SolarWinds Observability.

apiVersion: apps/v1 
kind: StatefulSet 
metadata: 
  name: <app>-with-uamsclient-sidecar 
spec: 
  selector: 
    matchLabels: 
      app: <app>-with-uamsclient-sidecar 
  serviceName: <app>-with-uamsclient-sidecar 
  replicas: 3 
  template: 
    metadata: 
      labels: 
        app: <app>-with-uamsclient-sidecar 
    spec: 
      restartPolicy: OnFailure 
      containers: 
      # - name: <app> # main app container 
      - name: uamsclient-sidecar 
        image: solarwinds/swo-agent:latest 
        env: 
          - name: UAMS_ACCESS_TOKEN 
            value: <token> 
          - name: SWO_URL 
            value: <cluster endpoint> 
          - name: UAMS_CONTAINER_HOSTNAME 
            value: <custom hostname> 
          - name: UAMS_CLIENT_ID_OVERRIDE_SOURCE_NAME 
            valueFrom: 
              fieldRef: 
                fieldPath: metadata.name 
        volumeMounts: 
          - name: uamsclient-workdir 
            mountPath: /uamsclient/workdir 
  volumeClaimTemplates: 
  - metadata: 
      name: uamsclient-workdir 
    spec: 
      accessModes: [ "ReadWriteOnce" ] 
      resources: 
        requests: 
          storage: 1Gi