Skip to main content
Version: v0.37 Stable
Enterprise
Available in these plansFreeDevProdScale
Auto Snapshots

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

Supported Configurations
Running the control plane as a container with:
Running the control plane as a binary with vCluster Standalone. When scaling with additional worker nodes, they are joined as private nodes.
Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

Snapshots

vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster Platform allows you to configure taking snapshots of the vCluster at specific intervals.

Manual snapshots with the vCluster CLI

For on-demand snapshot creation and restore operations, see the vCluster Snapshot and Restore documentation.

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. If you use private nodes, see Use snapshots with private nodes for additional restore steps.

Deployed etcd isn't supported

Snapshots aren't supported with deployed etcd (controlPlane.backingStore.etcd.deploy), so don't rely on scheduled snapshots to protect those tenant clusters.

In the vcluster.yaml, it is configured under snapshots. Using the UI, you can configure the management of snapshots in the config options of a tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster under Snapshots. Though snapshot configuration is configured on the tenant cluster itself, the capability and logic of scheduling snapshots is in vCluster Platform.

note

Auto Snapshot requires platform v4.4.0 or later.

Configure​

Enable auto snapshots​

To enable auto snapshots, add the following configuration to your vcluster.yaml:

Auto Snapshots configuration
snapshots:
  auto:
    # 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

S3 bucket example​

Snapshots can be stored in an S3 bucket.

Configure snapshots with S3
Standalone deployments

Automatic snapshots are supported for standalone deployments, with two differences: AWS pod identity authentication is not available, and the credentials secret must be created in the project namespace of the standalone cluster.

S3 configuration options​

OptionDescription
auto.storage.type.s3.urlURL of the AWS S3 bucket. Must be pre-fixed with s3://.
auto.storage.type.s3.credentialReferences the AWS credentials as a Kubernetes secret
auto.storage.type.s3.credential.nameName of the Kubernetes secret.
auto.storage.type.s3.credential.namespaceNamespace 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​

Not available for standalone

AWS pod identity authentication is not supported for standalone deployments. Use S3 credentials stored in a Kubernetes secret instead.

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

info

The EKS Pod Identity association must be created for the vCluster control plane pod. The vCluster control plane pod is the one that runs inside the control plane cluster namespace automatically created by vCluster Platform for each vCluster—typically named: loft-<project-name>-<vcluster-name>. By default, this pod uses the service account: vc-<vcluster-name>. This is the service account that must be associated with your EKS Pod Identity role so that the vCluster control plane can authenticate to AWS when performing scheduled snapshot creation to S3.

Example vcluster.yaml configuring snapshots into s3 with a pod identity
snapshots:
  auto:
    # 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 S3 credentials as a secret​

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

For standalone deployments, the secret must be created in the project namespace where the standalone cluster is created. The credential.namespace field is still part of the schema, but standalone deployments ignore it at runtime and always read the secret from that project namespace.

  1. Create a Kubernetes secret of your S3 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. If the vCluster is externally deployed, ensure the vCluster ClusterRole has permission to read the secret. The vCluster ClusterRole follows the naming pattern vc-<vClusterName>-v-<vClusterNamespace>.

    The secret needs to contain all these three keys:

    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_SESSION_TOKEN
    AWS_SESSION_TOKEN with static credentials

    AWS_SESSION_TOKEN must be present in the secret even if you don't use one. This applies to long-term static credentials and to S3-compatible storage that doesn't issue session tokens, such as MinIO, Ceph, or Dell ECS. If you don't have a session token, set the key to an empty string.

    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: ""
    EOF

  2. Create a vCluster referencing those credentials.

    Example vcluster.yaml referencing the Kubernetes secret
    snapshots:
      auto:
        # 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​

Configure snapshots with OCI

OCI configuration options​

OptionDescription
auto.storage.type.oci.repositoryOCI registry address. Must be pre-fixed with oci://
auto.storage.type.oci.credentialReference the OCI credentials as a Kubernetes secret
auto.storage.type.oci.credential.nameName of the Kubernetes secret
auto.storage.type.oci.credential.namespaceNamespace of the Kubernetes secret. The secret must be deployed on the host of where the vCluster control plane pod is deployed to.
auto.storage.type.oci.usernameUsername of the credentials to access the OCI registry
auto.storage.type.oci.passwordPassword 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 tenant cluster configuration. This protects the details of your credentials.

For standalone deployments, the secret must be created in the project namespace where the standalone cluster is created. The credential.namespace field is still part of the schema, but standalone deployments ignore it at runtime and always read the secret from that project namespace.

  1. 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. If the vCluster is externally deployed, ensure the vCluster ClusterRole has permission to read the secret. The vCluster ClusterRole follows the naming pattern vc-<vClusterName>-v-<vClusterNamespace>.

    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

  2. Create a vCluster referencing those credentials.

    Example vcluster.yaml referencing the Kubernetes secret
    snapshots:
      auto:
        # Take a snapshot every 12 hours
        schedule: 0 */12 * * *
        storage:
          type: oci
          oci:
            # Location of OCI registry
            # Must be prefixed with `oci://`
            repository: oci://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
