Version: main 🚧

Snapshots

vCluster Platform allows you to configure taking snapshots of the vCluster at specific intervals.

This allows administrators to capture and store the vCluster state in scheduled intervals to help protect against infrastructure failures, data corruption, and configuration errors. By maintaining consistent recovery points, administrators can quickly restore the vCluster to a known good state without relying on manual backup processes. For more details on how snapshots work, please refer to the documentation in the Snapshot and Restore section.

In the vcluster.yaml, it is configured under external.platform.autoSnapshot. Using the UI, you can configure the management of snapshots in the config options of a virtual cluster under Snapshots. Though snapshot configuration is configured on the virtual cluster itself, the functionality and logic of scheduling snapshots is in vCluster Platform.

Snapshot scheduling and retention

Scheduling is based on a cron schedule and you can determine what time zone to start the schedule. The number of snapshots to keep is based on how many days are set for the retention period as well as how many total successful snapshots that you want to keep at any given time.

Example vcluster.yaml of enabling snapshots
external:
  platform:
    autoSnapshot:
      enabled: true
      # Take a snapshot every 12 hours
      schedule: 0 */12 * * * 
      # Default is UTC
      # Options are at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      timezone: America/New_York
      retention:
        period: 30
        maxSnapshots: 14
      storage:
        type: s3
        s3:
          url: s3://my-bucket/path
      

Scheduling and Retention Options

Option	Required	Description	Default
`enabled`	Yes	Determines whether auto snapshots are enabled or disabled.	`false`
`timezone`	No	Determine when midnight is considered based on time zone.	`UTC`
`schedule`	Yes	Configure the schedule of taking snapshots by specifying a cron schedule.	None
`retention.period`	No	Number of days that a snapshot will be stored in the storage service.	`30`
`retention.maxSnapshots`	No	Number of snapshots that can be stored in the storage service.	`30`

Supported storage backends

The snapshot file can be saved in specific locations:

AWS S3 buckets
OCI registries

Storage Type Options

Option	Description
`storage.type`	Defines the type of storage used to store the snapshot, the platform supports the following types: AWS S3 and OCI.

AWS S3 buckets

Snapshots can be stored in an AWS S3 bucket.

S3 Configuration Options

Option	Description
`storage.type.s3.url`	URL of the AWS S3 bucket. Must be pre-fixed with `s3://`.
`storage.type.s3.credential`	References the AWS credentials as a Kubernetes secret
`storage.type.s3.credential.name`	Name of the Kubernetes secret.
`storage.type.s3.credential.namespace`	Namespace of the Kubernetes secret. The secret must be deployed on the host of where the vCluster control plane pod is deployed to.

Authenticate with AWS Pod identity

When using AWS S3 buckets, it is recommended to authenticate using AWS pod identity.

Example vcluster.yaml configuring snapshots into s3 with a pod identity
external:
  platform:
    autoSnapshot:
    enabled: true
    # Take a snapshot every 12 hours
    schedule: 0 */12 * * * 
    storage:
      type: s3
        s3:
          # URL of location of S3-compatible bucket
          # Must be prefixed with `s3://`
          url: s3://<bucket-name>/snapshots

Authenticate with AWS Credentials as a secret

Alternatively, you can create a Kubernetes secret with your AWS credentials.

Create a Kubernetes secret of your AWS credentials.
Create this secret on the host of where the vCluster control plane is deployed. It could be deployed in the namespace of the vCluster or a different namespace.
The secret needs to contain all these three keys:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN
Create AWS credentials secret
```
kubectl create -f - <<EOF
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: aws-cred
  namespace: p-default
data:
  AWS_ACCESS_KEY_ID: "id"
  AWS_SECRET_ACCESS_KEY: "key" 
  AWS_SESSION_TOKEN: "token"
EOF
```

Create a vCluster referencing those credentials.

Example vcluster.yaml referencing the Kubernetes secret
external:
  platform:
    autoSnapshot:
      enabled: true
      # Take a snapshot every 12 hours
      schedule: 0 */12 * * * 
      storage:
        type: s3
        s3:
          # URL of location of S3-compatible bucket
          # Must be prefixed with `s3://`
          url: s3://<bucket-name>/<path>
          # Secret must be located on the host cluster that the vCluster is deployed on
          credential:
            secretName: aws-cred
            secretNamespace: p-default

