Configuring Elasticsearch snapshots

You can configure votre instance GitHub Enterprise Server to use a customer-managed cloud storage provider for native Elasticsearch snapshots and restores, instead of copying search index data directly from disk.

Qui peut utiliser cette fonctionnalité ?

Site administrators can configure Elasticsearch snapshot storage.

Dans cet article

About Elasticsearch snapshots

By default, GitHub Enterprise Server Backup Utilities and GitHub Enterprise Server Backup Service back up search index data by copying files directly from disk. This approach doesn't follow Elasticsearch's own recommendations, can consume a large amount of backup appliance storage, and carries some risk of corrupting the backed-up indices.

As an opt-in alternative, votre instance GitHub Enterprise Server supports Elasticsearch's built-in, incremental snapshot and restore functionality. When you configure a supported cloud storage provider and enable the snapshot backup strategy:

  • ghe-backup creates an incremental snapshot of your search index data in your configured cloud storage account. Incremental snapshots are faster than a full copy, especially on subsequent backups.
  • ghe-restore restores search index data from your cloud storage account, if a snapshot exists that matches the target instance's GitHub Enterprise Server version.
  • Snapshots are isolated per GitHub Enterprise Server patch version, which allows for safer rollbacks between versions.

This feature is opt-in. If you don't configure a snapshot repository, votre instance GitHub Enterprise Server continues to back up search index data using the existing disk-based method.

Prerequisites

  • A supported cloud storage provider: Azure Blob storage, Amazon S3, or Google Cloud Storage (or a service that's compatible with one of these APIs).
  • The storage container or bucket you plan to use as the snapshot repository. You must create this container or bucket yourself. GitHub Enterprise Server does not create it for you, and repository registration will fail if the container or bucket doesn't already exist.

Configuring a snapshot storage provider

Configure the following settings using ghe-config over SSH. For more information, see Accès à l’interpréteur de commandes d’administration (SSH).

You'll apply the configuration to register the snapshot repository with Elasticsearch. The repository is named search_index_snapshots-VERSION, where VERSION is the current GitHub Enterprise Server release version.

Azure Blob storage

  1. Set the following secrets:

    ghe-config secrets.elasticsearch.snapshot-provider azure
ghe-config secrets.elasticsearch.snapshot.azure.container YOUR-CONTAINER
ghe-config secrets.elasticsearch.snapshot.azure.account-name YOUR-STORAGE-ACCOUNT
ghe-config secrets.elasticsearch.snapshot.azure.account-key YOUR-ACCOUNT-KEY

    Optionally, set a custom blob endpoint suffix (defaults to core.windows.net):

    ghe-config secrets.elasticsearch.snapshot.azure.endpoint-suffix YOUR-ENDPOINT-SUFFIX

  2. Run configuration apply.

    ghe-config-apply

Amazon S3

  1. Set the following secrets:

    ghe-config secrets.elasticsearch.snapshot-provider s3
ghe-config secrets.elasticsearch.snapshot.bucket-name YOUR-BUCKET-NAME
ghe-config secrets.elasticsearch.snapshot.service-url YOUR-SERVICE-URL
ghe-config secrets.elasticsearch.snapshot.region YOUR-AWS-REGION
ghe-config secrets.elasticsearch.snapshot.access-key-id YOUR-ACCESS-KEY-ID
ghe-config secrets.elasticsearch.snapshot.access-secret YOUR-ACCESS-SECRET

    For the service URL, use your S3 endpoint, for example https://s3.us-east-1.amazonaws.com.

  2. Run configuration apply.

    ghe-config-apply

Google Cloud Storage

  1. Create a JSON service account key with access to your bucket, then encode it as base64.

    base64 -w0 service-account.json

  2. Set the following secrets:

    ghe-config secrets.elasticsearch.snapshot-provider gcs
ghe-config secrets.elasticsearch.snapshot.gcs.bucket YOUR-BUCKET-NAME
ghe-config secrets.elasticsearch.snapshot.gcs.credentials YOUR-BASE64-ENCODED-CREDENTIALS

  3. Run configuration apply.

    ghe-config-apply

Verifying registration

After configuration apply completes, confirm the snapshot repository was registered.

curl -k "http://127.0.0.1:9200/_snapshot/search_index_snapshots-$(ghe-version -v)/_status"

If a required secret is missing, configuration apply fails while registering the repository. Update the secrets and rerun ghe-config-apply to retry.

Enabling snapshots during backup and restore

Configuring a storage provider registers the snapshot repository, but you must also enable the snapshot backup strategy so ghe-backup and ghe-restore use it automatically.

  • GitHub Enterprise Server Backup Service: Set the strategy using ghe-config on the appliance.

    ghe-config backup.es-backup-strategy snapshot

  • GitHub Enterprise Server Backup Utilities: Set the strategy in your backup.config file on the backup host.

    GHE_ES_BACKUP_STRATEGY=snapshot

    The default value is rsync, which preserves the existing disk-based backup behavior. GitHub Enterprise Server Backup Utilities stores only snapshot metadata locally; snapshot contents remain in your configured cloud storage.

If you don't set a backup strategy, the snapshot repository can still be managed manually, but ghe-backup and ghe-restore will continue to use the disk-based method.

Managing snapshots manually

You can manage Elasticsearch snapshots directly using the following commands. Run any command with the -h flag for usage information.

CommandDescription
ghe-es-create-snapshotCreates a new snapshot in the configured repository.
ghe-es-list-snapshotsLists snapshot repositories, or snapshots within a repository.
ghe-es-restore-snapshotRestores search indices from a snapshot.

Conseil

For routine backups and restores, use GitHub Enterprise Server Backup Utilities or GitHub Enterprise Server Backup Service instead of these commands directly. The backup tooling coordinates Elasticsearch snapshots with the rest of your instance's data to ensure a consistent backup or restore. Use the manual commands only when you need to manage search index snapshots independently of a full instance backup or restore.

Restoring a snapshot from an earlier version

You can restore a snapshot created by an earlier GitHub Enterprise Server version to a later version. You cannot restore a snapshot from a later version to an earlier version.

  1. List available snapshots for the earlier version.

    ghe-es-list-snapshots -v 3.14.0

  2. Restore the snapshot you want.

    ghe-es-restore-snapshot -v 3.14.0 -s SNAPSHOT-NAME

Elasticsearch automatically upgrades the restored indices to the current version's format.

Managing snapshot storage

Elasticsearch snapshots are incremental, but your cloud storage account can still accumulate old snapshots over time. To avoid unbounded storage growth, configure a lifecycle policy with your storage provider to automatically delete snapshots older than your retention requirements. For more information, see your provider's documentation: