Configure Velero storage backends

What you’ll accomplish

You’ll configure Velero’s backup storage destination, provide credentials, and customize the backup schedule and retention to match your environment’s requirements.

Prerequisites

• UDS CLI installed
• UDS Registry account created and authenticated locally with a read token
• Access to a Kubernetes cluster with UDS Core deployed
• An S3-compatible or Azure Blob storage endpoint for backup data

Before you begin

UDS Core ships with these backup defaults:

Setting	Default
Schedule	Daily at 03:00 UTC (0 3 * * *)
Retention	10 days (240h)
Excluded namespaces	kube-system, velero
Cluster resources	Included
Volume snapshots	Disabled

Velero’s storage configuration uses two Helm charts:

Chart	Scope
velero (upstream)	Credentials, backup storage location, schedule, volume snapshot settings
uds-velero-config (UDS)	Storage network egress policy

S3-compatible storage is configured through Zarf variables set in your uds-config.yaml. Azure Blob Storage is configured through bundle overrides.

Steps

1. Configure your storage destination

   S3-compatible storage

   Choose the authentication method that matches your environment.

   Static access keys

   Add the following variables to your uds-config.yaml:

   uds-config.yaml

   variables:
     core:
       VELERO_BUCKET_PROVIDER_URL: "https://s3.us-east-1.amazonaws.com"
       VELERO_BUCKET: "my-velero-backups"
       VELERO_BUCKET_REGION: "us-east-1"
       VELERO_BUCKET_KEY: "<your-access-key>"
       VELERO_BUCKET_KEY_SECRET: "<your-secret-key>"

   The full set of available variables:

   Variable	Description	Default
   VELERO_BUCKET_PROVIDER_URL	S3 endpoint URL	http://minio.uds-dev-stack.svc.cluster.local:9000
   VELERO_BUCKET	Bucket name	uds
   VELERO_BUCKET_REGION	Bucket region	uds-dev-stack
   VELERO_BUCKET_KEY	Access key ID	uds
   VELERO_BUCKET_KEY_SECRET	Secret access key	uds-secret
   VELERO_BUCKET_CREDENTIAL_NAME	Kubernetes Secret name for credentials	velero-bucket-credentials
   VELERO_BUCKET_CREDENTIAL_KEY	Key within the credentials Secret	cloud

   Note

   The defaults point to an in-cluster MinIO instance used for local development. For production, set all values to match your S3-compatible storage provider.

   Existing Kubernetes Secret

   If your environment pre-provisions Kubernetes Secrets (for example, via an external secrets operator), you can reference an existing Secret instead of having Zarf create one:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           velero:
             values:
               - path: credentials.existingSecret
                 value: "velero-bucket-credentials"

   The Secret must follow this format:

   apiVersion: v1
   kind: Secret
   metadata:
     name: velero-bucket-credentials
     namespace: velero
   type: Opaque
   stringData:
     cloud: |
       [default]
       aws_access_key_id=<your-access-key>
       aws_secret_access_key=<your-secret-key>

   IRSA on Amazon EKS

   IRSA (IAM Roles for Service Accounts) lets Velero assume an IAM role without storing credentials in the cluster. The Amazon EKS OIDC webhook injects temporary credentials that the AWS SDK uses automatically.

   Before configuring your bundle, provision the required IAM resources. The examples below use OpenTofu and assume an aws provider is already configured in your workspace.

   Create the S3 access policy:

   velero-s3-policy.tf

   # Velero S3 backup storage policy
   # Reference: https://github.com/vmware-tanzu/velero-plugin-for-aws?tab=readme-ov-file#set-permissions-for-velero
   data "aws_iam_policy_document" "velero_s3" {
     statement {
       effect  = "Allow"
       actions = [
         "s3:GetObject",
         "s3:DeleteObject",
         "s3:PutObject",
         "s3:AbortMultipartUpload",
         "s3:ListMultipartUploadParts",
       ]
       resources = ["arn:aws:s3:::YOUR_VELERO_BUCKET/*"]
     }
   
     statement {
       effect  = "Allow"
       actions = [
         "s3:ListBucket",
         "s3:GetBucketLocation",
         "s3:ListBucketMultipartUploads",
       ]
       resources = ["arn:aws:s3:::YOUR_VELERO_BUCKET"]
     }
   }
   
   resource "aws_iam_policy" "velero_s3" {
     name   = "velero-s3-policy"
     policy = data.aws_iam_policy_document.velero_s3.json
   }

   Note

   Replace YOUR_VELERO_BUCKET with your backup bucket name. If the bucket uses SSE-KMS encryption, also grant kms:Decrypt, kms:GenerateDataKey, and kms:DescribeKey on the KMS key ARN.

   Create a role that the velero-server service account in the velero namespace can assume:

   velero-irsa-role.tf

   # The OIDC provider URL for your EKS cluster, without the https:// prefix.
   # Example: oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE1234567890
   variable "oidc_provider" {
     description = "EKS cluster OIDC provider URL (without https://)"
   }
   
   # Look up the OIDC provider already registered in IAM for this cluster
   data "aws_iam_openid_connect_provider" "eks" {
     url = "https://${var.oidc_provider}"
   }
   
   data "aws_iam_policy_document" "velero_irsa_trust" {
     statement {
       effect = "Allow"
   
       principals {
         type        = "Federated"
         identifiers = [data.aws_iam_openid_connect_provider.eks.arn]
       }
   
       actions = ["sts:AssumeRoleWithWebIdentity"]
   
       condition {
         test     = "StringEquals"
         variable = "${var.oidc_provider}:sub"
         # Scopes the role to the velero-server service account in the velero namespace
         values   = ["system:serviceaccount:velero:velero-server"]
       }
   
       condition {
         test     = "StringEquals"
         variable = "${var.oidc_provider}:aud"
         values   = ["sts.amazonaws.com"]
       }
     }
   }
   
   resource "aws_iam_role" "velero" {
     name               = "velero-backup-role"
     assume_role_policy = data.aws_iam_policy_document.velero_irsa_trust.json
   }
   
   resource "aws_iam_role_policy_attachment" "velero_s3" {
     role       = aws_iam_role.velero.name
     policy_arn = aws_iam_policy.velero_s3.arn
   }

   Place both .tf files in the same directory. Supply oidc_provider via a -var flag or a terraform.tfvars file, then apply:

   tofu init
   tofu plan
   tofu apply

   Note

   If you use Terraform instead of OpenTofu, replace tofu with terraform: the commands are identical.

   Add the overrides below to your bundle. Setting credentials.useSecret: false tells Velero not to mount a credentials file, so the AWS SDK uses the web identity token the IRSA webhook injects. The configuration.backupStorageLocation override replaces the default UDS Core configuration, which includes a credential Secret reference incompatible with IRSA.

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           velero:
             variables:
               # IRSA role ARN annotated on the Velero service account
               - name: VELERO_IRSA_ROLE_ARN
                 path: serviceAccount.server.annotations.eks\.amazonaws\.com/role-arn
             values:
               # Disable the credentials Secret; Velero uses the web identity token from the IRSA webhook
               - path: credentials.useSecret
                 value: false
               # Override the backup storage location to remove the credential reference
               # used by the default static-key configuration
               - path: configuration.backupStorageLocation
                 value:
                   - name: default
                     provider: aws
                     bucket: "<your-bucket-name>"
                     config:
                       region: "<your-region>"
                       s3ForcePathStyle: false

   Supply the role ARN in your uds-config.yaml:

   uds-config.yaml

   variables:
     core:
       VELERO_IRSA_ROLE_ARN: "arn:aws:iam::123456789012:role/velero-backup-role"

   Caution

   Replace <your-bucket-name> and <your-region> with your actual values directly in the bundle YAML. Unlike the static-credential approach, these cannot be set in uds-config.yaml because the entire configuration.backupStorageLocation array must be overridden to remove the credential Secret reference incompatible with IRSA. Set s3ForcePathStyle: false for AWS S3; use true only for MinIO or other providers that require path-style access.

   Azure Blob Storage

   Override the Velero credentials and backup storage location to use Azure Blob Storage:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           velero:
             variables:
               - name: VELERO_AZURE_CLOUD_CREDENTIALS
                 path: credentials.secretContents.cloud
                 sensitive: true
             values:
               - path: configuration.backupStorageLocation
                 value:
                   - name: default
                     provider: azure
                     bucket: <your-container-name>
                     config:
                       storageAccount: <your-storage-account>
                       resourceGroup: <your-resource-group>
                       storageAccountKeyEnvVar: AZURE_STORAGE_ACCOUNT_ACCESS_KEY
                       subscriptionId: <your-subscription-id>

   uds-config.yaml

   variables:
     core:
       VELERO_AZURE_CLOUD_CREDENTIALS: |
         AZURE_STORAGE_ACCOUNT_ACCESS_KEY=<your-storage-account-access-key>
         AZURE_CLOUD_NAME=<your-cloud-name>

   Note

   The bucket field corresponds to the Azure Blob container name.

