Skip to main content
Version: v0.34 Stable

Create snapshots

Supported Configurations
Running the control plane as a container with:

There are multiple ways to back up and restore a tenant cluster. vCluster provides a built-in method to create and restore snapshots using its CLI.

Scheduled snapshots with vCluster Platform

Need automated, scheduled snapshots? vCluster Platform AutoSnapshots lets you configure automatic snapshot creation on a cron schedule with retention policies. No need to write custom Kubernetes jobs.

warning

External databases such as MySQL or PostgreSQL that run outside the vCluster namespace require a separate backup. Refer to the relevant database documentation.

Create a snapshot​

We recommend using the vCluster CLI vcluster snapshot create command to back up the etcd datastore. Optionally, you can also create snapshots of your CSI volumes by running vcluster snapshot create with the --include-volumes flag.

warning

Without the --include-volumes flag, vCluster doesn't back up persistent volumes.

info

The vCluster snapshot feature currently only supports creating snapshots for CSI persistent volumes. See Volume snapshots for more details. To back up non-CSI persistent volumes (e.g. local volumes), use the Velero backup method.

When you run vcluster snapshot create, the CLI submits a snapshot request. The vCluster snapshot controller processes it in the background. Here is an example:

vcluster snapshot create myvcluster "container:///data/my-snapshot.tar.gz"
13:52:09 info Beginning snapshot creation... You can check the snapshot creation progress with the following command: vcluster snapshot get myvcluster "container:///data/my-snapshot.tar.gz"'

You can check the snapshot creation progress with the following command:

vcluster snapshot get myvcluster "container:///data/my-snapshot.tar.gz"

                  SNAPSHOT               |  STATUS   | AGE
  ---------------------------------------+-----------+------
    container:///data/my-snapshot.tar.gz | Completed | 28s

The vCluster snapshot controller automatically determines the configured backing store and saves the snapshot at the specified location. The snapshot includes:

  • Backing store data (for example, etcd or SQLite)
  • vCluster Helm release information
  • vCluster configuration (for example, vcluster.yaml)
  • If you used the --include-volumes flag:
    • List of PVCs with snapshots
    • Volume snapshot identifiers

Standalone​

Standalone vCluster runs as a systemd service directly on a Linux host, without a Kubernetes cluster. Use the --standalone flag instead of a cluster name to target the local standalone installation. This flag can't be used with --driver docker.

Modify the following with your specific values to generate a copyable command:
Create a snapshot on a standalone vCluster
vcluster snapshot create --standalone "s3://my-s3-bucket/my-bucket-key"

Check the snapshot status with:

Modify the following with your specific values to generate a copyable command:
Check snapshot status on a standalone vCluster
vcluster snapshot get --standalone "s3://my-s3-bucket/my-bucket-key"
External storage for cross-node recovery

The container:// protocol stores the snapshot on the local filesystem of the standalone node. For disaster recovery scenarios where you need to restore to a different node, use an external storage backend such as OCI, S3, or Azure Blob Storage.

Snapshot URL​

vCluster uses a snapshot URL to save the snapshot to a specific location. The snapshot URL contains the following information:

ParameterDescriptionExample
ProtocolDefines the storage type for the snapshotoci, s3, container, https (Azure Blob Storage)
Storage locationSpecifies where to save the snapshotoci://ghcr.io/my-user/my-repo:my-tag, s3://my-s3-bucket/my-snapshot-key, https://myaccount.blob.core.windows.net/my-container/my-snapshot.tar.gz, container:///data/my-snapshot.tar.gz
Optional flagsAdditional options for snapshot storageskip-client-credentials=true

Supported protocols​

The following protocols are supported for storing snapshots:

  • oci – Stores snapshots in an OCI image registry, such as Docker Hub or GHCR.
  • s3 – Saves snapshots to an S3-compatible bucket, such as AWS S3 or MinIO.
  • Azure Blob Storage – Saves snapshots to Azure Blob Storage.
  • container – Stores snapshots as a local file inside a vCluster container or another persistent volume claim (PVC).

For example, the following snapshot URL saves the snapshot to an OCI image registry:

