Configure Velero Image Registry When Adding A Cluster

The image registry configured while adding a cluster is only used to install Velero components in that business cluster. It maps to Cluster.spec.veleroInstall.imageRegistry and affects Velero Deployment, Node Agent, plugin init containers, and helper images.

It does not rewrite business application images, and it does not copy application images to a target registry.

When To Configure It

Set the Velero image registry when:

• The business cluster cannot pull public images.
• Official Velero images must be mirrored to an internal registry.
• Customer environments only allow pulls from an approved Harbor or registry.
• The image registry requires username/password authentication.

If the business cluster can pull the default Velero images directly, this field can be left empty.

Meaning Of The Field

veleroInstall.imageRegistry is an image registry prefix. Do not include http:// or https://.

Example:

harbor.example.com/disaster

Testudo uses this prefix when generating Velero install values:

Component	Default image	Image after configuration
Velero	velero/velero:v1.17.0	harbor.example.com/disaster/velero:v1.17.0
AWS plugin	velero/velero-plugin-for-aws:v1.13.0	harbor.example.com/disaster/velero-plugin-for-aws:v1.13.0
kubectl helper	registry.example.com/disaster/kubectl:1.20.14	harbor.example.com/disaster/kubectl:1.20.14

Images must already exist in the target registry. Testudo only rewrites install-time image references; it does not mirror images.

Console Steps

Open Resource Configuration / Cluster Configuration, then click Add Cluster.

After entering cluster name, authentication method, and kubeconfig/token, fill Velero image registry only if the business cluster needs an internal registry:

• Registry prefix, for example harbor.example.com/disaster.
• Username, if authentication is required.
• Password, if authentication is required.

After saving, the server stores the registry credential in the management namespace. The operator syncs it to the business cluster velero namespace and references it when installing Velero.

API Example

When adding a cluster with kubeconfig:

{
  "name": "prod-a",
  "description": "production cluster A",
  "kubeConfig": "<base64-or-raw-kubeconfig>",
  "veleroInstall": {
    "imageRegistry": "harbor.example.com/disaster",
    "username": "registry-user",
    "password": "registry-password"
  }
}

If the registry does not require authentication:

{
  "name": "prod-a",
  "kubeConfig": "<base64-or-raw-kubeconfig>",
  "veleroInstall": {
    "imageRegistry": "harbor.example.com/disaster"
  }
}

Username and password must be provided together. imageRegistry must not include a URL scheme.

Verify After Registration

Check the Cluster resource:

kubectl get clusters.testudo.softcdata.com prod-a \
  -o jsonpath='{.spec.veleroInstall.imageRegistry}{"\n"}'

If authentication was configured, check the credential reference:

kubectl -n disaster-system get secret
kubectl get clusters.testudo.softcdata.com prod-a \
  -o jsonpath='{.spec.veleroInstall.registryCredentialSecretRef.name}{"\n"}'

Check the business cluster:

kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy,ds,pod
kubectl --kubeconfig prod-a.kubeconfig -n velero get secret
kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy velero \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy velero \
  -o jsonpath='{.spec.template.spec.imagePullSecrets}{"\n"}'

Expected result:

• Velero Deployment and Node Agent are running.
• Velero images use the configured registry prefix.
• If authentication is configured, the business cluster velero namespace has a pull secret such as velero-regcred-<cluster-name>.
• Velero Pods do not show ImagePullBackOff, ErrImagePull, or registry authentication failures.

Common Misunderstandings

Misunderstanding	Correct behavior
This registry rewrites application workload images	It only affects Velero installation images
Testudo mirrors images automatically	Images must be mirrored before cluster registration
This controls DataSync trafficless Pod image	Trafficless Pod image is configured separately through DataSync/restore policy
This is a Helm chart registry	No. It is only an image registry prefix used while installing Velero