# Steps for In-Place Upgrade

## Prerequisites

{% stepper %}
{% step %}
**Have HQ deployed**

The first step is to have HQ deployed and *agent\_key* being obtained upon [environment creation](https://docs.lenses.io/latest/deployment/upgrade-to-lenses-6/broken-reference)
{% endstep %}

{% step %}
**Prepare Lenses 5 Configuration Files**

Before doing upgrade, make a copy of all configuration files.

In case of Helm deployment that would be:

* `values.yaml`

In case of Archive of Docker deployment that would be:

* `lenses.conf`\
  It is strongly suggested to rename this file to `lenses-agent.conf` for the upgrade.
* `provisioning.yaml`

{% hint style="info" %}
In case you are missing provisioning.yaml configuration file, re-creating it will be covered in next step.
{% endhint %}
{% endstep %}

{% step %}
**Convert all connections / alerts / channels to Provisioning**

There were multiple ways how Lenses resources could have been managed in the past:

1. Wizard
2. Provisioning v1
3. Provisioning v2

For Lenses (6) Agent, it is recommended that all connections (*kafka, schema-registry, connect,*...) are kept inside of *provisioning.yaml* file in *version 2*. [automation](https://docs.lenses.io/latest/deployment/configuration/agent/automation "mention")

Differences of provisioning between version 1 and 2 can be seen below:

{% tabs %}
{% tab title="Provisioning version 1" %}
{% code title="provisioning.yaml" %}

```yaml
license:
  fileRef:
    inline: '{"source":"Landoop LTD","clientId":"Lenses Dev","details":"kafka-lenses","key":"eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.AqO6Ax-o-4T0WKFX7eCGFRu329wxplkZuWrGdhyncrhBfh9higjsZA.-uGCXWjULTzb7-3ROfsRhw.olmx6FR7FH7c2adHol0ipokHF6jOo6LTDtoFOSPWfqKxbA3yI-CUqlyo_-Obin7MSA4KqXBLpXOvP72EJhIYuyqkxUVGRoXHF0Oj2V6kzdDcmjJHbMB4VTxdE8YBAYbPXzEXdhq7lZy4fxHHhYxAsRATCtqf7t7TQCE0TWOiSHvLwyD7xMK2X47KiKbnNlNvqeVnnjLUMMd7vzA5dTft48wJm2D5HJNZ0mS32gTaiiExT5nqolToL0KYIOpRiT00MTQkGlBdagVigc-DZBPM0ZTP5wuLkwdk4XbfoQKaWC4qaYA6VpGgQg03Mo1W4ljlqRy0N4cPQ-l4Mi1XV9VK-825-zhyxzPrxef5Zct2nzVEJ9MbWy0-xuf6THX4q2X8zmz_KiHoA-hBWjebv_2R9479ldGj0h-vm9htVD59_6RBOGb0rT4XSS-4_CGYBZzv5PIPpLdnVbkr_qjsxCI0BO7tPKoyxXg2qh4YQbn3wn5MqsE9yR2BbRaso9MSPFlF8PxqR7A4qrKJjn_mPlcrR-XGf0ua2XfWCVe4ngcWpzssYHcJJD80APyZgzneIw2dSaO0enfFYUq6avqGSeoG7VC9zYACfUdofdlULH2azmptJ2Jzw3ggpLR7ZzZ9QrySXTUB2jkzrqiHyM9fqIXUVwAkAJMcBuwF5zY5B_ChA69Uj_-s-S1RITBbg5wtB3LuHyJGtTo4fuYY75F_OL9Cwp7gcpa5u0M_wWZlx70j_6jCb-ogvghALbHY8OPeWz_1-3bvJM9T_jmjKy0FDt6x8FJV1lgMMR0j1RiUeauUMsnd4TNUYAH50mFwtK5PU-Iq.U4LwNfOL2JB4vzBMvo3Hig"}'
connections:
  kafka:
    tags: []
    templateName: Kafka
    configurationObject:
      kafkaBootstrapServers:
        - PLAINTEXT:///localhost:9092
      protocol: PLAINTEXT
      # metrics
      ## JMX
      metricsPort: 9581
      metricsType: JMX
      metricsSsl: false
      ## JOLOKIA
      # metricsPort: 19581
      # metricsType: JOLOKIAG # or JOLOKIAP
      # metricsSsl: false
      # metricsHttpSuffix: "/jolokia/"

  zookeeper:
    tags: []
    templateName: Zookeeper
    configurationObject:
      zookeeperUrls:
        - localhost:2181
      zookeeperSessionTimeout: 10000
      zookeeperConnectionTimeout: 10000
      # metrics
      ## JMX
      metricsPort: 9585
      metricsType: JMX
      metricsSsl: false
      ## JOLOKIA
      # metricsPort: 19585
      # metricsType: JOLOKIAG # or JOLOKIAP
      # metricsSsl: false
      # metricsHttpSuffix: "/jolokia/"

  schema-registry:
    templateName: SchemaRegistry
    tags: [ ]
    configurationObject:
      schemaRegistryUrls:
        - http://localhost:8081
      additionalProperties: { }
      # metrics
      ## JMX
      metricsPort: 9582
      metricsType: JMX
      metricsSsl: false
      ## JOLOKIA
      # metricsPort: 19582
      # metricsType: JOLOKIAG # or JOLOKIAP
      # metricsSsl: false
      # metricsHttpSuffix: "/jolokia/"

  connect-cluster-dev-1:
    templateName: KafkaConnect
    tags: []
    configurationObject:
      workers:
        - http://localhost:8083
      aes256Key: PasswordPasswordPasswordPassword
      # metrics
      ## JMX
      metricsPort: 9584
      metricsType: JMX
      metricsSsl: false
      ## JOLOKIA
      # metricsPort: 19584
      # metricsType: JOLOKIAG # or JOLOKIAP
      # metricsSsl: false
      # metricsHttpSuffix: "/jolokia/"

  my-prometheus: {"configuration":[{"key":"endpoints","value":["https://am.acme.com"]}],"tags":["prometheus","monitoring","metrics"],"templateName":"PrometheusAlertmanager"}

```

{% endcode %}
{% endtab %}

{% tab title="Provisioning version 2" %}
{% code title="provisioning.yaml" %}

```yaml
lensesHq:
  - configuration:
      agentKey:
        value: ${LENSESHQ_AGENT_KEY}
      port:
        value: 10000
      server:
        value: lenses-hq
    name: lenses-hq
    tags: ['hq']
    version: 1
kafka:
  - name: kafka
    version: 1
    tags: [ 'kafka', 'dev' ]
    configuration:
      metricsType:
        value: JMX
      metricsPort:
        value: 9581
      kafkaBootstrapServers:
        value: [PLAINTEXT://demo-kafka:19092]
      protocol:
        value: PLAINTEXT
confluentSchemaRegistry:
  - name: schema-registry
    version: 1
    tags: [ 'dev' ]
    configuration:
      schemaRegistryUrls:
        value: [http://demo-kafka:8081]
      metricsType:
        value: JMX
      metricsPort:
        value: 9582
connect:
  - name: dev
    version: 1
    tags: [ 'dev' ]
    configuration:
      workers:
        value: [http://demo-kafka:8083]
      aes256Key:
        value: 0123456789abcdef0123456789abcdef
      metricsType:
        value: JMX
      metricsPort:
        value: 9584%
```

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

More about other configuration options in *provisioning.yaml ->* [automation](https://docs.lenses.io/latest/deployment/configuration/agent/automation "mention")

If you are curious on how to properly create *provisioning.yaml* file, you can read more on [how-to-convert-wizard-mode-to-provisioning-mode](https://docs.lenses.io/latest/deployment/upgrade-to-lenses-6/how-to-convert-wizard-mode-to-provisioning-mode "mention").
{% endstep %}
{% endstepper %}

## Steps to deploy Agent

{% stepper %}
{% step %}
**Follow prerequisite steps above**

Steps:

* [x] Deploy Lenses HQ
* [x] Prepare Lenses 5 Configuration Files
* [x] Prepare Provision file

Once you went through the steps above you'll be ready to move ahead and deploying Agent at the side.
{% endstep %}

{% step %}
**Clone / Migrate Lenses 5 Groups**

In this step you'll ensure that Groups (with permissions) that exist in Lenses 5 will still have the same amount of permissions in Lenses 6 for newly created Environment (Agent).

{% hint style="success" %}
Migration of :

* data policies
* alerts
* sql processors

i**s not necessary in case Agent will re-use the same database as Lenses 5.**
{% endhint %}

To execute this step we have tooling that can help you [Lenses Migration Tool](https://github.com/lensesio-ps/lenses-migration-tool).

{% hint style="warning" %}
Be aware, cloning of **alerts** is not available yet via script above.
{% endhint %}

Once script is initiated you should be able to see new:

* Groups and
* Roles with its permissions inside HQ screen.

These are matching the ones you have in Lenses 5 instance and will enable users to see new Environment once it is connected :point\_down:
{% endstep %}

{% step %}
**Stop Lenses 5 instance and start Lenses 6 Agent**

There are multiple deployment methods for the Agent deployment, please choose one from [installation](https://docs.lenses.io/latest/deployment/installation "mention")

{% hint style="danger" %}
**Two** **Lenses** instances **shouldn't be** **connecting** to the **same** **database** therefore **old Lenses 5** should be **stopped**.
{% endhint %}

{% hint style="danger" %}
Note that there is no rollback mechanism once upgrade is initiated **over the same database**.

This type of upgrade is only possible when **Postgres is used as datastore.**
{% endhint %}
{% endstep %}

{% step %}
**Check Environment screen for a new Agent**

Screen of "Connected" Agent should look as follows and should be seen by AD groups that has been cloned in step :digit\_three:.

<figure><img src="https://3629020462-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoxgTiTb4MZT9IGHAYUTn%2Fuploads%2Fgit-blob-e3d4525af0d0ad65c4aac4521b8213d587053f7d%2Fimage%20(9)%20(1)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}