Skip to main content

Repository: govuk-chat-opensearch

A repo for managing GOV.UK Chat’s OpenSearch snapshots

GitHub
govuk-chat-opensearch
Ownership
#ai-govuk owns the repo. #dev-notifications-ai-govuk receives automated alerts for this repo.
Category
AI apps

README

These scripts allow you to capture, restore and delete snapshots of an OpenSearch cluster.

Overview of snapshot management

A snapshot is a copy of an existing index, stored in an S3 bucket. After a snapshot is created it can be restored to a new index.

The OpenSearch instance can have multiple indices, so you can restore as many snapshots as you like and run them all simultaneously. You can then evaluate different snapshots by simply changing the name of the index you’re querying.

Glossary

  • Index - Our searchable data structure in OpenSearch (i.e. think “our live database”)
  • Snapshot - A backup copy of the index frozen in time
  • Repository - Where we store these backups (S3 bucket)

Setup

Copy .env.example to .env and fill in the required environment variables with the values below.

The credentials are stored in AWS Secrets Manager; you can get them with the following two commands:

eval $(gds aws govuk-test-developer -e --art 8h)

aws secretsmanager get-secret-value --secret-id "govuk/govuk-chat/opensearch-frozen-instance-credentials"  --query SecretString --output text | jq -r "{url: .url, username: .username, password: .password}"

Finally, run uv sync to install the dependencies.

Frozen instance indices

The frozen instance has been initialised with 2 indices you can query:

  • govuk_chat_chunked_content_titan - the same frozen index as in the existing cluster
  • govuk_chat_chunked_content_prod - the GOV.UK Chat production index restored on 3rd Dec 2025 (so this includes the new travel advice indexing).

You can list all the indices in the cluster with the following command:

uv run snapshot.py list-indices

Repository management

See the repository management docs for more details.

Snapshot management

List

List all snapshots and their status.

uv run snapshot.py list

Capture

Captures a snapshot of an OpenSearch index and saves it to the repository.

Note that you need to specify the index name here rather than the snapshot capturing all indices in the cluster. This is so we have more control over capturing and restoring snapshots because one snapshot will contain one index, so it’s easier to restore a snapshot into a cluster with some existing indices.

[!IMPORTANT] To make it easier to identify snapshots, use the following naming convention for the snapshot name. This will help in identifying snapshots when you’re restoring them. Use the following format: {index_name_being_captured}-{yyyy-mm-dd}-{hhss} e.g. govuk_chat_chunked_content-2025-01-01-1200

uv run snapshot.py capture <snapshot_name> <index_name>
  • index_name: you need to specify the index you’re taking a snapshot of. You can find the name of all the current indices in the cluster by running uv run snapshot.py list-indices.

Restore

Restores a snapshot of the OpenSearch index.

uv run snapshot.py restore <repository_name> <snapshot_name> <index_name_from> <index_name_to>
  • repository_name: because we have multiple repositories associated with the cluster, you need to specify which repository the snapshot you’re restoring lives in. The repository name is shown in uv run snapshot.py list
  • snapshot_name: the name of the snapshot you’re restoring, again shown in uv run snapshot.py list
  • index_name_from: the name of the index in the snapshot you want to restore. Because some snapshots contain multiple indices (e.g. the daily production snapshot), you need to target a specific index. uv run snapshot.py list shows you all the indices a snapshot contains
  • index_name_to: the name of the index in the test cluster you want to restore to. If this index already exists it’ll be deleted and recreated. If not, it’ll be created.

Delete

Deletes a snapshot.

Shows a list of snapshots that are eligible for deletion.

uv run snapshot.py delete <repository_name> <snapshot_name>

Index management

List indices

Lists all the indices in the cluster.

uv run snapshot.py list-indices

Delete index

Deletes an index from the cluster. If you’ve restored a snapshot to an index and you’re finished testing it, you should delete the index to save on storage costs.

uv run snapshot.py delete-index <index_name>

Example workflow

See the example workflow docs for an example of how you might use snapshots for testing.

Using the frozen OpenSearch instance in the GOV.UK Chat Rails app

To use this instance in GOV.UK Chat Rails app, you need to first configure the environment variables in the .env file in the govuk-chat repo.

Set the following environment variables to the same values in the .env file when you configured this project (see setup for more details):

  • OPENSEARCH_URL
  • OPENSEARCH_USERNAME
  • OPENSEARCH_PASSWORD

You’ll then need to set the index name in the opensearch.yml config file here. (uv run snapshot.py list-indices will show you the names of the indices in the cluster.)

Make sure you restart the GOV.UK Chat Rails app for these changes to take effect.