# How to convert Wizard Mode to Provisioning Mode

## Migrating from Lenses Wizard Mode to Provision

### Overview

Lenses 5.0+ introduces two primary methods for configuring your Lenses instance:

* **Wizard Mode**: An interactive UI-based setup that appears when no Kafka brokers are configured
* **Provision Mode**: A programmatic approach using `provisioning.yaml` configuration with(out) sidecar containers

This guide walks you through migrating from the Wizard Mode setup to a fully automated Provision configuration, enabling GitOps workflows and Infrastructure as Code practices.

### Understanding the Migration Path

#### When to Consider Migration

You should migrate from Wizard Mode to Provision when you need:

* **Automated deployments** and Infrastructure as Code
* **GitOps workflows** for configuration management
* **Consistent environments** across development, staging, and production
* **Version control** for your Lenses configuration
* **Scalable deployment** patterns for multiple Lenses Agent instances
* Migrating from Lenses ⅘ to Lenses 6 Agent

#### Key Differences

| Aspect                    | Wizard Mode    | Provision Mode                       |
| ------------------------- | -------------- | ------------------------------------ |
| **Setup Method**          | Interactive UI | YAML configuration                   |
| **Automation**            | Manual         | Fully automated                      |
| **Version Control**       | Not supported  | Full Git integration                 |
| **Secrets Management**    | Manual entry   | Kubernetes secrets + file references |
| **Deployment**            | One-time setup | Repeatable deployments               |
| **Configuration Updates** | UI-based       | Code-based with CI/CD                |

### Pre-Migration Checklist

