Bigeye Agent Installation Guide

Bigeye provides a Docker image for hosting the Bigeye Data Source Agent on your infrastructure. The agent may be deployed as a standard Docker container instance using tools such as docker run or docker-compose. You may also use container orchestration systems such as Kubernetes or Nomad. ~

Requirements

Pre-Install Checklist

You will need the following information to install the Bigeye agent.

1. Set up a VM / host (infrastructure requirements below)
2. Bigeye credentials
   • You will need a Bigeye account.
   • The user must be an Admin or an Owner role in Bigeye.
3. Company prefix
   • This is the first part of your Bigeye URL (e.g. “app” for app.bigeye.com)

1. docker access token
   • Bigeye will provide this

Infrastructure Requirements

1. Host with docker installed and running
   1. Other Docker platforms such as AWS ECS, or orchestration systems such as Kubernetes will work, but their installation is not directly supported by Bigeye.
   2. Install docker if it is not already intalled [CentOS][RHEL][Debian][Ubuntu]
      1. NOTE for RHEL, the official docker instructions don't quite work. Using docker's CENTOS yum repository instead is a good workaround.
      2. bash

         sudo yum install -y yum-utils
         sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
         sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
         sudo systemctl start docker
         # test it 
         sudo docker run hello-world
         

   3. You can test if docker is running by using docker info and getting a non-error response
2. docker compose should already work if you've installed docker with the above instructions. If not, Install docker compose (Instructions
   1. Run docker compose version to test if it is installed correctly. The version should be 2.0 or higher.
3. Minimum HW size: 4 CPU, 8GB mem (ie AWS t3.xlarge, GCP e2-standard-4, Azure B4/D4, etc)/
   1. 25GB disk space on /var is recommended
4. Network access for agent subnets
   1. No ingress (inbound) networking access for the agent is required (other than for internal administration ie SSH)
   2. Egress (outbound) Access to the data sources you wish to add to Bigeye for monitoring
   3. Egress (outbound) Access to the Bigeye Saas environment to pull work
   4. Egress (outbound) Access to pull the agent image from docker.io

Install

Docker compose is a docker native tool that is used to define docker containers as yaml configuration instead of having to manage them on the command-line with flags etc. It will be used heavily for installing and running the agent.

Create docker-compose.yaml

Download bigeye-agent-docker-compose.yaml as docker-compose.yaml and pull the latest agent image.

docker logout
docker login --username bigeyedata --password <docker access token>
wget https://bigeye-public-web.s3.amazonaws.com/bigeye-agent-docker-compose.yaml --output-document=docker-compose.yaml
docker compose pull

Anytime you wish to install the latest version of the agent, docker compose pull can be run again to pull the latest image.

If docker compose is not able to be installed, the native docker commands are in the Appendix and can be used instead.

If docker pull is not possible on the system where you will be running the agent, there are instructions on how to import/export the container from a test system instead in the Appendix.

Configuration

1. Generate agent encryption keys and configuration

mkdir agent_config

# Run setup script
# -p app - single-tenant saas customers will use something different (ask Bigeye)

docker run --rm -it -v "${PWD}/agent_config:/app/config" --entrypoint setup_agent.sh docker.io/bigeyedata/agent:latest -p app

The setup script will prompt you for your Bigeye username and password. This is used to exchange Encryption and mTLS certs with Bigeye's infrastructure. After registration it typically takes 10-15minutes for the mTLS keys to propagate, agent connections before then will fail with an error message about invalid SSL cert.

A description of the files that are generated by the above script can be found in the Appendix.

2. Add data sources to the agent

Edit agent_config/agent.yaml and add each source. For each source you will need:

• Warehouse type (MySQL, Oracle, Redshift, etc)
• Hostname or IP address
• Port number
• Username
• Password (double quotes in the password should be escaped with a , ie "my_pass\"_with_a_double_quote")
• Database name

Workspaces

To limit agent sources to only certain workspaces, you can configure the allowed workspace IDs in the agent's config.yaml. You can set the workspaces at the agent level or the source level. We will use the agent level settings as a fallback if the source level settings are not set. If neither are set, we will allow all workspaces as before. These settings are optional, but highly recommended.

An example of such a config at the agent level is given below, under the defaultAllowedWorkspaces key:

companyUuid: <company_uuid>

defaultAllowedWorkspaces: [1, 2]
workflowUrl: app-workflows.bigeye.com

mutualTlsEnabled: true

mtlsCertLocation: /app/config/mtls.pem
mtlsKeyLocation: /app/config/mtls.key
publicEncryptionKeyDir: /app/config
privateEncryptionKeyPath: /app/config/private.pem

logQueries: false
healthLoggerEnabled: true

Another example of a config at the source level is given below, under the allowedWorkspaces key:

sources:
  - identifier: 'Oracle test agent'
    allowedWorkspaces: [2, 3]
    connectionFactory:
      type: oracle
      host: test.test
      port: 1521
      user: <username>
      password: <password>
      databaseName: <databaseName>

Running the Agent

Note: All configuration steps above must be complete before deploying the agent.

