Manage Aiven for OpenSearch® custom repositories in the Aiven Console or API

Use the Aiven Console or API for configuring custom repositories in Aiven for OpenSearch to store snapshots in your cloud storage.

Prerequisites

Aiven Console

• Running Aiven for OpenSearch service
• Access to the Aiven Console
• Access to a supported object storage service (AWS S3, GCS, or Azure)
• Credentials for the selected storage provider

Aiven API

• Running Aiven for OpenSearch service
• Aiven API and authentication token
• Access to a supported object storage service (AWS S3, GCS, or Azure)
• Credentials for the selected storage provider

note

• Repository credentials are omitted from API responses for security reasons.
• Aiven API provides a direct interface to the OpenSearch snapshot API.

Limitations

Aiven Console

You can configure custom repositories for the following object storage services:

• Amazon S3
• Google Cloud Storage (GCS)
• Microsoft Azure Blob Storage

Aiven API

• Supported storage services
  • Amazon S3
  • Google Cloud Storage (GCS)
  • Microsoft Azure Blob Storage
• To edit repository details, you can only use the Aiven Console.
• The following operations are not supported via Aiven API:
  • Remove a repository
  • View or edit repository details

Create custom repositories

Each repository requires a unique name, a storage type (such as S3, Azure, or GCS), and the appropriate settings for the selected storage provider.

Aiven Console

1. Log in to the Aiven Console, go to your project, and open your service's page.
2. Click Snapshots in the sidebar.
3. On the Snapshots page, click Add repository.
4. In the Add custom repository window:
   1. Enter a repository name.
   2. Select a storage provider.
   3. Give provider-specific details required for accessing the storage.
   4. Click Add.

Aiven API

Custom repositories are configured in the user_config of your Aiven for OpenSearch service. Use the following API request to configure custom repositories:

curl -s --url "https://api.aiven.io/v1/project/{project_name}/service/{service_name}" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
-X PUT -d '{
  "user_config": {
    "custom_repos": [
      {
        "name": "azure-repo",
        "type": "azure",
        "settings": {
          "account": "AZURE_ACCOUNT",
          "base_path": "your/path",
          "container": "AZURE_CONTAINER",
          "sas_token": "AZURE_SAS_TOKEN",
          "readonly": false
        }
      },
      {
        "name": "aws-repo",
        "type": "s3",
        "settings": {
          "access_key": "AWS_ACCESS_KEY",
          "secret_key": "AWS_SECRET_KEY",
          "base_path": "your/path",
          "bucket": "AWS_BUCKET",
          "region": "AWS_REGION",
          "server_side_encryption": true,
          "readonly": false
        }
      }
    ]
  }
}'

List custom repositories

Aiven Console

1. Log in to the Aiven Console, go to your project, and open your service's page.
2. Click Snapshots in the sidebar.

Find your custom repositories listed on the Snapshots page.

Aiven API

curl -s --url "https://api.aiven.io/v1/project/{project_name}/service/{service_name}/opensearch/_snapshot"\
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

Example response:

{
  "repositories": [
    {
      "name": "aws-repo",
      "settings": {
        "base_path": "test/path",
        "bucket": "testbucket",
        "endpoint": "http://s3.eu-north-1.amazonaws.com",
        "region": "eu-north-1",
        "server_side_encryption": true,
        "readonly": false
      },
      "type": "s3"
    },
    {
      "name": "azure-repo",
      "settings": {
        "base_path": "test/path",
        "container": "testcontainer",
        "readonly": false
      },
      "type": "azure"
    }
  ]
}

View or edit repository details

1. Log in to the Aiven Console, go to your project, and open your service's page.
2. Click Snapshots in the sidebar.
3. On the Snapshots page, find your custom repository and click Actions > Edit repository.
4. Edit repository details and save your changes by clicking Update.

Remove a repository

1. Log in to the Aiven Console, go to your project, and open your service's page.
2. Click Snapshots in the sidebar.
3. On the Snapshots page, find your custom repository and click Actions > Remove repository > Remove.

Error handling

The Aiven API returns OpenSearch errors as they are.

Exceptions:

• 502: OpenSearch did not respond.
• 409: The service is not powered on or does not support this feature.

Related pages

Manage Aiven for OpenSearch® custom repositories in OpenSearch® API