Modify the following with your specific values to generate a copyable command:
Snapshot and push to an OCI image registry
vcluster snapshot create my-vcluster "oci://ghcr.io/my-user/my-repo:my-tag"

Store snapshots in OCI image registries​

You can save snapshots to OCI image registries. Authenticate using locally stored OCI credentials, or pass credentials directly in the snapshot URL.

To authenticate with local credentials, log in to your OCI registry and create the snapshot:

Modify the following with your specific values to generate a copyable command:
Authenticate with local OCI credentials and create a snapshot
# Log in to the OCI registry using a password access token.
echo $PASSWORD_ACCESS_TOKEN | docker login ghcr.io -u $USERNAME --password-stdin

# Create a snapshot and push it to an OCI image registry.
vcluster snapshot create my-vcluster "oci://ghcr.io/my-user/my-repo:my-tag"

Alternatively, pass credentials directly in the snapshot URL. The following parameters configure authentication:

ParameterDescriptionRequired
usernameUsername for authenticating with the OCI registryYes, when not using local credentials
passwordBase64-encoded password for authenticating with the OCI registryYes, when not using local credentials
skip-client-credentialsWhen set to true, ignores local Docker credentialsNo, defaults to false
Modify the following with your specific values to generate a copyable command:
Pass OCI credentials directly in the snapshot URL
# Pass authentication credentials directly in the URL and create a snapshot.
export OCI_USERNAME=my-username
export OCI_PASSWORD=$(echo -n "my-password" | base64)
vcluster snapshot create my-vcluster "oci://ghcr.io/my-user/my-repo:my-tag?username=$OCI_USERNAME&password=$OCI_PASSWORD&skip-client-credentials=true"

Store snapshots in S3 buckets​

Store snapshots in an S3-compatible bucket using the s3 protocol. This works with AWS S3 and S3-compatible providers such as MinIO or Ceph. These are common in on-premise and air-gapped environments where cloud storage isn't available.

You can authenticate in two ways: by using local environment credentials or by passing credentials directly in the URL.

To use local environment credentials, log in to AWS CLI, then create and save the snapshot:

Modify the following with your specific values to generate a copyable command:
Create and store a snapshot in an S3 bucket using AWS CLI credentials
# Check if you are logged in.
aws sts get-caller-identity

# Create a snapshot and store it in an S3 bucket.
vcluster snapshot create my-vcluster "s3://my-s3-bucket/my-bucket-key"

Alternatively, you can pass options directly in the snapshot URL. The following options are supported:

FlagDescriptionRequired
access-key-idBase64-encoded S3 access key ID for authenticationYes, when not using local credentials
secret-access-keyBase64-encoded S3 secret access key for authenticationYes, when not using local credentials
session-tokenBase64-encoded temporary session token for authenticationYes, when not using local credentials
regionRegion of the S3-compatible bucketNo
urlBase64-encoded custom endpoint URL for S3-compatible providers (e.g. MinIO, Ceph)No
force-path-styleUse path-style addressing (endpoint/bucket) instead of virtual-hosted-style. Required for most S3-compatible providers.No, defaults to false
profileAWS profile to use for authenticationNo
skip-client-credentialsSkips use of local credentials for authenticationNo, defaults to false
server-side-encryptionServer-side encryption method (AES256 for SSE-S3, aws:kms for SSE-KMS)No
kms-key-idKMS key ID for SSE-KMS encryptionNo
Security

Credentials passed in the snapshot URL are Base64-encoded, not encrypted. Avoid storing snapshot commands with inline credentials in shell history, scripts, or CI logs. For production environments, prefer local credential-based authentication with aws configure or a Kubernetes Secret, and set skip-client-credentials=false.

Run the following command to create a snapshot and store it in an S3 bucket:

Modify the following with your specific values to generate a copyable command:
Pass S3 credentials directly in the URL to create a snapshot
# Read the AWS credentials from files and encode them with base64
# This allows them to be safely included in the S3 URL
export ACCESS_KEY_ID=$(cat my-access-key-id.txt | base64)
export SECRET_ACCESS_KEY=$(cat my-secret-access-key.txt | base64)
export SESSION_TOKEN=$(cat my-session-token.txt | base64)