# The -d flag (detatch) runs the container in the background
docker compose up -d

# Check that the container is running
docker ps -f name=bigeye-agent

# View container logs (-f can be used to “tail” the logs)
docker compose logs

# Stopping the agent if desired
docker compose down

To confirm that the container started successfully, look for a line in the Docker log similar to the following:

INFO Agent started successfully in 4076ms. Polling for activities...

Note that you can launch more instances of the Agent on the same machine by copying the bigeye-agent block in docker-compose.yaml (be sure to name it something else ie bigeye-agent-xxx).

Add data sources in Bigeye UI

Log into the Bigeye UI ie https://app.bigeye.com for multi-tenant saas or https://.bigeye.com for single-tenant saas.

1. Go to _Catalogs _view
2. Select the Add source button in the upper right hand
3. Select the data source type (ie. Snowflake)
4. Select Connect with in-VPC agent
5. The Name field in the next screen much match exactly the Identifier field that was used in agent.yaml

• The rest of the steps beyond this will be the same as a directly connected data source (non-agent). https://docs.bigeye.com/docs/getting-started#1-connect-your-sources

Troubleshooting

Common agent errors in agent log

javax.net.ssl.SSLException: error:10000412:SSL routines:OPENSSL_internal:SSLV3_ALERT_BAD_CERTIFICATE

• Description: Certificate given to Bigeye in “Step 2. Upload agent authentication key” does not match.
• Fix: Work with Bigeye support to resolve this (config/mtls_ca.pem md5 should be checked and in Bigeye’s workflow service)

Deadline exceeded (DEADLINE_EXCEEDED)

• Description: Network connectivity between the Bigeye agent and the Bigeye workflow service does not work
• Fix:
  • Check that workflowUrl is set correctly in ./config/agent.yaml
  • Check that the port is open, ie nmap -Pn -p 443
  • Nmap should return “open” as the state of the port and not “filtered”
    Shell

    PORT    STATE SERVICE
    443/tcp open  https
    

  • Find out why network connectivity is not working and resolve

Exception in thread "main" io.grpc.StatusRuntimeException: CANCELLED: RST_STREAM closed stream. HTTP/2 error code: CANCEL

• Description: Something in the networking infrastructure is closing the connection between the agent and Bigeye SaaS.
• Fix: Work with your security / networking team to find where this is happening. Something that helps narrow things down greatly is to prove the agent and configs work from outside of your production network. IE start the agent with the same configuration files on a laptop at home/office (somewhere not in the production network).

jdbc timeout / error reaching host:port

• Description: Networking connectivity between the agent and the data source is not set up.
• Fix: Likely culprits are firewalls or subnets that do not have a route to reach the subnet that the data source is running on

io.grpc.StatusRuntimeException: UNAVAILABLE: error reading from server: EOF

• Description: Yaml formatting error in ./config/agent.yaml
• Fix: Typically this will be improper indentation or a missing quote in the agent config file.

Http2Exception: First received frame was not SETTINGS. Hex dump for first 5 bytes: 485454502f

• Description: The agent is detecting that an "HTTP" connection is being established on the server side, but we are using GRPC for communication which is HTTP2. This can happen if there is a proxy in the self-hosted environment between the agent and Bigeye infrastructure.
• Fix: Ensure that the proxy can handle HTTP2 connections or route agent connections directly to Bigeye infrastructure and do not go through the proxy

Appendix

Import Image Archive

If docker pull can not be used on the production system where the agent will be run, use the following instructions to save and transfer the docker image from a test system / local workstation.

save the agent image as a file

Follow the docker compose pull instructions on a test system to pull the agent image. Then export the image to a file using docker save.

# Export image to file
docker save docker.io/bigeyedata/agent:latest > bigeye_agent_$(date '+%Y-%m-%d').tar

import the agent image on the production system

Copy the image archive file to the system where the agent will be run. Import it onto the host that will be running the agent using the commands below.

# Import image
docker load -i < Path to image archive here >

# Verify the image was loaded successfully
docker image ls bigeyedata/agent:latest

Running without docker compose

It's possible to use docker run directly if a newer version of docker that has docker compose is not available.

# “docker logout” is required first if you are already logged in as a different account

docker login --username bigeyedata --password <docker access token>

docker pull docker.io/bigeyedata/agent:latest

docker run -d --name bigeye-agent -v ${PWD}/agent_config:/app/config/ --restart always docker.io/bigeyedata/agent:latest

docker logs bigeye-agent

AWS Secrets manager

The agent can read your data source password from AWS Secrets Manager instead of having the password in plain text in agent.yaml. To use it, use the following example snip below in your agent.yaml. The aws credentials are used by the agent to read the secret from AWS Secrets Manager.

# The AWS access key and secret key are used by the agent to read from AWS secrets manager
awsAccessKey: AKIAIOSFODNN7EXAMPLE (ie what normally goes in AWS_ACCESS_KEY_ID)
awsSecretKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY (ie what normally goes in AWS_SECRET_ACCESS_KEY)
region: us-east-1 (AWS region where AWS secrets manager secret resides)