OCI image registries

Snapshots can be stored in an OCI image registry.

OCI Configuration Options

Option	Description
`storage.type.oci.repository`	OCI registry address. Must be pre-fixed with `oci://`
`storage.type.oci.credential`	Reference the OCI credentials as a Kubernetes secret
`storage.type.oci.credential.name`	Name of the Kubernetes secret
`storage.type.oci.credential.namespace`	Namespace of the Kubernetes secret. The secret must be deployed on the host of where the vCluster control plane pod is deployed to.
`storage.type.oci.username`	Username of the credentials to access the OCI registry
`storage.type.oci.password`	Password of the credentials to access the OCI registry

Authenticate with credentials in a Kubernetes secret

It's recommended to store your credentials to your OCI registry in a secret and reference the secret in the vcluster.yaml of your virtual cluster configuration. This protects the details of your credentials.

Create a Kubernetes secret of your credentials to your OCI registry.
Create this secret on the host of where the vCluster control plane is deployed. It could be deployed in the namespace of the vCluster or a different namespace.
The secret needs to contain:
- username
- password
Create OCI credentials secret
```
kubectl create -f - <<EOF
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: oci-cred
  namespace: p-default
data:
  username: "id" # username to authenticate with the OCI registry
  password: "key" # password base64 to authenticate with the OCI registry 
EOF
```

Create a vCluster referencing those credentials.

Example vcluster.yaml referencing the Kubernetes secret
external:
  platform:
    autoSnapshot:
      enabled: true
      # Take a snapshot every 12 hours
      schedule: 0 */12 * * * 
      storage:
        type: oci
        oci:
          # Location of S3 bucket
          # Must be prefixed with `oci://`
          repository: s3://my-registry/snapshots
          credential:
            secretName: oci-cred
            secretNamespace: p-default

Authenticate without a Kubernetes secret

If you do not want to use a secret, you can also explicitly set the username and password directly in the vcluster.yaml.

Example vcluster.yaml setting OCI credentials without a secret
external:
    platform:
      autoSnapshot:
        enabled: true
        # Take a snapshot every 12 hours
        schedule: 0 */12 * * * 
        storage:
          type: oci
          oci:
            # Location of S3 bucket
            # Must be prefixed with `oci://`
            repository: s3://my-registry/snapshots
            credential:
              username: "my-username"
              password: "my-pasword"

View Snapshots

After enabling automatic snapshots, you can view the list of snapshots for each virtual cluster in the details of the virtual cluster.

Snapshot Name

Snapshots are identified by a generated name formatted as <Virtual_Cluster_Name>-<Snapshot_Timestamp>.tar.gz.

Snapshot schedule lifecycle

Snapshots transition through different statuses as part of their execution lifecycle. A typical flow starts with the snapshot being in the Scheduled state, then moves to the In Progress state while it is being stored. If the snapshot and storage is successful, the snapshot moves to the Stored state. If an error occurs, it temporarily enters the Error state before retrying. The snapshot will be attempted one more time before moving to a Failed state.

If a snapshot was removed from the storage backend, but not in vCluster Platform, the snapshot appears in the Not Found state.

Snapshot Status	Description
`Scheduled`	A snapshot that is scheduled to be stored in the storage backend service. Only one snapshot can have the Scheduled status at a time.
`In Progress`	A snapshot that is currently being stored in the storage backend service.
`Stored`	A snapshot that has been successfully stored in the storage backend service.
`Error`	A snapshot that failed on the first attempt but will be retried.
`Failed`	A snapshot that failed to be generated.
`Not Found`	A snapshot that appears in the list but has been removed from the storage backend service.

Snapshot scheduling and retention​

Scheduling and Retention Options​

Supported storage backends​

Storage Type Options​

AWS S3 buckets​

S3 Configuration Options​

Authenticate with AWS Pod identity​

Authenticate with AWS Credentials as a secret​

OCI image registries​

OCI Configuration Options​

Authenticate with credentials in a Kubernetes secret​

Authenticate without a Kubernetes secret​

View Snapshots​

Snapshot Name​

Snapshot schedule lifecycle​