Configuring Environments

Create a Lenses environment, start its agent, and connect Kafka services

Use an environment to represent one Kafka setup in Lenses. Each environment needs one Lenses Agent. The agent authenticates to Lenses with an agent key, then connects to Kafka and other services with a provisioning file.

For the core model, see Concepts.

Before you start

Make sure you have:

1. access to Lenses

2. Kafka broker addresses

3. any Schema Registry, Kafka Connect, alerting, or monitoring endpoints you use

4. any TLS or mTLS JKS files

5. network access from the agent to each target service

Create the environment

Open Environments from the left navigation. Select + in the header, or use the action on Home.

Enter:

• environment name

• optional description

• tier, such as dev, staging, or prod

After you create the environment, copy the agent key.

The agent key connects the agent to Lenses. It does not configure Kafka or any other service.

Start the agent

Copy the startup command shown in the UI and run it where your agent will live.

The generated command assumes the default Lenses Docker Compose network. If you run the agent elsewhere, update hostnames, ports, and network routing to match your deployment.

Configure service connections

When the agent appears, select Start configuration. You can also wait for the agent to connect first, then open the configuration tab.

If the agent starts with only an agent key, it connects to Lenses only. It does not connect to Kafka until you apply a provisioning file. For automation details, see Provisioning. The schema is available in the JSON schema repository.

The configuration editor uses YAML. Use the left-side presets and toggles to insert starter blocks into the editor.

Select the connection type and preset that matches your setup. For example, Kafka over mTLS or Confluent Cloud. Then replace every placeholder value with real settings, such as broker addresses, usernames, ports, and secrets.

Fill in every required value before you test or apply. Use the editor problem panel to catch missing or invalid fields.

Some connection types support more than one entry. Common examples are Kafka Connect clusters and alert or monitoring integrations.

TLS and mTLS files

If your services use TLS or mTLS, upload the required JKS files before you apply the configuration.

Uploaded file names must exactly match the file names referenced in the editor. For example, kafka-truststore.jks.

Metrics and advanced settings

The presets do not cover every option. The placeholder YAML includes extra sections as comments. Uncomment and edit those blocks when you need metrics or advanced settings.

Test the configuration

Select the beaker icon in the top-right of the editor to test the provisioning file.

Lenses validates the file and shows errors in the editor and the problem panel.

Apply the configuration

Select Apply to Agent when the test passes. Then open Agent Logs to follow startup and service connection status.

Initial discovery can take a few minutes. Topics and optional services may appear gradually.

Verify the environment

Confirm these checks after apply:

1. the agent shows as connected

2. Kafka appears in the environment

3. topics start loading

4. optional services, such as Schema Registry or Kafka Connect, appear if configured

5. Agent Logs show successful connections and no repeated errors

Troubleshooting

If the environment does not connect, check:

1. the agent key is correct

2. broker addresses and ports are reachable from the agent

3. TLS or mTLS files are uploaded and named exactly as referenced

4. the YAML has no validation errors

5. credentials and secrets are valid

6. firewalls, DNS, and container networking allow access to each service