squaredup/relay-agent repository overview

⁠What is SquaredUp?

SquaredUp is a unified visibility layer hosted in the cloud that provides an end-to-end view of all your business-critical applications. Connect to 100+ data sources through a versatile interface offering flexible dashboarding, effortless monitoring, powerful analytics, and universal search across your tech stack. Powered by our data mesh architecture, SquaredUp lets you correlate your data across teams and tools – all without the costs and complexity of a data warehouse.

⁠What is the SquaredUp Relay Agent?

The Relay allows you to securely connect data sources inside your own network (such as on-premise) to SquaredUp. An agent is a service that runs on a local machine and connects an internal service to SquaredUp. The agent listens to the queue from SquaredUp and picks up tasks, for example running scripts to provide data that SquaredUp has asked for. Ideally, you'd install it on a machine that has the fastest connection to the on-prem service, based on its location.

⁠Supported Tags

This repository provides both immutable tags, and rolling tags for each segment of a semantic version number⁠, along with latest and -rc tags.

We suggest that regardless of tag, customers make use of the latest version of the agent available, but the choice of which tag should be based on your practices and application needs. For many customers, especially those deploying a shared agent as its own service, the Major tag would be suitable, allowing them to receive updates during container provisioning operations, whilst isolating them from any breaking changes. The SquaredUp UI will also display an icon next to any agent that is running an outdated version, should you wish to use an immutable tag and still be notified of updates.

• Immutable tags
  • Major.Minor.Patch.Build
• Rolling tags
  • Major.Minor.Patch, Major.Minor, Major
  • Major.Minor.Patch-rc (release candidate)
  • latest

⁠How to use this image

⁠Prerequisites

⁠API Key

Prior to starting the agent, you will need to have logged into your SquaredUp tenant and created a Relay Agent and assigned it to one or more Agent groups. Creating an Agent registers it for use with SquaredUp and creates a unique API key that identifies that agent. For more information see step 1 of How to deploy an Agent⁠.

The API key can be injected into the container using a number of mechanisms. Depending on your organisational policies and practises, you may have a variety of different tools at your disposal to store the key and ensure that it is securely provided to the container. The examples below show how to provide the key using both Environment variables and Volume mounts for simplicity, but be aware that users who have access to the container host will be able expose the key using these methods. Consult your own organisational best practises to ensure that the API key is not compromised.

⁠Firewalls and Proxies

Make sure the container will be able to make outbound connections on port 443 to:

• SquaredUp (api.squaredup.com / eu.api.squaredup.com, depending on your region),
• Amazon S3 instances (*.amazonaws.com)
• Microsoft Azure Relay (*.servicebus.windows.net)

If a Proxy is required for individual containers, set a Environment variable named ALL_PROXY with the location of the proxy server. The proxy server may be a hostname or IP address (optionally followed by a colon and port number) or it may be a http URL (optionally including a username and password for proxy authentication). A proxy URL must be started with http, not https, and cannot include any text after the hostname, IP, or port

⁠Deploying multiple agents

Typically customers are able to service all of their needs with a single agent, deployed into their internal network. However should you have many isolated networks (either physical or virtual) that you wish to gather data from, you may need to deploy more than one agent.

Agents should never share API keys, as this will result in data requests being sent to the wrong network.

The agent container image will typically be deployed as its own shared service into a network communicating with multiple data sources, but if you have applications in isolated virtual networks (such as a microservices app with only open ports for frontend access), you may find it convenient to add an agent container into the existing service definition and manage them together as a single unit.

Consult the SquaredUp Relay documentation⁠ to learn more about managing multiple agents.

⁠Start an Agent

⁠Specify API key via Environment variable

Starting an instance of the Relay Agent is simple:

$ docker run -d --name SquaredUp-Agent -e RelaySettings:ApiKeys:0:ApiKey=XXXXXXXXXXXXX squaredup/relay-agent:tag

... where SquaredUp-Agent is the name you wish to assign the container, XXXXXXXXXXX is your API key, and tag is the tag specifying the agent version you want. See the tags tab for relevant tags. We always recommend you run the latest GA version available at time of deployment.

⁠Configuration file via volume mount

If instead you wish to use a configuration file, you can mount the following file into your container at /app/appsettings.json:

{
    "RelaySettings": {
        "ApiKeys": [
            {
                "Description": "Friendly name to be used in logs instead of last 4 key digits",
                "ApiKey": "XXXXXXXXXXXXXXXXXX"
            }
        ]
    },
    "LogLevel": "Information"
}

The description attribute is optional, and simply provide a friendly identifier in log entries instead of using the last four digits of the API key. The following command mounts the file from the working directory into correct location in the container:

$ docker run -d -v appsettings.json:/app/appsettings.json squaredup/relay-agent

⁠Using Secrets with Docker Compose

You can use the secrets functionality of Docker compose to inject the API key in a more secure fashion. In this example compose.yml the agent is started using the same config JSON from above, injected from the local file appsettings.json:

name: squaredup

services:
  agent:
    hostname: squaredup-containerhost # sets the hostname value as it appears in the Cloud
    image: squaredup/relay-agent:tag
    restart: on-failure
    secrets:
      - source: squp_config
        target: /app/appsettings.json

secrets:
  squp_config:
    file: ./appsettings.json

Note that the name and hostname attributes are optional, and can be specified to make it easier to track the containers and agent at a later date. To create and start the agent, you can simply run:

docker compose up -d

⁠Using secrets with Docker Swarm

When running a Swarm, secrets are managed by your cluster and will be securely replicated to each node within it, as they are encrypted during transit and storage, and are held in memory so they won't be found on individual nodes or container filesystems. In addition, secrets are only sent to swarm managers and nodes that are running containers that require them.

To create a secret from a local file named appsettings.json that contains the agent config, run:

docker secret create squp_agent_config appsettings.json

Note that the secret name squp_agent_config is user configurable, but you will need to remember it for the next step.

Finally, start the container and grant it access to the secret by running:

docker service create --name squp_agent --secret source=squp_agent_config,target=/app/appsettings.json squaredup/relay-agent:tag

⁠Using secrets with Docker Swarm and Compose files

You can reference existing Swarm secrets in services to be managed by Docker Compose. First you must create your secret as above using docker secret create.

Next, you can reference it in your Compose file by setting external: true on the global secret definition. This tells Compose not to attempt to create a new secret, and instead to take the existing value from the swarm.

name: squaredup

services:
  agent:
    hostname: squaredup-containerhost # sets the hostname value as it appears in the Cloud
    image: squaredup/relay-agent:tag
    restart: on-failure
    secrets:
      - source: squp_config
        target: /app/appsettings.json

secrets:
  squp_config:
    external: true

⁠Viewing Agent logs

When running in a container, the agent will print all log entries to StdOut. These are then available via docker logs containername when running detached, or in whatever log providers you may have configured.

When specifying the agent configuration through appsettings.json you also have the option to set the log level verbosity to Warning or Error if you wish to decrese the amount of logs stored and removal operational messages logged at the Information level (the default). For troubleshooting purposes, SquaredUp support may ask you to set the LogLevel to Debug, but this should only be performed temporarily as this is an extremely verbose mode and can generate a large volume of log data.

⁠Documentation

To immediately get started for free or request a demo visit squaredup.com⁠.

For detailed information on using SquaredUp please check our Knowledge base⁠.

⁠Feedback

To provide feedback, please contact SquaredUp Support⁠.