Velero Plugin For JDCloud

Seamless Kubernetes Backup & Restore with JDCloud Object Storage

🐛 Report a Bug · ✨ Request a Feature · 💬 Ask a Question

📑 Table of Contents

Overview
Features
Prerequisites
Deployment
Troubleshooting
Contributors
Star History

Overview

This plugin is used for saving and retrieving backup data on JDCloud OSS as an object storage plugin. The backup includes metadata files of Kubernetes resources and CSI objects, as well as the progress of asynchronous operations. It is also used to store result data from backups and restores, including log files, warning/error files, and more.

Features

JDCloud OSS Integration: Seamless integration with JDCloud Object Storage Service
Kubernetes Backup: Full support for Kubernetes resource backup and restore
CSI Support: Compatible with Container Storage Interface (CSI) snapshots
Asynchronous Operations: Handles long-running backup and restore operations
Multi-namespace Support: Backup and restore across multiple Kubernetes namespaces
Secure Credentials: Secure handling of cloud provider credentials

Prerequisites

JKE Cluster or other Kubernetes Cluster
Git
Docker
Docker-buildx
Velero CLI (v1.17.1 or later)

Deployment

Step 1: Prepare Environment

Log in to a node in the JKE Cluster or other Kubernetes Cluster and connect to the cluster.
Install the Velero CLI tool.

Download the appropriate Velero CLI binary for your architecture:
- Linux AMD64: velero-v1.17.1-linux-amd64.tar.gz
- Other architectures: Visit the official Velero releases page to find binaries for ARM64, macOS, or Windows
- Upload the downloaded file to your Kubernetes node
Extract Velero:
```
tar -xvf velero-v1.17.1-linux-amd64.tar.gz
sudo mv velero-v1.17.1-linux-amd64/velero /usr/local/bin/velero
```

Step 2: Get Plugin Image

You have two options to obtain the plugin image:

Option A: Use Pre-built Image (Recommended)

Pull the official image from Docker Hub:

docker pull jdopensource/velero-plugin-for-jdcloud:dev-v1.0.0

💡 Note: Check the Docker Hub tags for the latest version.

Option B: Build from Source

Clone the Velero plugin repository:

git clone https://github.com/jd-opensource/velero-plugin-for-jdcloud.git
cd velero-plugin-for-jdcloud

Build the Docker image:
```
make docker-build IMAGE="my.hub.com/base/velero-plugin-for-jdcloud" VERSION="v1.0.0"
```
🔧 Customization: Replace my.hub.com/base/velero-plugin-for-jdcloud with your preferred registry and repository name.

Step 3: Configure JDCloud OSS

Create a new OSS bucket:
- Log in to JDCloud OSS Console
- Create a new bucket in your preferred region
- Ensure the bucket is empty (no existing directories or files)

Create a credentials configuration file:

mkdir -p /home/velero
vi /home/velero/credentials-velero

Add the following content:

JDCLOUD_OSS_ACCESS_KEY=<Your Access Key>
JDCLOUD_OSS_SECRET_KEY=<Your Secret Key>

Step 4: Install Velero

Install Velero using the CLI tool:

velero install \
    --provider jdcloud.com/jdcloud \
    --plugins my.hub.com/base/velero-plugin-for-jdcloud:v1.0.0 \
    --bucket <Your Bucket> \
    --prefix "velero-backups/" \
    --secret-file /home/velero/credentials-velero \
    --backup-location-config \
      endpoint=<Your Endpoint>,region="cn-north-1",s3ForcePathStyle="true",bucket="<Your Bucket>",profile="default",insecureSkipTLSVerify="true",credentialsFile="/credentials/cloud"

Replace the following placeholders:

