Agent Connection
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.
- Set up a VM / host (infrastructure requirements below)
- Bigeye credentials
- You will need a Bigeye account.
- The user must be an Admin or an Owner role in Bigeye.
- Company prefix
- This is the first part of your Bigeye URL (e.g. “app” for app.bigeye.com)
- docker access token
- Bigeye will provide this
Infrastructure Requirements
- Host with docker installed and running
- Other Docker platforms such as AWS ECS, or orchestration systems such as Kubernetes will work, but their installation is not directly supported by Bigeye.
- Install docker if it is not already intalled [CentOS][RHEL][Debian][Ubuntu]
- NOTE for RHEL, the official docker instructions don't quite work. Using docker's CENTOS yum repository instead is a good workaround.
-
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
- You can test if docker is running by using
docker info
and getting a non-error response
docker compose
should already work if you've installed docker with the above instructions. If not, Install docker compose (Instructions- Run
docker compose version
to test if it is installed correctly. The version should be 2.0 or higher.
- Run
- Minimum HW size: 4 CPU, 8GB mem (ie AWS t3.xlarge, GCP e2-standard-4, Azure B4/D4, etc)/
- 25GB disk space on /var is recommended
- Network access for agent subnets
- No ingress (inbound) networking access for the agent is required (other than for internal administration ie SSH)
- Egress (outbound) Access to the data sources you wish to add to Bigeye for monitoring
- Egress (outbound) Access to the Bigeye Saas environment to pull work
- 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.
- Go to _Catalogs _view
- Select the Add source button in the upper right hand
- Select the data source type (ie. Snowflake)
- Select Connect with in-VPC agent
- 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”
PORT STATE SERVICE 443/tcp open https
- Find out why network connectivity is not working and resolve
- Check that workflowUrl is set correctly in
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.
-
Configure docker daemon with systemd file
- 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.
- 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
-
Set the
HTTP_PROXY
andHTTPS_PROXY
environment variables for the VM- 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. -
export HTTP_PROXY=http://someproxy.etc.com:8080 export HTTPS_PROXY=http://someproxy.etc.com:8080
- 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
-
Configure your docker
config.json
to use a proxy server- See official docker documentation here - This is required to configure the Docker CLI to use proxies via environment variables in containers.
- If this step is missed, then you will have errors while running the setup script for the bigeye agent.
-
Update the Bigeye docker-compose.yaml file
- 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.
JDK_JAVA_OPTIONS=-Dhttp.proxyHost=someproxy.etc.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=someproxy.etc.com -Dhttps.proxyPort=8080
- 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
Updated 25 days ago