Configuring the Gremlin Agent

This documentation page shows you how to configure the Gremlin Agent. You can configure Gremlin using either environment variables or a configuration file, although we recommend using the configuration file in most cases. This guide assumes you've already installed and authenticated the Agent.

Using the configuration file

Gremlin's configuration file is located in a file named ^config.yaml. On Linux, this file lives at ^{/etc/gremlin/config.yaml}, and on Windows, its path is ^{C:\ProgramData\Gremlin\Agent\config.yaml}. By default, Gremlin ships with a commented-out version of this file. Use the comments or the following example to set up your configuration.

‍

Accepted variables

‍

Example: config.yaml

‍

Restarting the Gremlin Agent

To restart the Gremlin Agent and apply your new changes, run the following commands (depending on your environment):

‍

Linux

sudo systemctl restart gremlind

‍

Windows

Restart-Service -Name gremlind

‍

Using environment variables

The daemon supports the following environment variables. For AWS users, Gremlin supports ARN values from AWS Secrets Manager or AWS Systems Manager Parameter Store.

‍

The following are optional environment variables that may be required in containerized or cloud deployments:

‍

In addition, the following standard Linux environment variables allow proxy configuration:

‍

Configuration value priorities

If both the environment variables and the configuration file are used when configuring Gremlin, the environment variable values will take priority. For example if you have the GREMLIN_IDENTIFIER environment variable set to foo and in the config.yaml file the identifier field is set to bar, Gremlin will end up using foo as its identifier when registering with the API.

Remote config values

The Gremlin agent supports using AWS ARNs for the following config values in either ENVVARs or config file:

• identifier
• team_id
• team_secret
• team_certificate
• team_private_key
• tls_identity_certificate
• tls_identity_private_key

When remote configuration values are used, Gremlin does not store the corresponding configuration values on the hard disk of the system where it runs. When Gremlin is configured to use Secret Authentication option (i.e. using a team_secret), the agent must store temporary session tokens in the .credentials file, which is only readable by the Gremlin system user.

The following services are supported for reading values:

• ssm
• secretsmanager

The agent requires some credentials to exist on the machine to be able to retrieve the remote values.The credentials preference follows the default AWS order.

Passing environment variables to Systemd or SysV

While configuring the daemon with config.yaml is recommended, process managers like systemd and sysvinit can pass environment variables directly to the daemon process from /etc/default/gremlind. Your installation comes with an example of this file at /etc/default/gremlind.example

# Gremlin Identifier; uniquely identifies this machine with Gremlin
GREMLIN_IDENTIFIER=gremlin-01

# Gremlin Team ID; you can find this value at https://app.gremlin.com/settings/teams
GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111

# `gremlin init` will run automatically when the gremlind service starts.
# Supply extra options to `gremlin init` via this variable
GREMLIN_INIT_OPTS="--tag service=pet-store --tag interface=http"

# Gremlin Team Secret, should not be set when using `team_certificate`+`team_private_key`
GREMLIN_TEAM_SECRET=11111111-1111-1111-1111-111111111111

‍

You can set any of the environment variables listed in the previous section in the configuration file.

Tags

The Gremlin Agent automatically detects tags from the host system, such as operating system, zone, and local hostname. Gremlin also detects additional tags from certain cloud providers, including Amazon Web Services and Azure. You can also create custom tags and assign them to your Gremlin Agent(s) during installation. See Network Tags for instructions on adding custom tags to Gremlin.

‍

DNS Collection

In order to run dependency tests using Gremlin Reliability Management (RM), the Gremlin agent must be configured to collect DNS data by enabling DNS Collection. When DNS Collection is enabled, the Gremlin Agent collects DNS information from hosts, containers, and Kubernetes objects, and uses it to detect dependencies.

To learn more about enabling or disabling DNS collection, see DNS Collection.

‍

Client TLS Identity for Mutual TLS (mTLS)

The gremlind and gremlin-integrations agents support setting a TLS identity to enable mutual TLS. The following values are required for setting that up:

• tls_identity_certificate: A PEM-encoded certificate chain, starting with the leaf certificate, followed by its intermediates.
• tls_identity_private_key: A PEM-encoded private key.
• service_url: The URL of your mTLS gateway.

Values can be set directly into config.yaml , referenced as paths on the file system, or ARNs to secrets in AWS (see Remote config values).

For Kubernetes users, upgrade to Helm Chart 0.25.0 and supply values under gremlin.tls.identity and chao.tls.identity.

‍

Private Edition configuration

For Gremlin Private Edition users, you will need to change the URL that the agent uses to communicate with Gremlin from the public Gremlin API to your Private Edition instance. You can do this by setting the gremlin.serviceUrl option (or the GREMLIN_SERVICE_URL environment variable) to the URL of your instance, with the suffix v1. For example, this will configure the agent to send requests to a local Private Edition instance:

# config.yaml
service_url: https://api.gremlin.yourdomain.com/v1

‍

Customize Gremlin's Linux user and group

By default, Gremlin installs a gremlin user and group with the necessary privileges to perform all Gremlin features. These defaults can be overridden at installation time by supplying environment variables to the installer. The full list of variables available at install time and their defaults are as follows:

‍

For example, to run Gremlin as root and restrict executable access to root:root, run:

GREMLIN_INSTALL_USER=root GREMLIN_INSTALL_GROUP=root GREMLIN_INSTALL_BIN_MODE=0770 \
  sudo -E yum install gremlin gremlind

‍

helm upgrade --install gremlin gremlin/gremlin \
    --namespace gremlin --create-namespace \
    --set gremlin.secret.managed=true \
    --set gremlin.secret.type=secret \
    --set gremlin.secret.teamID=${GREMLIN_TEAM_ID} \
    --set gremlin.secret.clusterID=${GREMLIN_CLUSTER_ID} \
    --set gremlin.secret.teamSecret=${GREMLIN_TEAM_SECRET} \
    --set-file ssl.certFile=./ssl_cert_file.pem \
    --set gremlin.tls.identity.enabled=true \
    --set gremlin.tls.identity.existingSecret.name=gateway-client \
    --set chao.tls.identity.enabled=true \
    --set chao.tls.identity.existingSecret.name=gateway-client \
    --set gremlin.serviceUrl=${GREMLIN_SERVICE_URL}