<Your Bucket>: Your JDCloud OSS bucket name
<Your Endpoint>: Your JDCloud OSS endpoint (e.g., https://s3.cn-north-1.jdcloud-oss.com)

📝 Configuration Notes:

Private Registry: If using a private container registry, ensure your Kubernetes cluster can pull images from it. You may need to configure image pull secrets.

Endpoint Format: Use the correct JDCloud OSS endpoint format, typically https://s3.<region>.jdcloud-oss.com

Region Values: Common regions include cn-north-1, cn-south-1, cn-east-1. Check JDCloud documentation for your specific region.

Bucket Naming: Bucket names must be globally unique across JDCloud OSS

Prefix: The prefix velero-backups/ helps organize backup files in your bucket

Step 5: Verify Installation

Check the storage location status:

velero backup-location get

The expected output:

NAME      PROVIDER              BUCKET/PREFIX                   PHASE       LAST VALIDATED                  ACCESS MODE   DEFAULT
default   jdcloud.com/jdcloud   <Your Bucket>/<Your prefix>     Available   2026-01-04 15:48:35 +0800 CST   ReadWrite     true

Available indicates a successful installation.

Step 6: Create Your First Backup

Create a test backup of all resources in the default namespace:

velero backup create default-backup \
  --include-namespaces default \
  --wait

The expected output:

Backup request "default-backup" submitted successfully.
Waiting for backup to complete. You may safely press ctrl-c to stop waiting - your backup will continue in the background.
..........
Backup completed with status: Completed. You may check for more information using the commands `velero backup describe default-backup` and `velero backup logs default-backup`.

Check backup status:

velero backup get

The expected output:

NAME             STATUS      ERRORS   WARNINGS   CREATED                         EXPIRES   STORAGE LOCATION   SELECTOR
default-backup   Completed   0        0          2026-01-04 15:52:39 +0800 CST   29d       default            <none>

Status meanings:

Completed: Backup finished successfully
InProgress: Backup is still running
Failed: Backup encountered errors

View backup details:

# Get detailed information about the backup
velero backup describe default-backup --details

# View backup logs for troubleshooting
velero backup logs default-backup

Step 7: Restore from Backup

Optional - Test restore: Delete resources in the default namespace to test restore functionality:
```
kubectl delete namespace default
kubectl create namespace default
```

Set backup location to read-only mode (recommended during restore):

kubectl patch backupstoragelocation default \
    --namespace velero \
    --type merge \
    --patch '{"spec":{"accessMode":"ReadOnly"}}'

Restore from backup:

velero restore create restore-default \
  --from-backup default-backup \
  --wait

The expected output:

Restore request "restore-default" submitted successfully.
Waiting for restore to complete. You may safely press ctrl-c to stop waiting - your restore will continue in the background.
......
Restore completed with status: Completed. You may check for more information using the commands `velero restore describe restore-default` and `velero restore logs restore-default`.

Check restore status:

velero restore get

The expected output:

NAME              BACKUP           STATUS      STARTED                         COMPLETED                       ERRORS   WARNINGS   CREATED                         SELECTOR
restore-default   default-backup   Completed   2026-01-04 15:56:38 +0800 CST   2026-01-04 15:56:44 +0800 CST   0        3          2026-01-04 15:56:38 +0800 CST   <none>

Status meanings:

Completed: Restore finished successfully
InProgress: Restore is still running
Failed: Restore encountered errors

View restore details:

velero restore describe restore-default
velero restore logs restore-default

Restore backup location to read-write mode:

kubectl patch backupstoragelocation default \
    --namespace velero \
    --type merge \
    --patch '{"spec":{"accessMode":"ReadWrite"}}'

Step 8: Manage Backups

Delete a Backup

velero backup delete default-backup

⚠️ Warning: This will permanently delete the backup from storage. Ensure you have other backups or don't need this data.

The expected output:

Are you sure you want to continue (Y/N)? Y
Request to delete backup "default-backup" submitted successfully.
The backup will be fully deleted after all associated data (disk snapshots, backup files, restores) are removed.

List All Backups

velero backup get

Uninstall Velero

If you need to completely remove Velero from your cluster:

# Delete Velero namespace and resources
kubectl delete namespace velero
kubectl delete clusterrolebinding velero

# Delete Velero CRDs
kubectl delete crds -l component=velero

# Optional: Clean up remaining resources
kubectl delete clusterroles -l component=velero

Troubleshooting

Common Issues and Solutions

1. Backup Location Not Available

Symptoms: velero backup-location get shows status as Unavailable

Solutions:

Check credentials file permissions:

ls -la /home/velero/credentials-velero
chmod 600 /home/velero/credentials-velero

Verify JDCloud OSS credentials are correct and active
Ensure the bucket exists and is accessible from your cluster
Check network connectivity to JDCloud OSS endpoint

2. Image Pull Errors

Symptoms: Velero pods stuck in ImagePullBackOff or ErrImagePull

Solutions:

If using a private registry, configure image pull secrets:

kubectl create secret docker-registry regcred \
  --docker-server=<your-registry-server> \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  --docker-email=<your-email> \
  -n velero

Verify the image name and tag are correct
Check if the image exists in the registry

3. Permission Issues

Symptoms: Backup/restore operations fail with permission errors

Solutions:

Ensure Velero service account has necessary RBAC permissions
Check if the cluster has sufficient CPU/memory resources
Verify the node has access to the JDCloud OSS endpoint

4. Backup/Restore Failures

Symptoms: Operations fail with various error messages

Debugging Steps:

Check Velero pod logs:

kubectl logs -n velero deployment/velero

Check specific backup/restore logs:

velero backup logs <backup-name>
velero restore logs <restore-name>

Describe the resource for detailed status:

velero backup describe <backup-name> --details

Getting Help

📖 Documentation: Check the official Velero documentation
🐛 Report bugs: Create a bug report
✨ Request features: Request a new feature
💬 Community support: Join discussions

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
changelogs		changelogs
docs/images		docs/images
examples		examples
hack		hack
velero-plugin-for-jdcloud		velero-plugin-for-jdcloud
vendor		vendor
.dockerignore		.dockerignore
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
tilt-provider.json		tilt-provider.json

Folders and files

Latest commit

History

Repository files navigation

Velero Plugin For JDCloud