sources:
  - identifier: some snowflake db1 using aws secrets manager for password
    connectionFactory:
      type: snowflake
      host: mycompany.snowflakecomputing.com
      port:
      user: user
      # AWS Secrets Manager secret name
      asmSecretNameForPassword: my/aws/secret_manager/secret_name
      databaseName: somedb1

Environment variable for password

The agent.yaml can accept environment variables in place of the plain text. This is useful for things like data source credentials. Update agent.yaml to use an environment variable for the user and password like shown below. The syntax is specific, do not wrap the variable in quotes: ${good} "${bad}"

# Example data source using environment vars for credentials
  - identifier: db with env vars for creds
    connectionFactory:
      type: snowflake
      host: mycompany.snowflakecomputing.com
      port: 443
      user: ${SECRET_USERNAME}
      password: ${SECRET_PASSWORD}
      databaseName: somedb

Then update docker-compose.yaml to pass through the environment variables (last 3 lines):

version: "3.9"
services:
  bigeye-agent:
    image: "docker.io/bigeyedata/agent:latest"
    restart: always
    volumes:
      - "${PWD}/agent_config:/app/config"

    environment:
      - SECRET_USERNAME
      - SECRET_PASSWORD

Write a script that can retrieve the credentials

Finally write a script that can retrieve secrets from your password keeper (HashiCorp Vault, Azure Key Vault, etc) and use that to populate the environment variables

export SECRET_USERNAME=$(username_script.sh)
export SECRET_PASSWORD=$(password_script.sh)

docker compose up

(Optional) Automate

There are many ways of automating this. A low effort way would be to put the variable exports into your .bashrc or .bash_profile so the environment variable is populated on login, then you don't have to remember to set it before running docker compose up.

Description of files in the agent_config directory

This is a catalog of the files that get created during agent setup in agent_config and a description of what they are used for.

Configuration

• agent.yaml - Configuration file for the agent. Datasource connection info goes here, along with flags for the agent to enable query logging, setting company uuid etc.
• mtls.conf, mtls_ca.conf - only used one time for generating mTLS certs

Encryption certs (encryption at rest)

• <company_uuid>.pem, bigeye.pem - these are used for signing/verifying signing of encryption key pair
• private.pem - public certificate used to encrypt payloads for the agent
• private.key - private key used to decrypt payloads from Bigeye

mTLS certs (2nd level of encryption, encryption in transit)

• mtls.key - private key used in mTLS connections with Bigeye infrastructure
• mtls.pem - public certificate used in mTLS connections with Bigeye infrastructure
• mtls_ca.key - private key to use as a certificate authority for self-signing mtls certs
• mtls_ca.pem - public certificate for local certificate authority. This is sent to Bigeye so it can be trusted from Bigeye's infrastructure. Bigeye's infrastructure will then trusts connections using mtls key pairs that are generated from the mtls_ca.key
• bigeye_workflows_ca.pem - public certificate for Bigeye's CA. This allows the agent to trust connections from Bigeye infrastructure.

Use custom trusted CA certificates

You may wish to use mTLS certificates signed by your own internal certificate authority for connecting to data sources. The agent supports adding additional certificates to the trusted CA list as of agent version 1.0.6.

To use additional CA trust certificates with the agent, put your custom certs in a new subdirectory agent_config/user_ca and restart the agent. The agent will import all CA certificates in that directory into its trust list.

mkdir agent_config/user_ca

# Copy the CA certificate file to the new directory
cp < path to CA certificate file > agent_config/user_ca/

# Restart the container to load the new CA certificates
docker compose restart 

Note" The CA certificates file names must end in .pem (i.e. custom_ca.pem).

Use a proxy

If all requests on your VM for the Bigeye agent are required to go through a proxy, then there may be some additional steps required to get everything installed successfully.

1. Configure docker daemon with systemd file

   1. See official docker documentation here - This is required to be able to login and pull images from our private docker repository where the bigeye agent images are hosted.
   2. If this step is missed, then when running docker login you will receive this error message.
      Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout

2. Set the HTTP_PROXY and HTTPS_PROXY environment variables for the VM

   1. In order to download our docker compose file, you will need to set these environment variables using the below commands. This will allow you to run the wget command in our instructions to download our docker compose file.
   2. bash

      export HTTP_PROXY=http://someproxy.etc.com:8080
      export HTTPS_PROXY=http://someproxy.etc.com:8080
      

3. Configure your docker config.json to use a proxy server

   1. See official docker documentation here - This is required to configure the Docker CLI to use proxies via environment variables in containers.
   2. If this step is missed, then you will have errors while running the setup script for the bigeye agent.

4. Update the Bigeye docker-compose.yaml file

   1. Set the proxy settings in the bigeye docker-compose.yaml file so that the Bigeye agent knows to forward all requests through that proxy. See example below, the proxy settings should be placed using the JDK_JAVA_OPTIONS variable under the environment section of the docker-compose.yaml file.
   YAML

   JDK_JAVA_OPTIONS=-Dhttp.proxyHost=someproxy.etc.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=someproxy.etc.com -Dhttps.proxyPort=8080