snapshots:
  auto:
    # Take a snapshot every 12 hours
    schedule: 0 */12 * * *
    storage:
      type: oci
      oci:
        # Location of OCI registry
        # Must be prefixed with `oci://`
        repository: oci://my-registry/snapshots
        username: "my-username"
        password: "my-password"

Auto snapshots on standalone tenant clusters​

note

Auto snapshots on a standalone tenant cluster require vCluster v0.37 or later, in addition to the platform version requirement above. The standalone runtime needs to pull its own storage credentials from the platform, which it can only do from v0.37 onward.

These restrictions apply no matter which method above you use to configure auto snapshots. Standalone tenant clusters have additional restrictions on snapshots.auto.storage:

  • Only s3, oci, and azure are supported. container (local filesystem) storage is rejected. The volume exists only inside the tenant cluster, so the platform can't list or prune it from outside.
  • A storage credential must be configured explicitly. Ambient cloud identity, such as an AWS instance profile or IRSA, isn't available. The platform resolves credentials on the tenant's behalf, and has no access to the tenant's own cloud identity.
  • An Azure Blob URL containing a SAS token is rejected, since it would persist the token in plaintext in the tenant's snapshot request.
  • Any configured secretNamespace on the storage credential is ignored. The platform always reads the credential Secret from the Platform project namespace containing the VirtualClusterInstance, regardless of secretNamespace. This restriction is specific to standalone. Pod-based tenant clusters honor secretNamespace normally.

To avoid giving the tenant cluster standing access to the credential Secret, the platform exposes a snapshotcredentials API. A standalone tenant cluster retrieves the configured credentials at snapshot time and uses them in memory without persisting them. The platform doesn't shorten or rotate credentials stored in the Secret.

The restore workflow also splits differently for standalone. Snapshot creation is delegated to the tenant cluster itself, since only it can snapshot its own etcd. The platform drops a request in the tenant's own kube-system namespace, and the tenant cluster reconciles it. Snapshot list and delete run on the platform side directly against the object store instead, since those operations don't need access to the tenant cluster. See Restore a standalone vCluster for the restore side.

Config reference​

snapshots object ​

Snapshots holds configuration for automatic vCluster snapshots.

auto object ​

Auto holds automatic snapshot configuration

schedule string ​

Schedule specifies a scheduled time in Cron format, see https://en.wikipedia.org/wiki/Cron for a tenant cluster snapshot to be taken

timezone string ​

Timezone specifies time zone used for scheduled snapshot operations. Defaults to UTC. Accepts the same format as time.LoadLocation() in Go (https://pkg.go.dev/time#LoadLocation). The value should be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York".

retention object ​

Retention specifies how long snapshots will be kept

period integer ​

Period defines the number of days a snapshot will be kept

maxSnapshots integer ​

MaxSnapshots defines the number of snapshots that can be taken

storage object ​

Storage specifies where the snapshot will be stored

type string ​

Type specifies supported type of storage services for a snapshot S3/OCI/Container, see https://www.vcluster.com/docs/vcluster/manage/backup-restore#store-snapshots-in-s3-buckets

s3 object ​

S3 holds configuration for storing snapshots in S3-compatible bucket

url string ​

Url specifies url to the storage service

credential object ​

Credential secret with the S3 Credentials, it should contain AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN

secretName string ​

SecretName is the secret name with credential

secretNamespace string ​

SecretNamespace is the secret namespace with credential

oci object ​

OCI holds configuration for storing snapshots in OCI image registries

repository string ​

Repository OCI repository to store the snapshot

credential object ​

Credential secret with the OCI Credentials

secretName string ​

SecretName is the secret name with credential

secretNamespace string ​

SecretNamespace is the secret namespace with credential

username string ​

Username to authenticate with the OCI registry

password string ​

Password to authenticate with the OCI registry

container object ​

Container holds configuration for storing snapshots as local files inside a vCluster container

path string ​

Path specifies directory to store the snapshot

volume object ​

Volume specifies which volume needs to be mounted into the container to store the snapshot

name string ​

Name to be used to mount the volume

path string ​

Path to the volume mount

azure object ​

Azure holds configuration for storing snapshots in Azure Blob Storage

blobUrl string ​

BlobURL specifies the Azure Blob Storage URL in the format https://{account}.blob.core.windows.net/{container}/{path}

credential object ​

Credential secret with the Azure credentials. The secret should contain either: AZURE_STORAGE_KEY (storage account access key), or AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP (service principal)

secretName string ​

SecretName is the secret name with credential

secretNamespace string ​

SecretNamespace is the secret namespace with credential