vcluster snapshot create my-vcluster "s3://my-s3-bucket/my-bucket-key?access-key-id=$ACCESS_KEY_ID&secret-access-key=$SECRET_ACCESS_KEY&session-token=$SESSION_TOKEN"
S3-compatible providers​

S3-compatible providers such as MinIO or Ceph require two additional parameters: url to specify the custom endpoint and force-path-style to use path-style bucket addressing. These providers don't use session tokens, so you can omit that parameter.

Modify the following with your specific values to generate a copyable command:
Store a snapshot with an S3-compatible provider
# Base64-encode the credentials and the custom endpoint URL
export ACCESS_KEY_ID=$(cat my-access-key-id.txt | base64)
export SECRET_ACCESS_KEY=$(cat my-secret-access-key.txt | base64)
export ENDPOINT=$(echo -n "https://s3.example.com:9000" | base64)

vcluster snapshot create my-vcluster "s3://my-bucket/my-snapshot-key?access-key-id=$ACCESS_KEY_ID&secret-access-key=$SECRET_ACCESS_KEY&url=$ENDPOINT&region=us-east-1&force-path-style=true"
S3 encryption support​

vCluster supports server-side encryption for S3 snapshots to meet security requirements. See the CLI reference for all available flags.

SSE-S3 (AES256)

Modify the following with your specific values to generate a copyable command:
vcluster snapshot create my-vcluster "s3://my-bucket/my-snapshot-key" --server-side-encryption AES256

SSE-KMS

Modify the following with your specific values to generate a copyable command:
vcluster snapshot create my-vcluster "s3://my-bucket/my-snapshot-key" --kms-key-id "12345678-1234-1234-1234-123456789012"

Example: Bucket policy requiring encryption

Enforce SSE-S3 encryption
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "DenyUnencryptedUploads",
    "Effect": "Deny",
    "Principal": "*",
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::my-bucket/*",
    "Condition": {
      "StringNotEquals": {
        "s3:x-amz-server-side-encryption": "AES256"
      }
    }
  }]
}

Store snapshots in Azure Blob Storage​

Store snapshots in Azure Blob Storage using the standard Azure Blob HTTPS URL:

https://<account>.blob.core.windows.net/<container>/<blob-path>

vCluster supports three ways to authenticate:

Log in with az login before running the snapshot command. You must also provide the subscription ID and resource group for the storage account as CLI flags or environment variables (AZURE_SUBSCRIPTION_ID and AZURE_RESOURCE_GROUP):

Modify the following with your specific values to generate a copyable command:
Create and store a snapshot in Azure Blob Storage using Azure CLI credentials
# Log in to Azure.
az login

# Create a snapshot and store it in Azure Blob Storage.
vcluster snapshot create my-vcluster "https://myaccount.blob.core.windows.net/my-container/my-snapshot.tar.gz" \
--azure-subscription-id my-subscription-id \
--azure-resource-group my-resource-group
Security

When using Azure CLI credentials or a storage account key, the vCluster CLI generates a short-lived SAS token and stores it in a Kubernetes Secret. The snapshot controller reads this token to upload the snapshot to Azure Blob Storage. vCluster deletes the Secret once the snapshot completes.

Store snapshots in containers​

Use the container protocol to save snapshots as local files inside a vCluster container. Run the following command to create a snapshot and store it in the specified path inside a container:

Modify the following with your specific values to generate a copyable command:
Create snapshots inside a vCluster container
# Create a snapshot to local vCluster PVC (if using embedded storage).
vcluster snapshot create my-vcluster "container:///data/my-snapshot.tar.gz"

Limitations​

When taking snapshots and restoring tenant clusters, there are limitations:

Sleeping tenant clusters

  • Snapshots require a running vCluster control plane and don't work with sleeping tenant clusters.

Tenant clusters using an external database

  • Tenant clusters with an external database handle backup and restore outside of vCluster. A database administrator must back up or restore the external database according to the database documentation. Avoid using the vCluster CLI backup and restore commands for clusters with an external database.

Distribution

  • Snapshots work only with K8s.

Cluster Certificates

  • vCluster doesn't include cluster certificates in snapshots.