Skip to main content
Version: 2.0.0-alpha.1 (preview)

Backups and restores

The backup.openeverest.io API group holds the resources for backups. For a task-oriented guide, see Backup and restore.

BackupStorageClass​

A cluster-scoped description of one storage technology: the parameters a storage of that technology takes, how it authenticates, and the forms the UI shows for it. OpenEverest ships the s3 class.

kubectl get backupstorageclasses
FieldDescription
displayNameShown in the UI as the storage Type.
parametersSchemaOpenAPI schema of BackupStorage.spec.parameters.
authModes[]The authentication modes a storage of this class can use, each with the keys its credentials Secret must hold (credentials.required, credentials.optional).
validations[]CEL rules that the schema can't express, each with a message and a reason. A storage that breaks one is not accepted.
uiSchemaThe forms of the class: location, storage (the parameters) and credentials for each authentication mode.

The s3 class​

The s3 class works with Amazon S3 and with S3-compatible object storage, such as MinIO, SeaweedFS, Ceph RGW or Google Cloud Storage in S3 interoperability mode.

ParameterDescription
regionRequired. Region of the bucket, for example us-east-1. Storage without regions usually accepts us-east-1.
endpointURLRequired. URL of the S3 service, for example https://s3.us-east-1.amazonaws.com. An http:// URL uses plain HTTP.
forcePathStyleUse path-style URLs. Needed by most self-hosted S3 services, such as MinIO.
implementationaws, minio, ceph, gcs or other. Tells the provider which S3 implementation it talks to, for engines that handle S3-compatible storage differently from Amazon S3. Defaults to aws.

Its only authentication mode is AccessKey, whose Secret holds AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Bucket names must be 3 to 63 lowercase letters, digits, ., - or _.

BackupStorage​

A namespaced place to write backups to, of the technology its class describes.

apiVersion: backup.openeverest.io/v1alpha1
kind: BackupStorage
metadata:
name: s3-backups
namespace: demo
spec:
backupStorageClassRef:
name: s3
location:
objectStore:
bucket: openeverest-backups
prefix: demo
parameters:
region: us-east-1
endpointURL: https://s3.us-east-1.amazonaws.com
authentication:
mode: AccessKey
credentialsSecretRef:
name: s3-backups-credentials
tls:
ca:
secretKeyRef:
name: s3-backups-ca
key: ca.crt
FieldDescription
backupStorageClassRef.nameRequired. The BackupStorageClass. Immutable.
location.objectStore.bucketRequired. Name of an existing bucket. Immutable.
location.objectStore.prefixPath within the bucket, for example team-a/prod. Immutable.
parametersThe parameters of the class, checked against its parametersSchema.
authentication.modeRequired. One of the class's authModes. Anonymous is not accepted.
authentication.credentialsSecretRef.nameSecret in the same namespace with the keys the mode requires. See Secrets and credentials.
tls.ca.secretKeyRefSecret key with the PEM CA certificates that signed the server certificate, for endpoints with a private CA.
tls.insecureSkipVerifyDon't verify the server certificate. Can't be combined with tls.ca.

The location is immutable because engines treat it as their backup catalog. To move backups elsewhere, create a new storage.

Each instance writes under its own path, <prefix>/backups/<namespace>/<instance>/<instance-uid>/<storage>, so instances never share a directory. Each Backup records its path in status.path.

Status​

OpenEverest checks every storage against its class and reports the result in the Accepted condition. It doesn't check that the bucket is reachable.

Accepted reasonMeaning
AcceptedThe storage is valid for its class.
ClassNotFoundThe BackupStorageClass doesn't exist.
InvalidClassThe class itself is invalid.
InvalidLocation, InvalidParametersThe location or the parameters break the class's schema or rules. The message says which.
AuthModeUnsupportedThe class doesn't offer the authentication mode.
CredentialsNotFoundThe credentials Secret is missing or lacks a key the mode requires.
InvalidCABundleThe CA Secret or key is missing, or holds something other than CA certificates.

status.backupClasses[] lists, for each backup class, whether it can write to this storage. kubectl get backupstorages shows the class, the bucket, the authentication mode and the Accepted reason; -o wide adds the credentials Secret, the CA Secret and whether verification is skipped.

To find the storages that use a Secret:

kubectl get backupstorages -n demo \
--field-selector spec.authentication.credentialsSecretRef.name=s3-backups-credentials

A storage that instances, backups, restores or backup imports still use isn't deleted. It reports Deleting with reason WaitingForReferrers and a message such as "still referenced by 1 Instance(s), 1 Backup(s)", and is removed once nothing uses it. Deleting a storage never deletes its Secrets or the data in the bucket.

BackupClass​

A cluster-scoped description of how backups are taken. Providers install their backup classes; you rarely create one yourself.

