Velero installation fails with "vSphere plugin is required to be specified via --plugins flag"

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

When attempting to install Velero for backup and restore operations using ./velero-vsphere install, the installation process fails immediately with the following CLI error:

An error occurred: vSphere plugin is required to be specified via --plugins flag

Environment

VMware Cloud Foundation (VCF) 9.x

Velero

VMware vSphere Kubernetes Service

Cause

This issue occurs due to two primary factors:

1. Incorrect Target Context: The ./velero-vsphere install command was executed against the Supervisor cluster context instead of the target VKS Guest Cluster context. In VCF 9.1, Velero operates natively as a Supervisor Service, and workloads residing inside Guest Clusters must be configured within the Guest Cluster's own kubectl context.
2. Missing Mandatory Plugin Flag: When installing Velero via CLI for vSphere-backed workloads, both the object storage plugin (e.g., AWS S3) and the vSphere plugin (vsphere-plugin-for-velero) must be explicitly declared using the --plugins parameter.

Resolution

Prerequisite

Ensure you have active kubectl access and that your local environment contains your S3 object storage credential file (e.g., s3-credentials).

Step 1: Switch to the Target Guest Cluster Context

            1.List all available contexts in your local kubeconfig:

                 kubectl config get-contexts

            2. Set the active context directly to your target Guest Cluster (TKC):

                 kubectl config use-context <GUEST_CLUSTER_NAME>

Step 2: Create the Kubernetes Cloud Credentials Secret

            1. Create the dedicated Velero namespace:

        kubectl create namespace $VELERO_NAMESPACE

            2. Create the secret containing your S3 storage access keys:

        kubectl create secret generic cloud-credentials \ --namespace $VELERO_NAMESPACE \ --from-file cloud=./s3-credentials                                                  

 

 

Step 3: Execute the Velero Installation

Run the standard ./velero install command, explicitly declaring both the AWS and vSphere plugins:

./velero install \

  --provider aws \

  --plugins velero/velero-plugin-for-aws:v1.9.0,vsphere-plugin-for-velero:v1.5.0 \

  --bucket $BUCKET \

  --secret-file ./s3-credentials \

  --backup-location-config region=$REGION,s3Url=$S3URL,s3ForcePathStyle="true" \

  --use-node-agent \

  --namespace $VELERO_NAMESPACE

Note: If deploying within an air-gapped environment or using a private image registry, append --image $VELERO_IMAGE to the installation command above.

Verification

Validate that the installation was successful by running the following commands against the Guest Cluster:

1. Verify Velero Custom Resource Definitions (CRDs):

    kubectl get crd | grep velero

2. Check Velero Pod Health:

    kubectl get pods -n $VELERO_NAMESPACE

3. Verify Backup Storage Location Status:

        ./velero backup-location get -n $VELERO_NAMESPACE

Expected Output: The storage location status should reflect Available.