Before starting your migration, please check [Tips: Before Upgrade](https://docs.lenses.io/latest/deployment/upgrade-to-lenses-6/tips-before-upgrade)

{% stepper %}
{% step %}
**Assess Agent Connections that have to be migrated from Lenses 5**

In the picture below it is visible that three connections has to be migrated to `provisioning.yaml` file:

1. Kafka
2. SchemaRegistry
3. KafkaConnect

in addition to that a new connection has to be made called **LensesHQ.**

<figure><img src="https://3629020462-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoxgTiTb4MZT9IGHAYUTn%2Fuploads%2Fgit-blob-d943d7d89e1accb23fd4e75db0145efc0c47ab54%2FScreenshot%202025-09-12%20at%2010.20.18%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Prepare Your Provision Configuration**

**Basic Structure**

For **Helm Deployment:**

* create a **`values.yaml` file** with the provision configuration enabled

**For deployment from Archive** create:

* **`lenses-agent.conf`** and
* **`provisioning.yaml` file**

Connections that provisioning is going to have:

* Kafka;
* SchemaRegistry;
* KafkaConnect;
* LensesHQ.
  {% endstep %}

{% step %}
**Configure Kafka Connection**

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: <your-HQ-generated-agentKey>
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: <your-HQ-address>
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
      kafka:
        - name: kafka
          version: 1
          tags: [ "prod", "prod-1", "us"]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://<your-kafka-address>:9092
            metricsType:
             value: JMX
            metricsPort:
             value: 9999
```

{% endcode %}

For more Kafka connection details, such as using secure connections, see [Kafka](https://docs.lenses.io/latest/deployment/configuration/agent/automation/kafka).
{% endtab %}

{% tab title="Archive Deployment" %}
{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Configure Additional Services Connections**

Last two bits are:

* **Kafka Connect** and
* **Schema Registry**

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: <your-HQ-generated-agentKey>
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: <your-HQ-address>
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
      kafka:
        - name: kafka
          version: 1
          tags: [ "prod", "prod-1", "us"]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://<your-kafka-address>:9092
            metricsType:
             value: JMX
            metricsPort:
             value: 9999
      confluentSchemaRegistry:
        - name: schema-registry
          version: 1
          tags: [ "prod", "global" ]
          configuration:
            schemaRegistryUrls:
              value:
                - http://<your-schema-registry-address>:8081
      connect:
        - name: datalake-connect
          version: 1
          tags: [ "prod", "us" ]
          configuration:
            workers:
              value:
                - http://<your-kafka-connect-address>:8083
```

{% endcode %}
{% endtab %}

{% tab title="Archive Deployment" %}
{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
confluentSchemaRegistry:
- configuration:
    schemaRegistryUrls:
      value:
      - http://<your-schemaregistry-address>:8081
  name: schema-registry
  tags:
  - prod
  - global
  version: 1
connect:
- configuration:
    workers:
      value:
      - http://<your-kafkaconnect-address>:8083
  name: datalake-connect
  tags:
  - prod
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Prepare HQ Connection**

Through last few steps, we covered configuring of:

* Kafka
* Schema Registry
* Kafka Connect connections.

Last but not least and probably the most important one is creating HQ connection otherwise Agent won't be useable.

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: <your-HQ-generated-agentKey>
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: <your-HQ-address>
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
```

{% endcode %}
{% endtab %}

{% tab title="Archive Deployment" %}
{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**License configuration is part of Lenses HQ from version 6.**
{% endhint %}
{% endstep %}

{% step %}
**Configure Database details**

In case Postgres is being used:

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
lensesAgent:
  storage:
    postgres:
      enabled: true
      host: postgres-1.postgres.svc.cluster.local
      port: 5432              # optional, defaults to 5432
      username: prod          
      password: external      # use "external" to manage it using secrets
      database: agent
  additionalEnv:
    - name: LENSES_STORAGE_POSTGRES_PASSWORD
      valueFrom:
        secretKeyRef:
          name: local-postgres-pwd
          key: password
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: agent_key_*
    ssl:
      enabled: false
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: lenses-hq.lenses.svc.cluster.local
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
      kafka:
        - name: kafka
          version: 1
          tags: [ "prod", "prod-2", "eu"]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://testing-kafka-bootstrap.kafka.svc.cluster.local:9092
            metricsType:
             value: JMX
            metricsPort:
             value: 9999
      connect:
        - name: datalake-connect
          version: 1
          tags: [ "prod-2", "eu" ]
          configuration:
            workers:
              value:
                - http://testing-connect-connect.kafka-connect.svc.cluster.local:8083
      confluentSchemaRegistry:
        - name: schema-registry
          version: 1
          tags: [ "prod", "global" ]
          configuration:
            schemaRegistryUrls:
              value:
                - http://testing-schema-registry.schema-registry.svc.cluster.local:8081
```

{% endcode %}
{% endtab %}

{% tab title="Archive Deployment" %}
You would have to use two files:

* ***lenses-agent.conf***
* ***provisioning.yaml***

{% code title="lenses-agent.conf" %}

```apacheconf
# Auto-detected env vars

lenses.secret.file=/data/security.conf

# lenses.append.conf

lenses.storage.postgres.host="postgres-1.postgres.svc.cluster.local"
lenses.storage.postgres.database="agent"
lenses.storage.postgres.username="agent"
lenses.storage.postgres.password="pleasechangeme"
lenses.storage.postgres.port="5432"
lenses.provisioning.path="/mnt/provision-secrets"
```

{% endcode %}

{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
confluentSchemaRegistry:
- configuration:
    schemaRegistryUrls:
      value:
      - http://<your-schemaregistry-address>:8081
  name: schema-registry
  tags:
  - prod
  - global
  version: 1
connect:
- configuration:
    workers:
      value:
      - http://<your-kafkaconnect-address>:8083
  name: datalake-connect
  tags:
  - prod
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="danger" %}
**H2** as a storage mechanism **is available** only **from** Agent **v6.0.6**

**Be aware that** H2 is **not recommended** for **production** environments
{% endhint %}

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
persistence:
  storageH2:
    enabled: true
    accessModes:
      - ReadWriteOnce
    size: 5Gi

lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: agent_key_*
    ssl:
      enabled: false
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: lenses-hq.lenses.svc.cluster.local
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
      kafka:
        - name: kafka
          version: 1
          tags: [ "prod", "prod-2", "eu"]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://testing-kafka-bootstrap.kafka.svc.cluster.local:9092
            metricsType:
             value: JMX
            metricsPort:
             value: 9999
      connect:
        - name: datalake-connect
          version: 1
          tags: [ "prod-2", "eu" ]
          configuration:
            workers:
              value:
                - http://testing-connect-connect.kafka-connect.svc.cluster.local:8083
      confluentSchemaRegistry:
        - name: schema-registry
          version: 1
          tags: [ "prod", "global" ]
          configuration:
            schemaRegistryUrls:
              value:
                - http://testing-schema-registry.schema-registry.svc.cluster.local:8081
```

{% endcode %}
{% endtab %}

{% tab title="Untitled" %}
You would have to use two files:

* ***lenses-agent.conf***
* ***provisioning.yaml***

{% code title="lenses-agent.conf" %}

```apacheconf
# Auto-detected env vars
lenses.secret.file=/data/security.conf
# lenses.append.conf
lenses.provisioning.path="/mnt/provision-secrets"
```

{% endcode %}

{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
confluentSchemaRegistry:
- configuration:
    schemaRegistryUrls:
      value:
      - http://<your-schemaregistry-address>:8081
  name: schema-registry
  tags:
  - prod
  - global
  version: 1
connect:
- configuration:
    workers:
      value:
      - http://<your-kafkaconnect-address>:8083
  name: datalake-connect
  tags:
  - prod
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

### Complete Migration Example

Here's a complete `values.yaml` and `lenses-agent + provisioning.yaml` example for a production migration:

{% hint style="success" %}
For more Helm options, please check [lenses-helm-chart](https://github.com/lensesio/lenses-helm-charts/tree/release/6.1/charts/lenses-agent#parameters) repo.
{% endhint %}

{% tabs %}
{% tab title="Helm Deployment" %}
{% code title="values.yaml" %}

```yaml
rbacEnable: true
namespaceScope: true

lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: lenses-agent-secret
        value: agent_key_*
    ssl:
      enabled: false
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: lenses-hq.lenses.svc.cluster.local
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
      kafka:
        - name: kafka
          version: 1
          tags: [ "prod", "prod-2", "eu"]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://testing-kafka-bootstrap.kafka.svc.cluster.local:9092
            metricsType:
             value: JMX
            metricsPort:
             value: 9999
      connect:
        - name: datalake-connect
          version: 1
          tags: [ "prod-2", "eu" ]
          configuration:
            workers:
              value:
                - http://testing-connect-connect.kafka-connect.svc.cluster.local:8083
      confluentSchemaRegistry:
        - name: schema-registry
          version: 1
          tags: [ "prod", "global" ]
          configuration:
            schemaRegistryUrls:
              value:
                - http://testing-schema-registry.schema-registry.svc.cluster.local:8081
  storage:
    postgres:
      enabled: true
      host: postgres-1.postgres.svc.cluster.local
      port: 5432              # optional, defaults to 5432
      username: prod          
      password: external      # use "external" to manage it using secrets
      database: agent
  additionalEnv:
    - name: LENSES_STORAGE_POSTGRES_PASSWORD
      valueFrom:
        secretKeyRef:
          name: local-postgres-pwd
          key: password
```

{% endcode %}
{% endtab %}

{% tab title="Archive Deployment" %}
You would have to use two files:

* ***lenses-agent.conf***
* ***provisioning.yaml***

{% code title="lenses-agent.conf" %}

```apacheconf
# Auto-detected env vars

lenses.kubernetes.pod.mem.request=128M
lenses.kubernetes.pod.mem.limit=1152M
lenses.jmx.port=9101
lenses.kubernetes.pod.liveness.initial.delay="60 seconds"
lenses.sql.execution.mode=KUBERNETES
lenses.topics.metrics=_kafka_lenses_metrics
lenses.provisioning.path="/mnt/provision-secrets"
lenses.topics.external.topology=__topology
lenses.kubernetes.pod.min.heap=128M
lenses.port=3030
lenses.kubernetes.pod.heap=1024M
lenses.topics.external.metrics=__topology__metrics

lenses.secret.file=/data/security.conf

# lenses.append.conf

lenses.storage.postgres.host="postgres-1.postgres.svc.cluster.local"
lenses.storage.postgres.database="agent"
lenses.storage.postgres.username="agent"
lenses.storage.postgres.password="pleasechangeme"
lenses.storage.postgres.port="5432"
lenses.provisioning.path="/mnt/provision-secrets"
```

{% endcode %}

{% code title="provisioning.yaml" %}

```yaml
lensesHq:
- configuration:
    agentKey:
      value: <your-HQ-generated-agentKey>
    port:
      value: 10000
    server:
      value: <your-HQ-address>
    sslEnabled:
      value: false
  name: lenses-hq
  tags:
  - hq
  version: 1
kafka:
- configuration:
    kafkaBootstrapServers:
      value:
      - PLAINTEXT://<your-kafka-address>:9092
    metricsPort:
      value: 9999
    metricsType:
      value: JMX
  name: kafka
  tags:
  - prod
  - prod-1
  - us
  version: 1
confluentSchemaRegistry:
- configuration:
    schemaRegistryUrls:
      value:
      - http://<your-schemaregistry-address>:8081
  name: schema-registry
  tags:
  - prod
  - global
  version: 1
connect:
- configuration:
    workers:
      value:
      - http://<your-kafkaconnect-address>:8083
  name: datalake-connect
  tags:
  - prod
  - us
  version: 1
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Deployment and Testing

{% stepper %}
{% step %}
**Deploy with Helm**

**Add the Lenses Helm repository:**

```bash
helm repo add lenses-agent https://helm.repo.lenses.io
helm repo update
```

**Deploy Lenses with your provision configuration:**

```bash
helm install lenses-agent lenses/lenses-agent \
  --namespace lenses \
  --create-namespace \
  -f values.yaml
```

**Monitor the deployment:**

```bash
kubectl get pods -n lenses -w
kubectl logs -n lenses deployment/lenses-agent
```

{% endstep %}

{% step %}
**Deploy through Archive**

**Download Archive**

Link to archives can be found here: [**https://archive.lenses.io/lenses/6.1/agent/**](https://archive.lenses.io/lenses/6.1/agent/)

**Extract the archive using the following command**

{% code title="terminal" %}

```sh
tar -xvf lenses-agent-latest-linux64.tar.gz -C lenses
```

{% endcode %}

**Start Agent**

{% code title="terminal" %}

```bash
bin/lenses lenses-agent.conf
```

{% endcode %}
{% endstep %}
{% endstepper %}

### Best Practices for Production

#### Security Considerations

* **Use Kubernetes secrets** for sensitive data instead of inline values
* **Enable TLS** for all Lenses HQ connections
* **Implement RBAC** for Kubernetes and Lenses HQ & Agent access
* **Rotate credentials** regularly

#### Operations Best Practices

* **Monitor resource usage** of sidecar containers
* **Set resource limits** to prevent resource monopolization
* **Implement health checks** for the provision process
* **Use GitOps workflows** for configuration management

#### Scaling Considerations

* **Plan for multiple environments** (dev, staging, prod)
* **Implement configuration templates** for reusability
* **Use Helm chart dependencies** for complex deployments
* **Monitor deployment metrics** and success rates

### Conclusion

Migrating from Lenses Wizard Mode to Provision Mode enables Infrastructure as Code practices, better security management, and automated deployments. While the initial setup requires more configuration, the long-term benefits of automated, version-controlled, and repeatable deployments make this migration worthwhile for production environments.

The provision sidecar pattern ensures that your Lenses configuration is managed alongside your infrastructure code, enabling true GitOps workflows and reducing configuration drift between environments.