New to KubeStash? Please start here.

BackupSession

What is BackupSession

A BackupSession is a Kubernetes CustomResourceDefinition(CRD) which represents a backup run triggered for a session of a BackupConfiguration for a target application.

KubeStash operator creates a Kubernetes CronJob according to the schedule for each session defined in a BackupConfiguration. On each backup schedule, this CronJob creates a BackupSession object that corresponds to the respective session specified in the BackupConfiguration. The BackupSession will trigger a backup executor job to initiate the backup process.

You can also create a BackupSession object manually to trigger backup at any time.

BackupSession CRD Specification

Like any official Kubernetes resource, a BackupSession has TypeMeta, ObjectMeta and Spec , Status sections.

A sample BackupSession created for backing up an Application and it’s components’ is shown below,

apiVersion: core.kubestash.com/v1alpha1
kind: BackupSession
metadata:
  creationTimestamp: "2023-12-14T08:40:01Z"
  finalizers:
  - kubestash.com/cleanup
  generation: 1
  name: sample-backup-sts-demo-session-1702543201
  namespace: demo
  ownerReferences:
  - apiVersion: core.kubestash.com/v1alpha1
    blockOwnerDeletion: true
    controller: true
    kind: BackupConfiguration
    name: sample-backup-sts
    uid: 83b71921-16be-4300-bc72-9eed5a94de58
  resourceVersion: "344530"
  uid: 948cd21a-cc2d-4c4a-ba8f-d5045ffa32f9
spec:
  invoker:
    apiGroup: core.kubestash.com
    kind: BackupConfiguration
    name: sample-backup-sts
  retryLeft: 2
  session: demo-session
status:
  conditions:
  - lastTransitionTime: "2023-12-14T08:40:01Z"
    message: Snapshots have been ensured successfully.
    reason: SuccessfullyEnsuredSnapshots
    status: "True"
    type: SnapshotsEnsured
  - lastTransitionTime: "2023-12-14T08:40:01Z"
    message: Backup Executor has been ensured successfully.
    reason: SuccessfullyEnsuredBackupExecutor
    status: "True"
    type: BackupExecutorEnsured
  - lastTransitionTime: "2023-12-14T08:40:33Z"
    reason: SuccessfullyCleanedSessionHistory
    status: "True"
    type: SessionHistoryCleaned
  - lastTransitionTime: "2023-12-14T08:40:33Z"
    message: Metrics have been pushed successfully.
    reason: SuccessfullyPushedMetrics
    status: "True"
    type: MetricsPushed
  phase: Succeeded
  retentionPolicy:
  - phase: Applied
    ref:
      name: demo-retention
      namespace: demo
    repository: gcs-demo-repo
  snapshots:
  - appRef:
      apiGroup: apps
      kind: StatefulSet
      name: sample-sts
      namespace: demo
    name: gcs-demo-repo-sample-backup-sts-demo-session-1702543201
    phase: Succeeded
    repository: gcs-demo-repo

Here, we are going to describe the various sections of a BackupSession object.

BackupSession Metadata

metadata.name

metadata.name indicates the name of the BackupSession. This name is automatically generated by respective CronJob and it follows the following pattern: <BackupConfiguration name>-<session name>-<creation timestamp in Unix epoch seconds>.

metadata.namespace

metadata.namespace indicates the name of the BackupSession. It is the same as the namespace of respective BackupConfiguration object.

If you create BackupSession manually to trigger a backup instantly, make sure that you have provided a valid invoker at spec.invoker field to your BackupSession.

BackupSession Spec

A BackupSession object has the following fields in the spec section:

spec.invoker

spec.invoker specifies the apiGroup, kind, and name of the respective object which is responsible for invoking this backup session.

spec.session

spec.session specifies the name of the session that triggered this backup.

spec.retryLeft

spec.retryLeft specifies the number of retry attempt left for this backup session. If this set to non-zero, KubeStash will create a new BackupSession if the current one fails.

BackupSession Status

.status section of BackupSession shows stats and progress of backup process in this session. .status section consists of the following fields:

status.phase

status.phase indicates the overall phase of the backup process for this BackupSession. It will be Succeeded only when all Snapshots are successfully completed and the post-backup actions are successful. If any of the snapshots fail to complete backup, status.phase will be Failed.

status.duration

status.duration specifies the time required to complete the backup process.

status.sessionDeadline

status.sessionDeadline indicates the deadline of the backup process. BackupSession will be considered Failed if the backup does not complete within this deadline.

status.snapshots

status.snapshots specifies the Snapshots status. It contains the following fields:

• name : indicates to the name of the Snapshot.
• phase : indicates the phase of the Snapshot.
• appRef : points to the application that is being backed up in this Snapshot.
• repository : indicates the name of the Repository where the Snapshot is being stored.

status.hooks

status.hooks represents the hook execution status. Each hook contains the following fields:

• preHooks : represents the pre-restore hook execution status.
• postHooks : represents the post-restore hook execution status.

Each preHook or postHook contains the following fields:

• name : indicates the name of the hook whose status is being shown here.
• phase : represents the hook execution phase.

status.retentionPolicy

status.retentionPolicy specifies whether the retention policies were properly applied on the repositories or not. Each one of them consists of the following fields:

• ref : points to the RetentionPolicy CR that is being used to cleanup the old Snapshots for this session.
• repository : specifies the name of the Repository on which the RetentionPolicy has been applied.
• phase : specifies the state of retention policy apply process.
• error : represents the reason if the retention policy applying fail.

status.retried

status.retried is a boolean field which specifies whether this session was retried or not in case of failed backup. This field will exist only if the retryConfig has been set in the respective backup invoker.

status.nextRetry

status.nextRetry specifies the timestamp when this backup will be retried if it has failed. This field will exist only if the retryConfig has been set in the respective backup invoker.

status.conditions

status.conditions shows the conditions of different operations/steps of the backup process. The following conditions are set by the KubeStash operator on a BackupSession.

Next Steps

• Learn how backup of workloads data works from here.
• Learn how backup stand alone PVC works from here.