# Deploying an Agent The Agent docker image can be configured via environment variables or via volume mounts for the configuration files. ## Running the Docker {% hint style="warning" %} Please check "File configuration" before running the command {% endhint %} {% code title="terminal" %} ```bash docker run --name lenses-agent \ -v $(pwd)/provisioning.yaml:/mnt/provision-secrets/provisioning.yaml \ -v $(pwd)/lenses-agent.conf:/data/lenses-agent.conf \ -e LENSES_PROVISIONING_PATH=/mnt/provision-secrets \ lensesio/lenses-agent:6.0 ``` {% endcode %} *** ### Provisioning {% stepper %} {% step %} #### Configure HQ To see be able to view and drilling to your Kafka environment, you need to connect the agent to HQ. You need to create an environment in HQ and copy the Agent Key into the **provisioning.yaml.**

Create new Environment and obtain agent key

{% tabs %} {% tab title="TLS Enabled" %} {% code title="provisioning.yaml" %} ```yaml lensesHq: - name: lenses-hq version: 1 tags: ['hq'] configuration: server: value: [LENSES_HQ_URL] port: value: 10000 agentKey: value: ${LENSES_HQ_AGENT_KEY} sslEnabled: value: true sslTruststore: file: "hq-truststore.jks" sslTruststorePassword: value: ${LENSES_HQ_AGENT_TRUSTSTORE_PWD} ``` {% endcode %} {% endtab %} {% tab title="TLS Disabled" %} {% code title="provisioning.yaml" %} ```yaml lensesHq: - name: lenses-hq version: 1 tags: ['hq'] configuration: server: value: [LENSES_HQ_URL] port: value: 10000 agentKey: value: ${LENSES_HQ_AGENT_KEY} sslEnabled: value: false ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="info" %} **Agent key reference** Agent key within provisioning.yaml can be referenced as a: * environment variable shown in example above * inline string {% endhint %} {% endstep %} {% step %} #### Configure Kafka {% hint style="info" %} Bare in mind that each Agent connects to one Kafka cluster. {% endhint %} There are many Kafka flavours today in the market. Good news is that Lenses support all flavours of Kafka and we are trying hard to keep documentation up to date. In the following [link](/latest/devx/6.0/deployment/configuration/agent/automation/kafka.md) you can find provisioning examples for the most common Kafka flavours. #### Other connections There are also provisioning examples for other components: * [Schema Registry](/latest/devx/6.0/deployment/configuration/agent/automation/schema-registries.md) * [Kafka Connect](/latest/devx/6.0/deployment/configuration/agent/automation/kafka-connect.md) * [Zookeeper](/latest/devx/6.0/deployment/configuration/agent/automation/zookeeper.md) * [AWS](/latest/devx/6.0/deployment/configuration/agent/automation/aws.md) * [Alerts & Audit integrations](/latest/devx/6.0/deployment/configuration/agent/automation/alert-and-audit-integrations.md) {% endstep %} {% step %} #### Configure Database {% hint style="warning" %} Bare in mind that each Agent requires separate database. Two Agents sharing the same database can lead to racing condition issue. {% endhint %} Last step is to configure a database to which Agent will be connecting to. #### Running Agent with Postgres database {% code title="lenses-agent.conf" %} ```apacheconf lenses.storage.postgres.host="dbname" lenses.storage.postgres.database="agentdb" lenses.storage.postgres.username="agentusername" lenses.storage.postgres.password="changeme" lenses.storage.postgres.port="5432" lenses.storage.postgres.schema="myschema" ``` {% endcode %} #### Running Agent with H2 embedded database {% hint style="warning" %} Embedded database is not recommended to be used in Production or high load environments. {% endhint %} In order to run Agent with embedded database, your *lenses-agent.conf* **should not** carry any property starting with *lenses.storage.postgres.\* * {% endstep %} {% endstepper %} *** ## Provisioning example file This provisioning file includes connections to: * [x] Kafka Cluster * [x] Schema Registry * [x] Kafka Connect * [x] Lenses HQ
provisioning.yaml {% code title="provisioning.yaml" %} ```yaml lensesHq: - configuration: agentKey: value: agent_key_* port: value: 10000 server: value: current-lenses-hq.panoptes.svc.cluster.local sslEnabled: value: false name: lenses-hq tags: - hq version: 1 kafka: - configuration: kafkaBootstrapServers: value: - PLAINTEXT://prod-1-kafka-bootstrap.kafka-prod.svc.cluster.local:9092 metricsPort: value: 9999 metricsType: value: JMX protocol: value: PLAINTEXT name: kafka tags: - prod - prod-1 - us version: 1 confluentSchemaRegistry: - configuration: schemaRegistryUrls: value: - http://schema-registry-prod.kafka-prod.svc.cluster.local:8081 name: schema-registry tags: - prod - global version: 1 connect: - configuration: workers: value: - http://prod-1-connect-connect.kafka-prod.svc.cluster.local:8083 name: datalake-connect tags: - prod - us version: 1 ``` {% endcode %}
*** ## File configuration In order for command above provisioning yaml has to be configured. There are two mandatory connections: 1. HQ which requires AgentKey (*LENSESHQ\_AGENT\_KEY) -* this key is being created once user registers "New environment" in HQ; 2. Kafka connection {% code title="provisioning.yaml" lineNumbers="true" %} ```yaml lensesHq: - configuration: agentKey: value: ${LENSESHQ_AGENT_KEY} port: value: 10000 server: value: hq name: lenses-hq tags: - hq version: 1 kafka: - configuration: kafkaBootstrapServers: value: - PLAINTEXT://kafka:9092 protocol: value: PLAINTEXT name: kafka tags: - demo version: 1 ``` {% endcode %} *** ## Environment Variables Environment variables prefixed with **LENSES\_** are transformed into corresponding configuration options. The environment variable name is converted to lowercase and underscores (**\_**) are replaced with dots (**.**). As an example set the option **lenses.port** use the environment variable **LENSES\_PORT**. Alternatively, the **lenses-agent.conf** can be mounted directly as * **/mnt/settings/lenses-agent.conf** *** ## Docker volumes The Docker image exposes four volumes in total, where cache, logs, plugins, and persistent data are stored: * /data/storage * /data/plugins * /data/logs * /data/kafka-streams-state ### Storage volume Resides under **/data/storage** and is used to store persistent data, such as Data Policies. For this data to survive between Docker runs and/or Agent upgrades, the volume must be managed externally (persistent volume). ### Plugins volume Resides under **/data/plugin**`s` it’s where classes that extend Agent may be added —such as custom Serdes, LDAP filters, UDFs for the Lenses SQL table engine, and custom\_http implementations. ### Logs volume Resides under **/data/logs**, logs are stored here. The application also logs to stdout, so the log files aren’t needed for most cases. ### KStreams state volume Resides under **/data/kafka-streams-state**, used when Lenses SQL is in IN\_PROC configuration. In such a case, Lenses uses this scratch directory to cache Lenses SQL internal state. Whilst this directory can safely be removed, it can be beneficial to keep it around, so the Processors won’t have to rebuild their state during a restart. *** ## Agent TLS and Global JVM Trust Store By default, the the serves connections over plaintext (HTTP). It is possible to use TLS instead. The Docker image offers the ability to provide the content for extra files via secrets mounted as files or as environment variables. Especially for SSL, Docker supports SSL/TLS keys and certificates in Java Keystore (JKS) formats. This capability is optional, and users can mount such files under custom paths and configure **lenses-agent.conf** manually via environment variables, or **lenses.append.conf**. There are two ways to use the File/Variable names of the table below. 1. Create a file with the appropriate filename as listed below and mount it unde**r /mnt/settings, /mnt/secrets, or /run/secrets** 2. Set them as environment variables. All settings except for passwords, can be optionally encoded in base64. The docker will detect such encoding automatically. | File / Variable Name | Description | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FILECONTENT\_JVM\_SSL\_TRUSTSTORE | The SSL/TLS trust store to use as the global JVM trust store. Add to LENSES\_OPTS the property javax.net.ssl.trustStore | | FILECONTENT\_JVM\_SSL\_TRUSTSTORE\_PASSWORD | Τhe trust store password. If set, the startup script will add automatically to LENSES*OPTS the property javax.net.ssl.trustStorePassword (\*\*\_base64 not supported*\*\*) | | FILECONTENT\_LENSES\_SSL\_KEYSTORE | The SSL/TLS keystore to use for the TLS listener for the Agent | *** ## Process UID/GUI The docker does not require running as root. The default user is set to root for convenience and to verify upon start-up that all the directories and files have the correct permissions. The user drops to **nobody** and group **nogroup** (**65534:65534**) before starting the Agent. If the image is started without root privileges, the agent will start successfully using the effective uid:gid applied. Ensure any volumes mounted (i.e., for the settings and data) have the correct permission set. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.lenses.io/latest/devx/6.0/deployment/installation/docker/agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.