kubectl get backupclasses
FieldDescription
displayName, descriptionShown in the UI.
executionModeWho takes the backups. ProviderManaged, the only mode, means the provider and its Operator.
providerManaged.providerRef.nameThe provider that runs the class. Immutable.
providerManaged.supportsPITRWhether point-in-time recovery is supported.
providerManaged.limitsLimits per instance, such as the number of storages or of PITR-enabled storages.
backupStorageClasses[]The storage classes the class can write to, each with the authModes it supports, an optional parametersSchema that narrows the class's parameters, and tls.customCA and tls.insecureSkipVerify (Supported or None).
supportsImportWhether backups in a storage can be discovered and imported with a BackupImport.
parametersSchema, restoreParametersSchemaSchemas of the extra parameters accepted by Backup.spec.parameters and Restore.spec.parameters.

The provider marks the classes it ships as Accepted. OpenEverest publishes in status.providers[] whether the class can be used with its provider, and in each BackupStorage's status.backupClasses[] whether it can write to that storage. Each verdict is Compatible, Pending (it may still become compatible, for example while the provider starts) or Incompatible, with a reason. A Backup, Restore or BackupImport that combines an incompatible class, provider and storage is rejected when it is created.

Instance backup settings​

Backups of an instance are configured in Instance.spec.backup:

FieldDescription
enabledTurns backups on for the instance.
classRef.nameThe BackupClass to use. It must list the instance's provider.
storages[].storageRef.nameA BackupStorage in the same namespace.
storages[].schedules[]Schedules writing to this storage: name, enabled, cron, and optional retention and parameters. Schedule names must be unique across storages.
storages[].schedules[].retention{type: count, count: 7} keeps the last 7 backups; {type: time, duration: 30d} keeps backups for 30 days (d, w or m). Omit to keep all backups.
storages[].pitr.enabledUpload the transaction log to this storage for point-in-time recovery.
storages[].pitr.parametersPITR settings defined by the backup class.

Instance.status.backup.storages[] reports, for each storage, the location it is configured with and its point-in-time recovery window. Each storage is checked separately, so one storage that can't be used doesn't stop the others. Such a storage gets a reason and a message:

ReasonMeaning
BackupStorageNotFoundThe BackupStorage doesn't exist.
BackupStorageNotAcceptedThe storage isn't Accepted. The message gives its reason.
BackupStorageIncompatibleThe instance's backup class can't write to the storage.
BackupStorageLocationChangedThe storage now points somewhere else than when it was configured, for example because it was deleted and created again with the same name.
UnsupportedParameter, ImplementationUnsupported, TLSOptionUnsupportedThe provider can't use a parameter, the S3 implementation or the TLS setting of the storage.

While a storage can't be used, the provider keeps the last configuration that worked for it, so schedules and point-in-time recovery keep running. The BackupConfigured condition of the instance names every storage that isn't configured.

Backup​

One backup of an instance. Schedules create Backup resources automatically; create one yourself for an on-demand backup.

apiVersion: backup.openeverest.io/v1alpha1
kind: Backup
metadata:
name: orders-db-before-migration
namespace: demo
spec:
origin:
type: Instance
instanceRef:
name: orders-db
classRef:
name: pg
storageRef:
name: s3-backups
deletionPolicy: Delete
FieldDescription
origin.typeInstance for backups of an OpenEverest instance, External for imported backups.
origin.instanceRef.nameThe instance to back up.
classRef.name, storageRef.nameBackup class and storage.
scheduleNameSet on backups created by a schedule.
parametersExtra settings defined by the backup class, such as the backup type.
deletionPolicyDelete (default) removes the data from the storage when the backup is deleted, Retain keeps it.

The status.state is Pending, Running, Succeeded, Failed, Error or Deleting. Only Succeeded backups can be restored. A backup stays Pending, with a message naming what is missing, while its class, storage or instance doesn't exist yet.

status.path is the directory in the bucket the backup was written to, so it can be restored after its instance is gone. status.sourceMetadata records the engine version, topology and backup type of the source, which decide where the backup can be restored.

Restore​

Restores data into an existing instance.

apiVersion: backup.openeverest.io/v1alpha1
kind: Restore
metadata:
name: orders-db-restore-1
namespace: demo
spec:
instanceRef:
name: orders-db
dataSource:
type: Backup
backup:
backupRef:
name: orders-db-before-migration
FieldDescription
instanceRef.nameThe instance to restore into.
dataSource.typeBackup or PointInTime.
dataSource.backup.backupRef.nameThe backup to restore.
dataSource.pointInTime.source.storageRef.nameThe storage holding the transaction log.
dataSource.pointInTime.source.instanceRef.nameThe instance whose log to use. Defaults to the target instance.
dataSource.pointInTime.recoveryTargetdate or latest.
dataSource.pointInTime.dateThe time to restore to, when recoveryTarget is date.
parametersExtra settings defined by the backup class.

The same dataSource structure is used in Instance.spec.dataSource to create a new instance from a backup.

BackupImport​

Scans a backup storage for backups that OpenEverest doesn't know about yet, so they can be imported and used to create instances. The Import database page in the UI creates BackupImport resources for you. Only backup classes with supportsImport: true can be used.