From 03d1960d4267d8783e7c2fa127b21f614a12ae62 Mon Sep 17 00:00:00 2001 From: Andrey Kolkov Date: Tue, 5 May 2026 11:32:11 +0400 Subject: [PATCH] feat(docs): added guide about backup workloads in managed k8s Signed-off-by: Andrey Kolkov --- .../kubernetes/backups-with-velero-addon.md | 175 ++++++++++++++++++ .../kubernetes/backups-with-velero-addon.md | 175 ++++++++++++++++++ 2 files changed, 350 insertions(+) create mode 100644 content/en/docs/next/kubernetes/backups-with-velero-addon.md create mode 100644 content/en/docs/v1.3/kubernetes/backups-with-velero-addon.md diff --git a/content/en/docs/next/kubernetes/backups-with-velero-addon.md b/content/en/docs/next/kubernetes/backups-with-velero-addon.md new file mode 100644 index 00000000..3a6db7ea --- /dev/null +++ b/content/en/docs/next/kubernetes/backups-with-velero-addon.md @@ -0,0 +1,175 @@ +--- +title: "Backups with the Velero addon" +linkTitle: "Backups with the Velero addon" +description: "Enable the Velero addon in a tenant Kubernetes cluster, point it at a SeaweedFS bucket, and back up and restore workloads." +weight: 60 +--- + +The `velero` addon of the [Managed Kubernetes]({{% ref "/docs/next/kubernetes" %}}) application installs [Velero](https://velero.io/) inside a tenant Kubernetes cluster. Combined with a tenant [Bucket]({{% ref "/docs/next/operations/services/object-storage/buckets" %}}), it lets tenant users back up workloads to S3 and restore them later. + +{{% alert color="info" %}} +This guide is for the **tenant-side** Velero addon, which runs inside a tenant Kubernetes cluster and is operated by the tenant user. + +For the platform-level Velero used by cluster administrators to back up `VMInstance`/`VMDisk` resources from the management cluster, see [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}). +{{% /alert %}} + +## What the addon installs + +When `spec.addons.velero.enabled` is `true` on a `Kubernetes` resource, Cozystack deploys Velero into the `cozy-velero` namespace of the tenant cluster. The chart wraps the upstream `vmware-tanzu/velero` chart as a subchart and pre-configures the AWS S3 plugin, the KubeVirt plugin, the node agent (file-system backup), and the CSI feature (`features: EnableCSI`). The `kubevirt-snapshots` `VolumeSnapshotClass` (driver `csi.kubevirt.io`) ships in every tenant cluster and is labelled for Velero's CSI plugin, so volume snapshots work out of the box. + +The default install does not create a `BackupStorageLocation`. You provide one through `valuesOverride` — typically pointing at a SeaweedFS `Bucket` that lives in your tenant. + +## Prerequisites + +- SeaweedFS is enabled on your tenant (`spec.seaweedfs: true`). See [Object Storage]({{% ref "/docs/next/operations/services/object-storage" %}}). +- The [`velero` CLI](https://velero.io/docs/v1.17/basic-install/#install-the-cli) is installed locally. +- You have admin access to the tenant namespace in the management cluster (to create `Bucket` and `Kubernetes` resources) and can fetch the resulting kubeconfig. + +## 1. Create a bucket for backups + +```yaml +apiVersion: apps.cozystack.io/v1alpha1 +kind: Bucket +metadata: + name: velero-backups + namespace: tenant-example +spec: + users: + velero: {} +``` + +Cozystack creates a credentials secret named `bucket---credentials` with `accessKey`, `secretKey`, `endpoint`, and `bucketName` fields. Read the values you will plug into the addon configuration: + +```bash +NS=tenant-example +SECRET=bucket-velero-backups-velero-credentials + +BUCKET_NAME=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.bucketName}' | base64 -d) +ACCESS_KEY=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.accessKey}' | base64 -d) +SECRET_KEY=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.secretKey}' | base64 -d) +ENDPOINT=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.endpoint}' | base64 -d) +echo "$BUCKET_NAME / https://$ENDPOINT" +``` + +`endpoint` is a hostname only — Velero needs `https://$ENDPOINT` as the S3 URL. + +## 2. Deploy a tenant cluster with the Velero addon + +{{% alert color="warning" %}} +The addon chart embeds the upstream Velero chart **as a subchart under the `velero` key**. Override values **must** be nested under `velero:` — placing them at the top level (e.g. `valuesOverride.configuration.backupStorageLocation`) is silently ignored. +{{% /alert %}} + +Render and apply a `Kubernetes` manifest using the values from the previous step: + +```bash +cat < my-cluster-kubeconfig +export KUBECONFIG=$PWD/my-cluster-kubeconfig +``` + +The remaining steps run against the **tenant** cluster. + +## 3. Verify Velero is running + +```bash +kubectl -n cozy-velero get deploy +velero -n cozy-velero backup-location get +``` + +Expected output: + +```text +NAME STATUS PROVIDER BUCKET ACCESS MODE DEFAULT +default Available aws bucket-91bbb59f-30ba-46fe-9a44-535d8332a464 ReadWrite true +``` + +`STATUS: Available` means Velero successfully connected to the bucket. + +## 4. Back up a namespace + +Create a sample workload (skip if you already have one to back up): + +```bash +kubectl create namespace demo +kubectl -n demo create configmap demo-cm \ + --from-literal=marker=backup-restore-validation +``` + +Take the backup: + +```bash +velero -n cozy-velero backup create demo-1 \ + --include-namespaces demo --snapshot-move-data +velero -n cozy-velero backup describe demo-1 --details +``` + +`--snapshot-move-data` uploads CSI snapshot data to the bucket so the backup is self-contained — restores no longer need access to the source PVs. + +Wait until `Phase: Completed`. + +## 5. Restore from the backup + +Simulate a loss by deleting the namespace, then restore it from the backup: + +```bash +kubectl delete namespace demo +velero -n cozy-velero restore create demo-1-restore \ + --from-backup demo-1 +velero -n cozy-velero restore describe demo-1-restore --details +``` + +When the restore reaches `Phase: Completed`, the namespace and its objects are recreated. Verify: + +```bash +kubectl -n demo get all,configmaps +``` + +The same pattern restores into a **different** tenant Kubernetes cluster as well — point a second cluster at the same bucket with an identical `addons.velero.valuesOverride`, and `velero backup get` in the second cluster will see `demo-1` once the bucket sync ticks (default interval one minute). See the upstream [migration scenario](https://velero.io/docs/v1.17/migration-case/) for cross-cluster considerations. + +## Related + +- [Managed Kubernetes — `addons.velero` parameters]({{% ref "/docs/next/kubernetes#parameters" %}}) +- [Buckets and Users]({{% ref "/docs/next/operations/services/object-storage/buckets" %}}) +- [Velero Backup Configuration (platform admin)]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}) diff --git a/content/en/docs/v1.3/kubernetes/backups-with-velero-addon.md b/content/en/docs/v1.3/kubernetes/backups-with-velero-addon.md new file mode 100644 index 00000000..bd40a53c --- /dev/null +++ b/content/en/docs/v1.3/kubernetes/backups-with-velero-addon.md @@ -0,0 +1,175 @@ +--- +title: "Backups with the Velero addon" +linkTitle: "Backups with the Velero addon" +description: "Enable the Velero addon in a tenant Kubernetes cluster, point it at a SeaweedFS bucket, and back up and restore workloads." +weight: 60 +--- + +The `velero` addon of the [Managed Kubernetes]({{% ref "/docs/v1.3/kubernetes" %}}) application installs [Velero](https://velero.io/) inside a tenant Kubernetes cluster. Combined with a tenant [Bucket]({{% ref "/docs/v1.3/operations/services/object-storage/buckets" %}}), it lets tenant users back up workloads to S3 and restore them later. + +{{% alert color="info" %}} +This guide is for the **tenant-side** Velero addon, which runs inside a tenant Kubernetes cluster and is operated by the tenant user. + +For the platform-level Velero used by cluster administrators to back up `VMInstance`/`VMDisk` resources from the management cluster, see [Velero Backup Configuration]({{% ref "/docs/v1.3/operations/services/velero-backup-configuration" %}}). +{{% /alert %}} + +## What the addon installs + +When `spec.addons.velero.enabled` is `true` on a `Kubernetes` resource, Cozystack deploys Velero into the `cozy-velero` namespace of the tenant cluster. The chart wraps the upstream `vmware-tanzu/velero` chart as a subchart and pre-configures the AWS S3 plugin, the KubeVirt plugin, the node agent (file-system backup), and the CSI feature (`features: EnableCSI`). The `kubevirt-snapshots` `VolumeSnapshotClass` (driver `csi.kubevirt.io`) ships in every tenant cluster and is labelled for Velero's CSI plugin, so volume snapshots work out of the box. + +The default install does not create a `BackupStorageLocation`. You provide one through `valuesOverride` — typically pointing at a SeaweedFS `Bucket` that lives in your tenant. + +## Prerequisites + +- SeaweedFS is enabled on your tenant (`spec.seaweedfs: true`). See [Object Storage]({{% ref "/docs/v1.3/operations/services/object-storage" %}}). +- The [`velero` CLI](https://velero.io/docs/v1.17/basic-install/#install-the-cli) is installed locally. +- You have admin access to the tenant namespace in the management cluster (to create `Bucket` and `Kubernetes` resources) and can fetch the resulting kubeconfig. + +## 1. Create a bucket for backups + +```yaml +apiVersion: apps.cozystack.io/v1alpha1 +kind: Bucket +metadata: + name: velero-backups + namespace: tenant-example +spec: + users: + velero: {} +``` + +Cozystack creates a credentials secret named `bucket---credentials` with `accessKey`, `secretKey`, `endpoint`, and `bucketName` fields. Read the values you will plug into the addon configuration: + +```bash +NS=tenant-example +SECRET=bucket-velero-backups-velero-credentials + +BUCKET_NAME=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.bucketName}' | base64 -d) +ACCESS_KEY=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.accessKey}' | base64 -d) +SECRET_KEY=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.secretKey}' | base64 -d) +ENDPOINT=$(kubectl get secret "$SECRET" -n "$NS" -o jsonpath='{.data.endpoint}' | base64 -d) +echo "$BUCKET_NAME / https://$ENDPOINT" +``` + +`endpoint` is a hostname only — Velero needs `https://$ENDPOINT` as the S3 URL. + +## 2. Deploy a tenant cluster with the Velero addon + +{{% alert color="warning" %}} +The addon chart embeds the upstream Velero chart **as a subchart under the `velero` key**. Override values **must** be nested under `velero:` — placing them at the top level (e.g. `valuesOverride.configuration.backupStorageLocation`) is silently ignored. +{{% /alert %}} + +Render and apply a `Kubernetes` manifest using the values from the previous step: + +```bash +cat < my-cluster-kubeconfig +export KUBECONFIG=$PWD/my-cluster-kubeconfig +``` + +The remaining steps run against the **tenant** cluster. + +## 3. Verify Velero is running + +```bash +kubectl -n cozy-velero get deploy +velero -n cozy-velero backup-location get +``` + +Expected output: + +```text +NAME STATUS PROVIDER BUCKET ACCESS MODE DEFAULT +default Available aws bucket-91bbb59f-30ba-46fe-9a44-535d8332a464 ReadWrite true +``` + +`STATUS: Available` means Velero successfully connected to the bucket. + +## 4. Back up a namespace + +Create a sample workload (skip if you already have one to back up): + +```bash +kubectl create namespace demo +kubectl -n demo create configmap demo-cm \ + --from-literal=marker=backup-restore-validation +``` + +Take the backup: + +```bash +velero -n cozy-velero backup create demo-1 \ + --include-namespaces demo --snapshot-move-data +velero -n cozy-velero backup describe demo-1 --details +``` + +`--snapshot-move-data` uploads CSI snapshot data to the bucket so the backup is self-contained — restores no longer need access to the source PVs. + +Wait until `Phase: Completed`. + +## 5. Restore from the backup + +Simulate a loss by deleting the namespace, then restore it from the backup: + +```bash +kubectl delete namespace demo +velero -n cozy-velero restore create \ + --from-backup demo-1 +velero -n cozy-velero restore describe demo-1 --details +``` + +When the restore reaches `Phase: Completed`, the namespace and its objects are recreated. Verify: + +```bash +kubectl -n demo get all,configmaps +``` + +The same pattern restores into a **different** tenant Kubernetes cluster as well — point a second cluster at the same bucket with an identical `addons.velero.valuesOverride`, and `velero backup get` in the second cluster will see `demo-1` once the bucket sync ticks (default interval one minute). See the upstream [migration scenario](https://velero.io/docs/v1.17/migration-case/) for cross-cluster considerations. + +## Related + +- [Managed Kubernetes — `addons.velero` parameters]({{% ref "/docs/v1.3/kubernetes#parameters" %}}) +- [Buckets and Users]({{% ref "/docs/v1.3/operations/services/object-storage/buckets" %}}) +- [Velero Backup Configuration (platform admin)]({{% ref "/docs/v1.3/operations/services/velero-backup-configuration" %}})