2. (Optional) Configure storage network egress

   By default, Velero’s network policy allows egress to any destination for storage connectivity. To restrict egress to a specific target, add the following overrides to your bundle using the uds-velero-config chart:

   Internal storage (in-cluster MinIO or similar):

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           uds-velero-config:
             values:
               - path: storage.internal.enabled
                 value: true
               - path: storage.internal.remoteSelector
                 value:
                   app: minio
               - path: storage.internal.remoteNamespace
                 value: "minio"

   CIDR-restricted (known IP range):

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           uds-velero-config:
             values:
               - path: storage.egressCidr
                 value: "10.0.0.0/8"

3. (Optional) Customize backup schedule and retention

   The default backup schedule runs daily at 03:00 UTC with a 10-day retention window. To customize these settings, add the following overrides to your bundle:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         velero:
           velero:
             values:
               # Run backups every 6 hours
               - path: schedules.udsbackup.schedule
                 value: "0 */6 * * *"
               # Retain backups for 30 days
               - path: schedules.udsbackup.template.ttl
                 value: "720h"

   Note

   The default schedule excludes kube-system and velero namespaces and includes cluster-scoped resources. These defaults apply unless explicitly overridden.

4. Create and deploy your bundle

   Combine all overrides from the steps above into a single bundle configuration, then create and deploy:

   uds create <path-to-bundle-dir>
   uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst

Verification

Confirm Velero is running and storage is connected:

# Velero pod is running
uds zarf tools kubectl get pods -n velero

# Backup storage location shows "Available"
uds zarf tools kubectl get backupstoragelocation -n velero

# Backup schedule exists with correct cron expression
uds zarf tools kubectl get schedule -n velero

Success criteria:

• Velero pod is Running
• BackupStorageLocation phase is Available
• Schedule velero-udsbackup exists with the expected cron expression

To confirm storage is working end-to-end, trigger a manual backup and verify it completes. See Perform a manual backup.

Troubleshooting

Problem: BackupStorageLocation shows “Unavailable”

Symptoms: The BSL phase is Unavailable and no backups are created.

Solution: Check Velero logs for storage connectivity errors:

uds zarf tools kubectl logs -n velero deploy/velero --tail=50

Common causes include incorrect bucket name or region, invalid credentials, and network policies blocking egress to the storage endpoint.

Problem: Velero pod crash-loops

Symptoms: The Velero pod repeatedly restarts.

Solution: Check pod logs for startup errors:

uds zarf tools kubectl logs -n velero deploy/velero --previous --tail=50

Common causes include malformed credential Secrets and missing required configuration values.

Related documentation

• Velero: Supported Storage Providers - full list of available storage plugins
• Velero: Backup Storage Locations - BSL configuration reference
• Velero Helm Chart - full list of upstream Helm values
• Backup & restore concepts - how Velero fits into UDS Core
• Configure Velero with IRSA on Amazon EKS - authenticate Velero to S3 using IAM Roles for Service Accounts instead of static access keys.
• Enable volume snapshots (AWS EBS) - capture persistent volume data using AWS EBS snapshots on EKS clusters.
• Enable volume snapshots (vSphere CSI) - capture persistent volume data using vSphere CSI snapshots on RKE2 clusters.
• Perform a manual backup - verify your scheduled backups are running and trigger a manual backup on demand.