> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating ABBYY Vantage

> Update an ABBYY Vantage Self-Hosted installation to a new release: synchronize container images, back up data, run installer scripts, and recover if needed.

<Warning>
  **Vantage 3.0 replaces this deployment model.** Vantage 2.7 and earlier required ABBYY's specified infrastructure, created by ABBYY-provided Ansible and Azure CLI scripts. That model is not supported in 3.0: you provision your own infrastructure, and ABBYY does not provide provisioning scripts or other infrastructure automation. This page applies to Vantage 2.7 only. See the [Vantage 3.0 overview](/vantage/self-hosted/v3.0/introduction) and [Migrate from Vantage 2.7](/vantage/self-hosted/v3.0/migration-from-2.7).
</Warning>

This section covers the process of updating ABBYY Vantage within the 2.7.x release line. Moving to 3.0 is a migration, not an update; see [Migrate from Vantage 2.7](/vantage/self-hosted/v3.0/migration-from-2.7).

<Note>
  Before updating Vantage, make sure that all requirements of the new release listed in the [System Requirements](/vantage/self-hosted/v2.7/system-requirements) section are met.
</Note>

The update process consists of the following steps:

1. [Synchronize container images](#synchronize-container-images).
2. [Back up data](#back-up-data).
3. [Run the installation scripts](#run-the-installation-scripts).
4. [Uninstall Vantage](#uninstall-vantage).
5. [Update ABBYY Vantage](#update-abbyy-vantage).

## Synchronize Container Images

To synchronize container images, follow the steps in [Downloading container images](/vantage/self-hosted/v2.7/installation#downloading-container-images).

## Back Up Data

To restore Vantage to the version running at the time of the update, you must have a backup of databases, Consul, and copies of Kubernetes secrets. Follow the steps below to properly back up these components:

1. Before creating a backup of databases and Consul, you need to stop the cluster. Shut down all the nodes in the cluster.
2. Create a backup of:
   * **Databases**: The list of databases is: `apigatewayregistry`, `auth`, `auth-identity`, `catalogstorage`, `cron`, `documentset`, `folderimport`, `interactive-jobs`, `mail`, `mailimport`, `permissions`, `publicapi`, `reporting`, `secretstorage`, `security-audit`, `skillinfo`, `skillmonitor`, `storage`, `subscriptions`, `tokenmanagement`, `transactions`, `workflows`, `workspace`.
   * **Consul**: Kubernetes CronJob backs up Consul to external RWX storage (such as NFS) by pod with the name `[X].consul-backup`. You can fetch backed-up TGZ files from the PVC folder named `consul-backup`.
3. Start the cluster. Start all the nodes in the cluster.
4. Back up **Copies of Kubernetes secrets**. To get the keys, run the following commands:

```bash theme={null}
kubectl get secret -n abbyy-vantage secretstorage-encryptionkeys -o yaml
kubectl get secret -n abbyy-vantage tokenmanagement-encryptionkeys -o yaml
```

<Note>
  Before creating a backup of copies of Kubernetes secrets, make sure the cluster is started.
</Note>

<Note>
  Backups are made just in case. With a successful upgrade, you will not have to make a recovery from the backup.
</Note>

## Run the Installation Scripts

Prior to updating ABBYY Vantage, follow the [Installation](/vantage/self-hosted/v2.7/installation) steps.

To run the installation scripts:

1. Set up configuration files.

<Note>
  By default, the technology core version 2 is deleted when updating Vantage. To keep it, add the `techcore.keep_previous_version` parameter to the `env_specific.yml` file and set its value to `true`.
</Note>

2. Prepare certificates.
3. Download container images.
4. Run the installation scripts (steps 1-3).

## Uninstall Vantage

Run the following playbook to uninstall the product:

```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/uninstall-vantage.yml
```

This playbook will remove all services while leaving the data store intact.

## Update ABBYY Vantage

To update ABBYY Vantage:

1. Run the following playbooks to do a pre-deploy check and to read and accept the Vantage legal documents:

```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/0-PreflightCheck-k8s.yml
ansible-playbook -i inventories/k8s -v playbooks/legal.yml
```

The playbooks will:

* Carry out a preliminary check regarding the resources whose parameters are specified in the `env_specific.yml` file of the playbook (database, SMTP connection, etc.).
* Ask the system administrator to accept the terms of the EULA and ABBYY Privacy Policy.

2. Run the following playbook to update Vantage:

```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/site-k8s-deploy.yml
```

The playbooks will install a new version of the product. On average, the process will take about 20-30 minutes.

<Note>
  After ABBYY Vantage is updated, you will have to authorize again. Authorization tokens obtained before the upgrade will not work anymore.
</Note>

To work with Advanced Designer and Scanning Station, you need to download their new versions and install them on your machines:

* `https://<your-vantage-host>/ad/latest` - for downloading Advanced Designer
* `https://<your-vantage-host>/ss/latest` - for downloading Scanning Station

If the update process fails, see the following section, Recovery.

## Recovery

If the update process was unsuccessful, follow these steps:

1. Check that the pods in the cluster are working well and restart them if they are not.
2. Analyze the logs of the pods that are not working as intended.
3. Follow the troubleshooting steps from the pod logs.
4. If the upgrade fails at any step of installing a new version of Vantage (e.g., waiting for Vantage jobs, waiting for Vantage deployments), fix the cause of the error and then run the install playbook:

```bash theme={null}
ansible-playbook -i inventories/k8s -v playbooks/site-k8s-deploy.yml
```

### Installing Vantage with Data Recovery on a New Cluster

If the steps described above did not help, you can install Vantage with data recovery on a new cluster by following these steps:

1. Make sure you have all the latest backups of your data.
2. Restore the data from backups you created earlier.
3. Prepare the `env_specific` file containing data for connecting databases and external storage restored from backups.
4. Install Vantage following the steps from [Running the installation scripts](/vantage/self-hosted/v2.7/installation#running-the-installation-scripts) in the Installation section. For step 2 (running the installer from a Docker image), use the command below:

```bash theme={null}
docker run -it --net=host \
-v $PWD/kube:/root/.kube \
-v $PWD/inventory:/ansible/inventories/k8s/inventory \
-v $PWD/env_specific.yml:/ansible/inventories/k8s/group_vars/all/env_specific.yml \
-v $PWD/ssl:/ansible/files/ssl:ro \
--privileged \
registry.local/vantage/vantage-k8s:2.7.1
```

5. Overwrite the key values in the `secretstorage-encryptionkeys` and `tokenmanagement-encryptionkeys` secrets with the values you backed up earlier:

   a. Run the command:

   ```bash theme={null}
   kubectl edit secrets -n abbyy-vantage secretstorage-encryptionkeys
   ```

   b. In the file that opens after `key-<guid>.xml`, replace the base64 string with the base64 string contained in the key that was previously backed up for the `secretstorage-encryptionkeys` secret.

   c. Save your changes and close the editor.

   d. Do the same for the `tokenmanagement-encryptionkeys` secret using the command:

   ```bash theme={null}
   kubectl edit secrets -n abbyy-vantage tokenmanagement-encryptionkeys
   ```
6. After rewriting the keys, restart the `secretstorage` and `tokenmanagement` pods:

```bash theme={null}
kubectl -n abbyy-vantage rollout restart $(kubectl -n abbyy-vantage get deployments -l app.kubernetes.io/component=secretstorage -o name)
```

```bash theme={null}
kubectl -n abbyy-vantage rollout restart $(kubectl -n abbyy-vantage get deployments -l app.kubernetes.io/component=tokenmanagement -o name)
```

7. Restart the transactions. On a machine that is connected to the cluster, run this command to access the transaction service:

```bash theme={null}
kubectl port-forward -n abbyy-vantage deployments/abbyy-vantage-transactions 8080:8080
```

Navigate your browser to `http://localhost:8080/index.html` and run the following API method:

```
/api/recovery/transactions/restart
```

<Note>
  If the Vantage host address has changed after recovery, and there are unaccepted invitations in the system, then you need to resend these invitations.
</Note>