diff --git a/docs/enterprise/snapshots-config-workflow.md b/docs/enterprise/snapshots-config-workflow.md index 8914cbee94..e5ddc020a4 100644 --- a/docs/enterprise/snapshots-config-workflow.md +++ b/docs/enterprise/snapshots-config-workflow.md @@ -47,4 +47,4 @@ After you configure a storage destination, you can create a backup. See [Creatin ## Additional Resources * [Restoring Full Backups](snapshots-restoring-full) -* [Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +* [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) diff --git a/docs/enterprise/snapshots-configuring-hostpath.md b/docs/enterprise/snapshots-configuring-hostpath.md index bfda1fe88a..2beb9a6e5a 100644 --- a/docs/enterprise/snapshots-configuring-hostpath.md +++ b/docs/enterprise/snapshots-configuring-hostpath.md @@ -25,7 +25,7 @@ This topic describes how to install Velero and configure a host path as your sto Complete the following items before you perform this task: -* Review the limitations and considerations. See [Limitations and Considerations](snapshots-understanding#limitations-and-considerations) in _About Backup and Restore_. +* Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Installing the Velero CLI](snapshots-velero-cli-installing). ## Install Velero and Configure Host Path Storage in Online Environments @@ -118,4 +118,4 @@ To install Velero and configure host path storage for existing clusters: ## Additional Resources -* [Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +* [Troubleshooting Snapshots](/enterprise/snapshots-troubleshooting-backup-restore) diff --git a/docs/enterprise/snapshots-configuring-nfs.md b/docs/enterprise/snapshots-configuring-nfs.md index bfd58aaf03..209a166991 100644 --- a/docs/enterprise/snapshots-configuring-nfs.md +++ b/docs/enterprise/snapshots-configuring-nfs.md @@ -26,7 +26,7 @@ Configuring an NFS server as a snapshots storage destination has the following r Complete the following items before you perform this task: -* Review the limitations and considerations. See [Limitations and Considerations](snapshots-understanding#limitations-and-considerations) in _About Backup and Restore_. +* Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Installing the Velero CLI](snapshots-velero-cli-installing). ## Install Velero and Configure NFS Storage in Online Environments @@ -121,4 +121,4 @@ To install Velero and configure NFS storage for existing clusters: ## Additional Resources -* [Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +* [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) diff --git a/docs/enterprise/snapshots-creating.md b/docs/enterprise/snapshots-creating.md index a99c06f5e7..40fd9685a4 100644 --- a/docs/enterprise/snapshots-creating.md +++ b/docs/enterprise/snapshots-creating.md @@ -97,4 +97,4 @@ To schedule automatic backups in the Admin Console: The retention policy applies to all backups, including both automatically- and manually-created backups. Changing the retention policy affects only backups created after the time of the change. ## Additional Resources -[Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +[Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) diff --git a/docs/enterprise/snapshots-restoring-full.mdx b/docs/enterprise/snapshots-restoring-full.mdx index c2d189386c..aae3503307 100644 --- a/docs/enterprise/snapshots-restoring-full.mdx +++ b/docs/enterprise/snapshots-restoring-full.mdx @@ -26,7 +26,7 @@ The following limitations apply to restoring from backups using snapshots: * * -For a full list of limitations and considerations related to the snapshots feature, see [Limitations and Considerations](snapshots-understanding#limitations-and-considerations) in _About Backup and Restore_. +For a full list of limitations and considerations related to the snapshots feature, see [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. ## Restore From a Full Backup Using the CLI {#full-cli} @@ -158,4 +158,4 @@ To restore an application from a partial backup: ## Additional Resources -[Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) \ No newline at end of file +[Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) \ No newline at end of file diff --git a/docs/enterprise/snapshots-storage-destinations.md b/docs/enterprise/snapshots-storage-destinations.md index bb4a21dda5..55df7f9a35 100644 --- a/docs/enterprise/snapshots-storage-destinations.md +++ b/docs/enterprise/snapshots-storage-destinations.md @@ -16,7 +16,7 @@ To configure host path or NFS as a storage destination, see [Configuring a Host Complete the following items before you install Velero and configure a storage destination: -* Review the limitations and considerations. See [Limitations and Considerations](snapshots-understanding#limitations-and-considerations) in _About Backup and Restore_. +* Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Installing the Velero CLI](snapshots-velero-cli-installing). ## Configure AWS Storage for Online Environments @@ -188,4 +188,4 @@ If no Velero installation is detected, instructions are displayed to install Vel ## Additional Resources -* [Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +* [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) diff --git a/docs/enterprise/snapshots-troubleshooting-backup-restore.md b/docs/enterprise/snapshots-troubleshooting-backup-restore.md index 0f8c581b67..78e5728723 100644 --- a/docs/enterprise/snapshots-troubleshooting-backup-restore.md +++ b/docs/enterprise/snapshots-troubleshooting-backup-restore.md @@ -1,6 +1,6 @@ import NodeAgentMemLimit from "../partials/snapshots/_node-agent-mem-limit.mdx" -# Troubleshooting Backup and Restore +# Troubleshooting Snapshots When a snapshot fails, a support bundle will be collected and stored automatically. Because this is a point-in-time collection of all logs and system state at the time of the failed snapshot, this is a good place to view the logs. @@ -160,7 +160,7 @@ There are file changes between Restic's initial scan of the volume and during th To resolve this issue, do one of the following: -* Use [Snapshot Hooks](https://docs.replicated.com/vendor/snapshots-hooks) to export data to an [EmptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume and include that in the backup instead of the primary PVC volume. +* Use [hooks](/vendor/snapshots-hooks) to export data to an [EmptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume and include that in the backup instead of the primary PVC volume. See [Configuring Backup and Restore Hooks for Snapshots](/vendor/snapshots-hooks). * Freeze the file system to ensure all pending disk I/O operations have completed prior to taking a snapshot. For more information, see [Hook Example with fsfreeze](https://velero.io/docs/main/backup-hooks/#hook-example-with-fsfreeze) in the Velero documentation. diff --git a/docs/enterprise/snapshots-velero-cli-installing.md b/docs/enterprise/snapshots-velero-cli-installing.md index bb0a7b2c8d..0138979734 100644 --- a/docs/enterprise/snapshots-velero-cli-installing.md +++ b/docs/enterprise/snapshots-velero-cli-installing.md @@ -15,7 +15,7 @@ To install the Velero CLI in an online cluster: - (Embedded kURL cluster) Run an SSH command to access and authenticate to your cluster node. - (Existing cluster) Open a terminal in the environment that you manage the cluster from, which can be a local machine that has kubectl installed. -1. Check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although earlier versions of Velero are supported, Replicated recommends using the latest supported version. For more information about supported versions, see [Velero Version Compatibility](snapshots-understanding#velero-version-compatibility) in _About Backup and Restore_. +1. Check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although earlier versions of Velero are supported, Replicated recommends using the latest supported version. For more information about supported versions, see [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility). Note the version number for the next step. @@ -55,7 +55,7 @@ To install the Velero CLI in an online cluster: To install the Velero CLI in an air gapped cluster: -1. From a computer with internet access, check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although earlier versions of Velero are supported, Replicated recommends using the latest [supported version](/enterprise/snapshots-understanding#velero-version-compatibility). +1. From a computer with internet access, check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although earlier versions of Velero are supported, Replicated recommends using the latest supported version. See [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility). Note the version number for the next step. diff --git a/docs/enterprise/snapshots-velero-installing-config.mdx b/docs/enterprise/snapshots-velero-installing-config.mdx index 9d4e859459..160c098749 100644 --- a/docs/enterprise/snapshots-velero-installing-config.mdx +++ b/docs/enterprise/snapshots-velero-installing-config.mdx @@ -37,4 +37,4 @@ Velero sets default limits for the velero Pod and the node-agent (restic) Pod du ## Additional Resources -* [Troubleshooting Backup and Restore](snapshots-troubleshooting-backup-restore) +* [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) diff --git a/docs/partials/snapshots/_limitation-cli-restores.mdx b/docs/partials/snapshots/_limitation-cli-restores.mdx index 27d6a0b778..fea84a67b8 100644 --- a/docs/partials/snapshots/_limitation-cli-restores.mdx +++ b/docs/partials/snapshots/_limitation-cli-restores.mdx @@ -1 +1 @@ -Only full backups can be restored using the KOTS CLI. To restore an application from a partial backup, use the Admin Console. See [Restore the Application Only Using the Admin Console](snapshots-restoring-full#admin-console). \ No newline at end of file +Only full backups can be restored using the KOTS CLI. To restore an application from a partial backup, use the Admin Console. See [Restore the Application Only Using the Admin Console](/enterprise/snapshots-restoring-full#admin-console). \ No newline at end of file diff --git a/docs/reference/custom-resource-backup.md b/docs/reference/custom-resource-backup.md index 7f159635b0..a9939d85ac 100644 --- a/docs/reference/custom-resource-backup.md +++ b/docs/reference/custom-resource-backup.md @@ -1,22 +1,14 @@ -# Velero Backup Custom Resource +# Velero Backup Resource for Snapshots -The Backup custom resource enables the Replicated snapshots backup and restore feature. The backend of this feature uses the Velero open source project to back up Kubernetes manifests and persistent volumes. +This topic provides information about the supported fields in the Velero Backup resource for the Replicated KOTS snapshots feature. -Add a Backup custom resource (`kind: Backup`, `apiVersion: velero.io/v1`) to your release and configure it as needed. A Backup custom resource is required for each application that you deploy. +## Overview -You must add annotations for each volume that you want to back up. For more information about configuring backups, see [Configuring Backups](/vendor/snapshots-configuring-backups). - -The Backup custom resource also supports optional resource installations so that the feature can be dynamically enabled based on a license field or a config option. For more information, see [Conditionally Including or Excluding Resources](/vendor/packaging-include-resources). - -Full backups are recommended because they give the flexibility of restoring full data, the application only, or the KOTS Admin Console only. For an example of a full backup and a list of the supported fields, see [Example](#example) and [Fields](#fields). - -Partial backups (application only) are supported but not recommended. For partial backups, you can use all of the fields that Velero supports. For information about the supported fields for partial backups, see [Backups](https://velero.io/docs/v1.10/api-types/backup/) in the Velero documentation. +The Velero Backup custom resource enables the KOTS snapshots backup and restore feature. The backend of this feature uses the Velero open source project to back up Kubernetes manifests and persistent volumes. ## Example -The following example shows the supported fields for a full backup. - -The `annotations` field shows that `pvc-volume` is the only volume included in the backup. +The following shows an example of the Velero Backup resource: ```yaml apiVersion: velero.io/v1 @@ -24,15 +16,13 @@ kind: Backup metadata: name: backup annotations: + # `pvc-volume` will be the only volume included in the backup backup.velero.io/backup-volumes: pvc-volume spec: includedNamespaces: - '*' excludedNamespaces: - some-namespace - orLabelSelectors: - - matchLabels: - app: my-app orderedResources: pods: mysql/mysql-cluster-replica-0,mysql/mysql-cluster-replica-1 persistentvolumes: pvc-12345,pvc-67890 @@ -61,17 +51,19 @@ spec: - -a onError: Fail timeout: 10s - post: + post: [] ``` -## Fields +## Supported Fields for Full Backups with Snapshots {#fields} + +For partial backups with the snapshots feature, you can use all of the fields that Velero supports. See [Backups](https://velero.io/docs/v1.10/api-types/backup/) in the Velero documentation. -The following Velero fields are supported for full backups, as shown in the previous example: +However, not all fields are supported for full backups. The table below lists the fields that are supported for full backups with snapshots: - - + + @@ -81,10 +73,6 @@ The following Velero fields are supported for full backups, as shown in the prev - - - - @@ -98,66 +86,66 @@ The following Velero fields are supported for full backups, as shown in the prev - + - + - + - + - + - + - + - + - + - + - + - + - + - +
Field NameDescriptionField NameDescription
includedNamespacesexcludedNamespaces (Optional) Specifies an array of namespaces to exclude from the backup.
orLabelSelectors(Optional) A list of metav1.LabelSelector to filter with when adding individual objects to the backup. If multiple are provided, they will be joined by the OR operator.
orderedResources (Optional) Specifies the order of the resources to collect during the backup process. This is a map that uses a key as the plural resource. Each resource name has the format NAMESPACE/OBJECTNAME. The object names are a comma delimited list. For cluster resources, use OBJECTNAME only.(Optional) Specifies the actions to perform at different times during a backup. The only supported hook is executing a command in a container in a pod (uses the pod exec API). Supports pre and post hooks.
resourceshooks.resources (Optional) Specifies an array of hooks that are applied to specific resources.
namehooks.resources.name Specifies the name of the hook. This value displays in the backup log.
includedNamespaceshooks.resources.includedNamespaces (Optional) Specifies an array of namespaces that this hook applies to. If unspecified, the hook is applied to all namespaces.
excludedNamespaceshooks.resources.excludedNamespaces (Optional) Specifies an array of namespaces to which this hook does not apply.
includedResourceshooks.resources.includedResources Specifies an array of pod resources to which this hook applies.
excludedResourceshooks.resources.excludedResources (Optional) Specifies an array of resources to which this hook does not apply.
labelSelectorhooks.resources.labelSelector (Optional) Specifies that this hook only applies to objects that match this label selector.
prehooks.resources.pre Specifies an array of exec hooks to run before executing custom actions.
posthooks.resources.post Specifies an array of exec hooks to run after executing custom actions. Supports the same arrays and fields as pre hooks.
exechooks.resources.[post/pre].exec Specifies the type of the hook. exec is the only supported type.
containerhooks.resources.[post/pre].exec.container (Optional) Specifies the name of the container where the specified command will be executed. If unspecified, the first container in the pod is used.
commandhooks.resources.[post/pre].exec.command Specifies the command to execute. The format is an array.
onErrorhooks.resources.[post/pre].exec.onError (Optional) Specifies how to handle an error that might occur when executing the command. Valid values: Fail and Continue Default: Fail
timeouthooks.resources.[post/pre].exec.timeout (Optional) Specifies how many seconds to wait for the command to finish executing before the action times out. Default: 30s
## Limitations {#limitations} -- The following top-level Velero fields, or children of `spec`, are not supported in full backups. Therefore, these fields are not shown in the preceding example specification. See [Example](#example). +- The following top-level Velero fields, or children of `spec`, are not supported in full backups: - `snapshotVolumes` - `volumeSnapshotLocations` @@ -165,7 +153,9 @@ The following Velero fields are supported for full backups, as shown in the prev - `includedResources` - `excludedResources` - Note that some of these fields are supported for hook arrays, as described in the previous field definition table. See [Fields](#fields). + :::note + Some of these fields are supported for hook arrays, as described in the previous field definition table. See [Supported Fields for Full Backups with Snapshots](#fields) above. + ::: -- All resources are included in the backup by default. However, resources can be excluded by adding `velero.io/exclude-from-backup=true` to the manifest files that you want to exclude. For more information, see [Configuring Backups](/vendor/snapshots-configuring-backups). +- All resources are included in the backup by default. However, resources can be excluded by adding `velero.io/exclude-from-backup=true` to the manifest files that you want to exclude. For more information, see [Configuring Snapshots](/vendor/snapshots-configuring-backups). diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index d56e042483..6fd0d21955 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -1,27 +1,29 @@ # Disaster Recovery for Embedded Cluster (Alpha) -This topic describes the disaster recovery feature for Replicated Embedded Cluster, including how to enable disaster recovery for your application, how to configure disaster recovery in the Replicated KOTS Admin Console, and how to restore from a backup. +This topic describes the disaster recovery feature for Replicated Embedded Cluster, including how to enable disaster recovery for your application. It also describes how end users can configure disaster recovery in the Replicated KOTS Admin Console and restore from a backup. :::important Embedded Cluster disaster recovery is an Alpha feature. This feature is subject to change, including breaking changes. To get access to this feature, reach out to Alex Parker at [alexp@replicated.com](mailto:alexp@replicated.com). ::: :::note -Embedded Cluster does not support backup and restore with the KOTS snapshots feature. For more information about snapshots, see [Understanding Backup and Restore](/vendor/snapshots-overview). +Embedded Cluster does not support backup and restore with the KOTS snapshots feature. For more information about using snapshots for existing cluster installations with KOTS, see [About Backup and Restore with Snapshots](/vendor/snapshots-overview). ::: ## Overview -The Embedded Cluster disaster recovery feature allows you to support backup and restore for your customers. Embedded Cluster users can configure and take backups from the Admin Console, and restore from the command line. +The Embedded Cluster disaster recovery feature allows your customers to take backups from the Admin Console and perform restores from the command line. Disaster recovery for Embedded Cluster is implemented with Velero. For more information about Velero, see the [Velero](https://velero.io/docs/latest/) documentation. -Disaster recovery for Embedded Cluster installations is implemented with Velero. For more information about Velero, see the [Velero](https://velero.io/docs/v1.14/) documentation. +The backups that your customers take from the Admin Console will include both the Embedded Cluster infrastructure and the application resources that you specify. + +The Embedded Cluster infrastructure that is backed up includes components such as the KOTS Admin Console and the built-in registry that is deployed for air gap installations. No configuration is required to include Embedded Cluster infrastructure in backups. Vendors specify the application resources to include in backups by configuring a Velero Backup resource in the application release. ## Requirements -Enabling disaster recovery for Embedded Cluster has the following requirements: +Embedded Cluster disaster recovery has the following requirements: * The disaster recovery feature flag must be enabled for your account. To get access to disaster recovery, reach out to Alex Parker at [alexp@replicated.com](mailto:alexp@replicated.com). -* Embedded Cluster version 1.4.1 or later +* Embedded Cluster version 1.22.0 or later * Backups must be stored in S3-compatible storage ## Limitations and Known Issues @@ -34,44 +36,68 @@ Embedded Cluster disaster recovery has the following limitations and known issue [View a larger version of this image](/images/ec-version-command.png) -* You can only restore from the most recent backup. +* Any Helm extensions included in the `extensions` field of the Embedded Cluster Config are _not_ included in backups. Helm extensions are reinstalled as part of the restore process. To include Helm extensions in backups, configure the Velero Backup resource to include the extensions using namespace-based or label-based selection. For more information, see [Configure the Velero Custom Resources](#config-velero-resources) below. + +* Users can only restore from the most recent backup. -* Velero is only installed during the installation process. Enabling the disaster recovery license field for customers after they have already installed will not do anything. +* Velero is installed only during the initial installation process. Enabling the disaster recovery license field for customers after they have already installed will not do anything. * If the `--admin-console-port` flag was used during install to change the port for the Admin Console, note that during a restore the Admin Console port will be used from the backup and cannot be changed. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). -## Configure Disaster Recovery for Your Application +## Configure Disaster Recovery + +This section describes how to configure disaster recovery for Embedded Cluster installations. It also describes how to enable access to the disaster recovery feature on a per-customer basis. -To configure disaster recovery for your application: +### Configure the Velero Custom Resources {#config-velero-resources} -1. Apply the `replicated.com/disaster-recovery: app` label to any Kubernetes resource you want backed up. +This section describes how to set up Embedded Cluster disaster recovery for your application by configuring Velero [Backup](https://velero.io/docs/latest/api-types/backup/) and [Restore](https://velero.io/docs/latest/api-types/restore/) custom resources in a release. - Example HelmChart resource to set the required label on all resources: +To configure Velero Backup and Restore custom resources for Embedded Cluster disaster recovery: - ```yaml - apiVersion: kots.io/v1beta2 - kind: HelmChart - metadata: - name: postgresql - spec: - chart: - name: postgresql - chartVersion: 15.5.0 - values: - commonLabels: - replicated.com/disaster-recovery: app - ``` +1. In a new release containing your application files, add a Velero Backup resource. In the Backup resource, use namespace-based or label-based selection to indicate the application resources that you want to be included in the backup. For more information, see [Backup API Type](https://velero.io/docs/latest/api-types/backup/) in the Velero documentation. -1. You must specify which Pod volumes you want backed up. This is done with the `backup.velero.io/backup-volumes` annotation. For more information, see [File System Backup](https://velero.io/docs/v1.14/file-system-backup/) in the Velero documentation. + :::important + If you use namespace-based selection to include all of your application resources deployed in the `kotsadm` namespace, ensure that you exclude the Replicated resources that are also deployed in the `kotsadm` namespace. Because the Embedded Cluster infrastructure components are always included in backups automatically, this avoids duplication. + ::: - Example Helm chart values to set the backup-volumes annotation on the relevant Pod: + **Example:** + + The following Backup resource uses namespace-based selection to include application resources deployed in the `kotsadm` namespace: ```yaml - podAnnotations: - backup.velero.io/backup-volumes: backup + apiVersion: velero.io/v1 + kind: Backup + metadata: + name: backup + spec: + # Back up the resources in the kotsadm namespace + includedNamespaces: + - kotsadm + orLabelSelectors: + - matchExpressions: + # Exclude Replicated resources from the backup + - { key: kots.io/kotsadm, operator: NotIn, values: ["true"] } ``` -1. (Optional) In addition to the previous steps, you can use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize your backup and restore process as needed. +1. In the same release, add a Velero Restore resource. In the `backupName` field of the Restore resource, include the name of the Backup resource that you created. For more information, see [Restore API Type](https://velero.io/docs/latest/api-types/restore/) in the Velero documentation. + + **Example**: + + ```yaml + apiVersion: velero.io/v1 + kind: Restore + metadata: + name: restore + spec: + # the name of the Backup resource that you created + backupName: backup + includedNamespaces: + - '*' + ``` + +1. (Optional) You can use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize the backup and restore process as needed. + + **Example**: For example, a Postgres database might be backed up using pg_dump to extract the database into a file as part of a backup hook. It can then be restored using the file in a restore hook: @@ -84,9 +110,11 @@ To configure disaster recovery for your application: post.hook.restore.velero.io/wait-for-ready: 'true' # waits for the pod to be ready before running the post-restore hook ``` -## Enable Disaster Recovery for Your Customers +1. Save and the promote the release to a development channel for testing. + +### Enable the Disaster Recovery Feature for Your Customers -After configuring disaster recovery for your application, you can enable it on a per-customer basis with the **Allow Disaster Recovery** license field. +After configuring disaster recovery for your application, you can enable it on a per-customer basis with the **Allow Disaster Recovery (Alpha)** license field. To enable disaster recovery for a customer: @@ -94,13 +122,19 @@ To enable disaster recovery for a customer: 1. On the **Manage customer** page, under **License options**, enable the **Allow Disaster Recovery (Alpha)** field. - When your customer installs with Embedded Cluster, Velero will be deployed if the **Allow Disaster Recovery** license field is enabled. + When your customer installs with Embedded Cluster, Velero will be deployed if the **Allow Disaster Recovery (Alpha)** license field is enabled. -## Configure Backup Storage and Take Backups in the Admin Console +## Take Backups and Restore -To configure backup storage and take backups in the Admin Console: +This section describes how your customers can configure backup storage, take backups, and restore from backups. -1. After installing the application and visiting the Admin Console, click the **Disaster Recovery** tab at the top of the Admin Console. +### Configure Backup Storage and Take Backups in the Admin Console + +Customers with the **Allow Disaster Recovery (Alpha)** license field can configure their backup storage location and take backups from the Admin Console. + +To configure backup storage and take backups: + +1. After installing the application and logging in to the Admin Console, click the **Disaster Recovery** tab at the top of the Admin Console. 1. For the desired S3-compatible backup storage location, enter the bucket, prefix (optional), access key ID, access key secret, endpoint, and region. Click **Update storage settings**. @@ -110,16 +144,17 @@ To configure backup storage and take backups in the Admin Console: 1. (Optional) From this same page, configure scheduled backups and a retention policy for backups. - scheduled backups + scheduled backups [View a larger version of this image](/images/dr-scheduled-backups.png) 1. In the **Disaster Recovery** submenu, click **Backups**. Backups can be taken from this screen. backups page + [View a larger version of this image](/images/dr-backups.png) -## Restore from a Backup +### Restore from a Backup To restore from a backup: diff --git a/docs/vendor/packaging-installer-storage.mdx b/docs/vendor/packaging-installer-storage.mdx index bce38a99df..c4449c33f6 100644 --- a/docs/vendor/packaging-installer-storage.mdx +++ b/docs/vendor/packaging-installer-storage.mdx @@ -70,12 +70,10 @@ To use the OpenEBS add-on without object storage, your kURL installer must meet * When neither the MinIO nor the Rook add-on are included in the kURL installer, the Velero add-on cannot be included. This is because, during installation, the Velero add-on automatically deploys internal storage for backups taken with the Replicated snapshots feature. The Velero add-on requires object storage to deploy this internal storage. If you include the Velero add-on without either the MinIO add-on or the Rook add-on, installation fails with the following error message: `Only Rook and Longhorn are supported for Velero Internal backup storage`. - When the Velero add-on is not included, your users must install and configure Velero on the cluster after installation in order to use Replicated snapshots for backup and restore. For more information, see [About Backup and Restore](/enterprise/snapshots-understanding). + When the Velero add-on is not included, your users must install and configure Velero on the cluster after installation in order to use Replicated snapshots for backup and restore. See [About Backup and Restore with Snapshots](/vendor/snapshots-overview). For a storage configuration for single node clusters that supports the use of the Velero add-on, see [OpenEBS with MinIO (Single or Multi-Node)](#openebs-minio) below. - - #### Example The following is an example installer that uses OpenEBS v3.3.x with Local PV for local storage and disables object storage for KOTS: diff --git a/docs/vendor/packaging-rbac.md b/docs/vendor/packaging-rbac.md index 49c016e6eb..ccb697f70e 100644 --- a/docs/vendor/packaging-rbac.md +++ b/docs/vendor/packaging-rbac.md @@ -102,7 +102,7 @@ The following limitations apply when using the `requireMinimalRBACPrivileges` or To set up snapshots when KOTS has namespace-scoped access, users can run the `kubectl kots velero ensure-permissions` command. This command creates additional Roles and RoleBindings to allow the necessary cross-namespace access. For more information, see [`velero ensure-permissions`](/reference/kots-cli-velero-ensure-permissions/) in the KOTS CLI documentation. - For more information about snapshots, see [About Backing Up and Restoring with Snapshots](/enterprise/snapshots-understanding). + For more information about snapshots, see [About Backup and Restore with Snapshots](/vendor/snapshots-overview). * **Air Gap Installations**: For air gap installations, the `requireMinimalRBACPrivileges` and `supportMinimalRBACPrivileges` flags are supported only in automated, or _headless_, installations. In headless installations, the user passes all the required information to install both KOTS and the application with the `kots install` command. In non-headless installations, the user provides information to install the application through the Admin Console UI after KOTS is installed. diff --git a/docs/vendor/replicated-onboarding.mdx b/docs/vendor/replicated-onboarding.mdx index 9f56b5c028..b8420187e4 100644 --- a/docs/vendor/replicated-onboarding.mdx +++ b/docs/vendor/replicated-onboarding.mdx @@ -545,7 +545,7 @@ Enable backup and restore with Velero for your application so that users can bac There are different steps to configure backup and restore for Embedded Cluster and for existing cluster installations with KOTS: * To configure the disaster recovery feature for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery) -* To configure the snapshots feature for existing cluster KOTS installations, see [Configuring Backup and Restore](snapshots-configuring-backups). +* To configure the snapshots feature for existing cluster KOTS installations, see [Configuring Snapshots](snapshots-configuring-backups). ### Add Custom Metrics diff --git a/docs/vendor/snapshots-configuring-backups.md b/docs/vendor/snapshots-configuring-backups.md index 263ca40eff..daf5fdb71d 100644 --- a/docs/vendor/snapshots-configuring-backups.md +++ b/docs/vendor/snapshots-configuring-backups.md @@ -1,34 +1,41 @@ -# Configuring Backups +# Configuring Snapshots -The snapshots feature is a backup and restore option that lets you define a manifest for creating backups and restoring previous backups. The backups include all of the annotated volumes in the archive. For more information, see [About Backup and Restore](snapshots-overview/). +This topic provides information about how to configure the Velero Backup resource to enable Replicated KOTS snapshots for an application. -:::note -If you are using multiple applications, repeat this procedure for each application. Every application must have its own Backup resource to be included in a full backup. -::: +For more information about snapshots, see [About Backup and Restore with snapshots](/vendor/snapshots-overview). -To configure backups: +## Configure Snapshots -1. Enable backups: +Add a Velero Backup custom resource (`kind: Backup`, `apiVersion: velero.io/v1`) to your release and configure it as needed. After configuring the Backup resource, add annotations for each volume that you want to be included in backups. - 1. Add a Backup resource (`kind: Backup`) using `apiVersion: velero.io/v1` to the application manifest files. The following minimal YAML example enables backups in the application. For more information about Backup resource options, see [Velero Backup Custom Resource](/reference/custom-resource-backup). +To configure snapshots for your application: - **Example:** +1. In a new release containing your application files, add a Velero Backup resource (`kind: Backup` and `apiVersion: velero.io/v1`): - ```yaml - apiVersion: velero.io/v1 - kind: Backup - metadata: - name: backup - spec: {} + ```yaml + apiVersion: velero.io/v1 + kind: Backup + metadata: + name: backup + spec: {} + ``` + +1. Configure the Backup resource to specify the resources that will be included in backups. + + For more information about the Velero Backup resource, including limitations, the list of supported fields for snapshots, and an example, see [Velero Backup Resource for Snapshots](/reference/custom-resource-backup). + +1. (Optional) Configure backup and restore hooks. For more information, see [Configuring Backup and Restore Hooks for Snapshots](snapshots-hooks). - ``` - 1. (Optional) Configure the resources annotation in the manifest so that it can be dynamically enabled based on a license field or a config option. For more information, see [Including Optional and Conditional Resources](packaging-include-resources/). +1. For each volume that requires a backup, add the `backup.velero.io/backup-volumes` annotation. The annotation name is `backup.velero.io/backup-volumes` and the value is a comma separated list of volumes to include in the backup. -1. Configure backups for each volume that requires a backup. By default, no volumes are included in the backup. If any pods mount a volume that should be backed up, you must configure the backup with an annotation listing the specific volumes to include in the backup. +
+ Why do I need to use the backup annotation? +

By default, no volumes are included in the backup. If any pods mount a volume that should be backed up, you must configure the backup with an annotation listing the specific volumes to include in the backup.

+
- The annotation name is `backup.velero.io/backup-volumes` and the value is a comma separated list of volumes to include in the backup. + **Example:** - For example, in the following Deployment manifest file, `pvc-volume` is the only volume that is backed up. The `scratch` volume is not included in the backup because it is not listed in annotation on the pod specification. + In the following Deployment manifest file, `pvc-volume` is the only volume that is backed up. The `scratch` volume is not included in the backup because it is not listed in annotation on the pod specification. ```yaml apiVersion: apps/v1 @@ -81,9 +88,7 @@ To configure backups: uri: Secret To Not Include ``` - -1. (Optional) If you are distributing your application with Replicated kURL, Replicated recommends that you include the kURL Velero add-on so that customers do not have to manually install Velero on their cluster. For more information about distributing with kURL, see [Creating a kURL installer](packaging-embedded-kubernetes). -## Next Step +1. If you distribute multiple applications with Replicated, repeat these steps for each application. Each application must have its own Backup resource to be included in a full backup with snapshots. -Next, you can configure backup and restore hooks. See [Configuring Backup and Restore Hooks](snapshots-hooks). \ No newline at end of file +1. (kURL Only) If your application supports installation with Replicated kURL, Replicated recommends that you include the kURL Velero add-on so that customers do not have to manually install Velero in the kURL cluster. For more information, see [Creating a kURL Installer](packaging-embedded-kubernetes). \ No newline at end of file diff --git a/docs/vendor/snapshots-hooks.md b/docs/vendor/snapshots-hooks.md index 34827ea3a9..227becd8d8 100644 --- a/docs/vendor/snapshots-hooks.md +++ b/docs/vendor/snapshots-hooks.md @@ -1,4 +1,4 @@ -# Configuring Backup and Restore Hooks +# Configuring Backup and Restore Hooks for Snapshots This topic describes the use of custom backup and restore hooks and demonstrates a common example. diff --git a/docs/vendor/snapshots-overview.md b/docs/vendor/snapshots-overview.md deleted file mode 100644 index 4c9c2ee388..0000000000 --- a/docs/vendor/snapshots-overview.md +++ /dev/null @@ -1,67 +0,0 @@ -import RestoreTable from "../partials/snapshots/_restoreTable.mdx" -import NoEcSupport from "../partials/snapshots/_limitation-no-ec-support.mdx" - -# Understanding Backup and Restore - -This topic provides an introduction to the Replicated KOTS snapshots feature for backup and restore. It describes how vendors enable snapshots, the type of data that is backed up, and how to troubleshoot issues for enterprise users. - -:::note - -::: - -## About Backup and Restore - -You can enable Replicated KOTS snapshots to support backup and restore for existing cluster installations with KOTS and Replicated kURL installations. - -Snapshots uses the Velero open source project as the backend to back up Kubernetes manifests and persistent volumes. Velero is a mature, fully-featured application. For more information, see the [Velero documentation](https://velero.io/docs/). - -In addition to the default functionality that Velero provides, KOTS exposes hooks that let you inject scripts that can execute both before and after a backup, and before and after a restore. For more information, see [Configuring Backup and Restore Hooks](snapshots-hooks). - -KOTS provides the Admin Console and the KOTS CLI so that your users can fully manage the backup and restore process. For more information, see [Understanding Backup and Restore for Enterprise Users](#how-users). - -## What Data is Backed Up - -Full backups include the Admin Console and all application data, including KOTS-specific object-stored data. For Replicated kURL installations, this also backs up the Docker registry, which is required for air gapped installations. - -### Other Object-Stored Data - -For kURL clusters, you might be using object-stored data that is not specific to the kURL KOTS add-on. - -For object-stored data that is not KOTS-specific and does not use persistentVolumeClaims (PVCs), you must write custom backup and restore hooks to enable back ups for that object-stored data. For example, Rook and Ceph do not use PVCs and so require custom backup and restore hooks. For more information about writing custom hooks, see [Configuring Backup and Restore Hooks](snapshots-hooks). - -### Pod Volume Data - -Replicated supports only the restic backup program for pod volume data. - -By default, Velero requires that you opt-in to have pod volumes backed up. In the Backup resource that you configure to enable snapshots, you must annotate each specific volume that you want to back up. For more information about including and excluding pod volumes, see [Configuring Backups](snapshots-configuring-backups). - -## How to Enable Backup and Restore - -To enable the snapshots backup and restore feature for your users, you must: - -- Have the snapshots entitlement enabled in your Replicated vendor account. For account entitlements, contact the Replicated TAM team. -- Define a manifest for creating backups. See [Configuring Backups](snapshots-configuring-backups). -- When needed, configure backup and restore hooks. See [Configuring Backup and Restore Hooks](snapshots-hooks). -- Enable the **Allow Snapshot** option in customer licenses. See [Creating and Managing Customers](releases-creating-customer). - -## Understanding Backup and Restore for Enterprise Users {#how-users} - -After vendors enable backup and restore, enterprise users install Velero and configure a storage destination in the Admin Console. Then users can create backups manually or schedule automatic backups. For more information about how users create and restore backups, see [About Backing Up and Restoring with Snapshots](/enterprise/snapshots-understanding). - -Replicated recommends advising your users to make full backups for disaster recovery purposes. Additionally, full backups give users the flexibility to do a full restore, a partial restore (application only), or restore just the Admin Console. - -From a full backup, users restore using the KOTS CLI or the Admin Console as indicated in the following table: - - - -Partial backups are not recommended as they are a legacy feature and only back up the application volumes and manifests. Partial backups can be restored only from the Admin Console. - -## Troubleshooting Backup and Restore - -To support end users with backup and restore, use the following resources: - -- To help troubleshoot error messages, see [Troubleshooting Backup and Restore](/enterprise/snapshots-troubleshooting-backup-restore). - -- Review the Limitations and Considerations section to make sure an end users system is compliant. See [Limitations and Considerations](/enterprise/snapshots-understanding#limitations-and-considerations). - -- Check that the installed Velero version and KOTS version are compatible. See [Velero Version Compatibility](/enterprise/snapshots-understanding#velero-version-compatibility). \ No newline at end of file diff --git a/docs/enterprise/snapshots-understanding.mdx b/docs/vendor/snapshots-overview.mdx similarity index 57% rename from docs/enterprise/snapshots-understanding.mdx rename to docs/vendor/snapshots-overview.mdx index 9fa133c5a0..5a5caa1724 100644 --- a/docs/enterprise/snapshots-understanding.mdx +++ b/docs/vendor/snapshots-overview.mdx @@ -1,13 +1,14 @@ +import RestoreTable from "../partials/snapshots/_restoreTable.mdx" +import NoEcSupport from "../partials/snapshots/_limitation-no-ec-support.mdx" import RestoreTypes from "../partials/snapshots/_restore-types.mdx" import Dr from "../partials/snapshots/_limitation-dr.mdx" import Os from "../partials/snapshots/_limitation-os.mdx" import InstallMethod from "../partials/snapshots/_limitation-install-method.mdx" import CliRestores from "../partials/snapshots/_limitation-cli-restores.mdx" -import NoEcSupport from "../partials/snapshots/_limitation-no-ec-support.mdx" -# About Backing Up and Restoring with Snapshots +# About Backup and Restore with Snapshots -This topic provides an introduction to performing backup and restore with the Replicated KOTS snapshots feature. +This topic provides an introduction to the Replicated KOTS snapshots feature for backup and restore. It describes how vendors enable snapshots, the type of data that is backed up, and how to troubleshoot issues for enterprise users. :::note @@ -15,9 +16,13 @@ This topic provides an introduction to performing backup and restore with the Re ## Overview -An important part of the lifecycle of an application is backup and restore. The snapshots feature can be used to create backups of KOTS installations and restore from backups. The KOTS Admin Console can be used to create and manage your storage destination and schedule, and to perform and monitor the backup and restore process. +An important part of the lifecycle of an application is backup and restore. You can enable Replicated KOTS snapshots to support backup and restore for existing cluster installations with KOTS and Replicated kURL installations. + +When snapshots is enabled for your application, your customers can manage and perform backup and restore from the Admin Console or KOTS CLI. + +Snapshots uses the Velero open source project as the backend to back up Kubernetes manifests and persistent volumes. Velero is a mature, fully-featured application. For more information, see the [Velero documentation](https://velero.io/docs/). -Velero and restic are the underlying technologies for snapshots. For more information, see the [Velero documentation](https://velero.io/docs/). +In addition to the default functionality that Velero provides, KOTS exposes hooks that let you inject scripts that can execute both before and after a backup, and before and after a restore. For more information, see [Configuring Backup and Restore Hooks for Snapshots](/vendor/snapshots-hooks). ### Limitations and Considerations @@ -53,7 +58,6 @@ The following table lists which versions of Velero are compatible with each vers This section describes the types of backups that are supported with snapshots. For information about how to configure backup storage destinations for snapshots, see the [Configuring Backup Storage](/enterprise/snapshots-velero-cli-installing) section. - ### Application and Admin Console (Full) Backups Full backups (also referred to as _instance_ backups) include the KOTS Admin Console and all application data, including application volumes and manifest files. @@ -89,6 +93,22 @@ kURL installers that include the Velero add-on also include a locally-provisione For information about how to configure backup storage destinations for snapshots, see the [Configuring Backup Storage](/enterprise/snapshots-velero-cli-installing) section. +### What Data is Backed Up? + +Full backups include the Admin Console and all application data, including KOTS-specific object-stored data. For Replicated kURL installations, this also backs up the Docker registry, which is required for air gapped installations. + +#### Other Object-Stored Data + +For kURL clusters, you might be using object-stored data that is not specific to the kURL KOTS add-on. + +For object-stored data that is not KOTS-specific and does not use persistentVolumeClaims (PVCs), you must write custom backup and restore hooks to enable back ups for that object-stored data. For example, Rook and Ceph do not use PVCs and so require custom backup and restore hooks. For more information about writing custom hooks, see [Configuring Backup and Restore Hooks for Snapshots](snapshots-hooks). + +#### Pod Volume Data + +Replicated supports only the restic backup program for pod volume data. + +By default, Velero requires that you opt-in to have pod volumes backed up. In the Backup resource that you configure to enable snapshots, you must annotate each specific volume that you want to back up. For more information about including and excluding pod volumes, see [Configuring Snapshots](/vendor/snapshots-configuring-backups). + ## About Restores {#restores} @@ -99,4 +119,39 @@ Then, the restore process redeploys all of the application manifests. All Pods a When you restore the Admin Console only, no changes are made to the application. -For information about how to restore using the Admin Console or the KOTS CLI, see [Restoring from Backups](snapshots-restoring-full). +For information about how to restore using the Admin Console or the KOTS CLI, see [Restoring from Backups](/enterprise/snapshots-restoring-full). + +## Using Snapshots + +This section provides an overview of how vendors and enterprise users can configure and use the snapshots feature. + +### How to Enable Snapshots for Your Application + +To enable the snapshots backup and restore feature for your users, you must: + +- Have the snapshots entitlement enabled in your Replicated vendor account. For account entitlements, contact the Replicated TAM team. +- Define a manifest for creating backups. See [Configuring Snapshots](snapshots-configuring-backups). +- When needed, configure backup and restore hooks. See [Configuring Backup and Restore Hooks for Snapshots](snapshots-hooks). +- Enable the **Allow Snapshot** option in customer licenses. See [Creating and Managing Customers](releases-creating-customer). + +### Understanding Backup and Restore for Users {#how-users} + +After vendors enable backup and restore, enterprise users install Velero and configure a storage destination in the Admin Console. Then users can create backups manually or schedule automatic backups. + +Replicated recommends advising your users to make full backups for disaster recovery purposes. Additionally, full backups give users the flexibility to do a full restore, a partial restore (application only), or restore just the Admin Console. + +From a full backup, users restore using the KOTS CLI or the Admin Console as indicated in the following table: + + + +Partial backups are not recommended as they are a legacy feature and only back up the application volumes and manifests. Partial backups can be restored only from the Admin Console. + +### Troubleshooting Snapshots + +To support end users with backup and restore, use the following resources: + +- To help troubleshoot error messages, see [Troubleshooting Snapshots](/enterprise/snapshots-troubleshooting-backup-restore). + +- Review the Limitations and Considerations section to make sure an end users system is compliant. + +- Check that the installed Velero version and KOTS version are compatible. \ No newline at end of file diff --git a/netlify.toml b/netlify.toml index 7d0cda8f20..1d953e959e 100644 --- a/netlify.toml +++ b/netlify.toml @@ -238,7 +238,12 @@ [[redirects]] from="https://docs.replicated.com/vendor/releases-configvalues" - to="https://docs.replicated.com/enterprise/installing-embedded-automation" + to="https://docs.replicated.com/enterprise/installing-embedded-automation" + + +[[redirects]] + from="https://docs.replicated.com/enterprise/snapshots-understanding" + to="https://docs.replicated.com/vendor/snapshots-overview" ################################################### # Redirects To the References Section diff --git a/sidebars.js b/sidebars.js index b68cd8ad93..a244b1a292 100644 --- a/sidebars.js +++ b/sidebars.js @@ -328,16 +328,6 @@ const sidebars = { 'vendor/packaging-air-gap-excluding-minio', ], }, - { - type: 'category', - label: 'Configuring Backup and Restore with Snapshots', - items: [ - 'vendor/snapshots-overview', - 'vendor/snapshots-configuring-backups', - 'vendor/snapshots-hooks', - 'reference/custom-resource-backup', - ], - }, { type: 'category', label: 'Distributing Kubernetes Operators with KOTS', @@ -410,10 +400,19 @@ const sidebars = { type: 'category', label: 'Performing Backup and Restore with Snapshots', items: [ - 'enterprise/snapshots-understanding', + 'vendor/snapshots-overview', + { + type: 'category', + label: 'Enabling and Configuring Snapshots', + items: [ + 'vendor/snapshots-configuring-backups', + 'reference/custom-resource-backup', + 'vendor/snapshots-hooks', + ], + }, { type: 'category', - label: 'Configuring Backup Storage', + label: 'Configuring Backup Storage for Snaphots', items: [ 'enterprise/snapshots-velero-cli-installing', 'enterprise/snapshots-configuring-hostpath',