Merge pull request #8333 from Lyndon-Li/add-1.15-doc

Add doc for 1.15
vmware-tanzu · Oct 23, 2024 · bdd231c · bdd231c
2 parents 182478f + 9f17fb3
commit bdd231c
Show file tree

Hide file tree

Showing 86 changed files with 9,380 additions and 1 deletion.
diff --git a/site/config.yaml b/site/config.yaml
@@ -12,9 +12,10 @@ params:
   hero:
     backgroundColor: med-blue
   versioning: true
-  latest: v1.14
+  latest: v1.15
   versions:
     - main
+    - v1.15
     - v1.14
     - v1.13
     - v1.12

diff --git a/site/content/docs/v1.15/_index.md b/site/content/docs/v1.15/_index.md
@@ -0,0 +1,58 @@
+---
+toc: "false"
+cascade:
+  version: v1.15
+  toc: "true"
+---
+![100]
+
+[![Build Status][1]][2]
+
+## Overview
+
+Velero (formerly Heptio Ark) gives you tools to back up and restore your Kubernetes cluster resources and persistent volumes. You can run Velero with a cloud provider or on-premises. Velero lets you:
+
+* Take backups of your cluster and restore in case of loss.
+* Migrate cluster resources to other clusters.
+* Replicate your production cluster to development and testing clusters.
+
+Velero consists of:
+
+* A server that runs on your cluster
+* A command-line client that runs locally
+
+## Documentation
+
+This site is our documentation home with installation instructions, plus information about customizing Velero for your needs, architecture, extending Velero, contributing to Velero and more.
+
+Please use the version selector at the top of the site to ensure you are using the appropriate documentation for your version of Velero.
+
+## Troubleshooting
+
+If you encounter issues, review the [troubleshooting docs][30], [file an issue][4], or talk to us on the [#velero-users channel][25] on the Kubernetes Slack server.
+
+## Contributing
+
+If you are ready to jump in and test, add code, or help with documentation, follow the instructions on our [Start contributing](https://velero.io/docs/v1.15.0/start-contributing/) documentation for guidance on how to setup Velero for development.
+
+## Changelog
+
+See [the list of releases][6] to find out about feature changes.
+
+[1]: https://github.com/vmware-tanzu/velero/workflows/Main%20CI/badge.svg
+[2]: https://github.com/vmware-tanzu/velero/actions?query=workflow%3A"Main+CI"
+
+[4]: https://github.com/vmware-tanzu/velero/issues
+[6]: https://github.com/vmware-tanzu/velero/releases
+
+[9]: https://kubernetes.io/docs/setup/
+[10]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos
+[11]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
+[12]: https://github.com/kubernetes/kubernetes/blob/main/cluster/addons/dns/README.md
+[14]: https://github.com/kubernetes/kubernetes
+[24]: https://groups.google.com/forum/#!forum/projectvelero
+[25]: https://kubernetes.slack.com/messages/velero-users
+
+[30]: troubleshooting.md
+
+[100]: img/velero.png
diff --git a/site/content/docs/v1.15/api-types/README.md b/site/content/docs/v1.15/api-types/README.md
@@ -0,0 +1,21 @@
+---
+title: "Table of Contents"
+layout: docs
+---
+
+## API types
+
+Here we list the API types that have some functionality that you can only configure via json/yaml vs the `velero` cli
+(hooks)
+
+* [Backup][1]
+* [Restore][2]
+* [Schedule][3]
+* [BackupStorageLocation][4]
+* [VolumeSnapshotLocation][5]
+
+[1]: backup.md
+[2]: restore.md
+[3]: schedule.md
+[4]: backupstoragelocation.md
+[5]: volumesnapshotlocation.md
diff --git a/site/content/docs/v1.15/api-types/_index.md b/site/content/docs/v1.15/api-types/_index.md
@@ -0,0 +1,19 @@
+---
+layout: docs
+title: API types
+---
+
+Here's a list the API types that have some functionality that you can only configure via json/yaml vs the `velero` cli
+(hooks)
+
+* [Backup][1]
+* [Restore][2]
+* [Schedule][3]
+* [BackupStorageLocation][4]
+* [VolumeSnapshotLocation][5]
+
+[1]: backup.md
+[2]: restore.md
+[3]: schedule.md
+[4]: backupstoragelocation.md
+[5]: volumesnapshotlocation.md
diff --git a/site/content/docs/v1.15/api-types/backup.md b/site/content/docs/v1.15/api-types/backup.md
@@ -0,0 +1,211 @@
+---
+title: "Backup API Type"
+layout: docs
+---
+
+## Use
+
+Use the `Backup` API type to request the Velero server to perform a backup. Once created, the
+Velero Server immediately starts the backup process.
+
+## API GroupVersion
+
+Backup belongs to the API group version `velero.io/v1`.
+
+## Definition
+
+Here is a sample `Backup` object with each of the fields documented:
+
+```yaml
+# Standard Kubernetes API Version declaration. Required.
+apiVersion: velero.io/v1
+# Standard Kubernetes Kind declaration. Required.
+kind: Backup
+# Standard Kubernetes metadata. Required.
+metadata:
+  # Backup name. May be any valid Kubernetes object name. Required.
+  name: a
+  # Backup namespace. Must be the namespace of the Velero server. Required.
+  namespace: velero
+# Parameters about the backup. Required.
+spec:
+  # CSISnapshotTimeout specifies the time used to wait for
+  # CSI VolumeSnapshot status turns to ReadyToUse during creation, before
+  # returning error as timeout. The default value is 10 minute.
+  csiSnapshotTimeout: 10m
+  # ItemOperationTimeout specifies the time used to wait for
+  # asynchronous BackupItemAction operations
+  # The default value is 4 hour.
+  itemOperationTimeout: 4h
+  # resourcePolicy specifies the referenced resource policies that backup should follow
+  # optional
+  resourcePolicy:
+    kind: configmap
+    name: resource-policy-configmap
+  # Array of namespaces to include in the backup. If unspecified, all namespaces are included.
+  # Optional.
+  includedNamespaces:
+  - '*'
+  # Array of namespaces to exclude from the backup. Optional.
+  excludedNamespaces:
+  - some-namespace
+  # Array of resources to include in the backup. Resources may be shortcuts (for example 'po' for 'pods')
+  # or fully-qualified. If unspecified, all resources are included. Optional.
+  includedResources:
+  - '*'
+  # Array of resources to exclude from the backup. Resources may be shortcuts (for example 'po' for 'pods')
+  # or fully-qualified. Optional.
+  excludedResources:
+  - storageclasses.storage.k8s.io
+  # Order of the resources to be collected during the backup process.  It's a map with key being the plural resource
+  # name, and the value being a list of object names separated by comma.  Each resource name has format "namespace/objectname".
+  # For cluster resources, simply use "objectname". Optional
+  orderedResources:
+    pods: mysql/mysql-cluster-replica-0,mysql/mysql-cluster-replica-1,mysql/mysql-cluster-source-0
+    persistentvolumes: pvc-87ae0832-18fd-4f40-a2a4-5ed4242680c4,pvc-63be1bb0-90f5-4629-a7db-b8ce61ee29b3
+  # Whether to include cluster-scoped resources. Valid values are true, false, and
+  # null/unset. If true, all cluster-scoped resources are included (subject to included/excluded
+  # resources and the label selector). If false, no cluster-scoped resources are included. If unset,
+  # all cluster-scoped resources are included if and only if all namespaces are included and there are
+  # no excluded namespaces. Otherwise, if there is at least one namespace specified in either
+  # includedNamespaces or excludedNamespaces, then the only cluster-scoped resources that are backed
+  # up are those associated with namespace-scoped resources included in the backup. For example, if a
+  # PersistentVolumeClaim is included in the backup, its associated PersistentVolume (which is
+  # cluster-scoped) would also be backed up.
+  includeClusterResources: null
+  # Array of cluster-scoped resources to exclude from the backup. Resources may be shortcuts 
+  # (for example 'sc' for 'storageclasses'), or fully-qualified. If unspecified, 
+  # no additional cluster-scoped resources are excluded. Optional.
+  # Cannot work with include-resources, exclude-resources and include-cluster-resources.
+  excludedClusterScopedResources: {}
+  # Array of cluster-scoped resources to include from the backup. Resources may be shortcuts 
+  # (for example 'sc' for 'storageclasses'), or fully-qualified. If unspecified, 
+  # no additional cluster-scoped resources are included. Optional.
+  # Cannot work with include-resources, exclude-resources and include-cluster-resources.
+  includedClusterScopedResources: {}
+  # Array of namespace-scoped resources to exclude from the backup. Resources may be shortcuts 
+  # (for example 'cm' for 'configmaps'), or fully-qualified. If unspecified, 
+  # no namespace-scoped resources are excluded. Optional.
+  # Cannot work with include-resources, exclude-resources and include-cluster-resources.
+  excludedNamespaceScopedResources: {}
+  # Array of namespace-scoped resources to include from the backup. Resources may be shortcuts 
+  # (for example 'cm' for 'configmaps'), or fully-qualified. If unspecified, 
+  # all namespace-scoped resources are included. Optional.
+  # Cannot work with include-resources, exclude-resources and include-cluster-resources.
+  includedNamespaceScopedResources: {}
+  # Individual objects must match this label selector to be included in the backup. Optional.
+  labelSelector:
+    matchLabels:
+      app: velero
+      component: server
+  # Individual object when matched with any of the label selector specified in the set are to be included in the backup. Optional.
+  # orLabelSelectors as well as labelSelector cannot co-exist, only one of them can be specified in the backup request
+  orLabelSelectors:
+  - matchLabels:
+      app: velero
+  - matchLabels:
+      app: data-protection
+  # Whether or not to snapshot volumes. Valid values are true, false, and null/unset. If unset, Velero performs snapshots as long as
+  # a persistent volume provider is configured for Velero.
+  snapshotVolumes: null
+  # Where to store the tarball and logs.
+  storageLocation: aws-primary
+  # The list of locations in which to store volume snapshots created for this backup.
+  volumeSnapshotLocations:
+    - aws-primary
+    - gcp-primary
+  # The amount of time before this backup is eligible for garbage collection. If not specified,
+  # a default value of 30 days will be used. The default can be configured on the velero server
+  # by passing the flag --default-backup-ttl.
+  ttl: 24h0m0s
+  # whether pod volume file system backup should be used for all volumes by default.
+  defaultVolumesToFsBackup: true
+  # Whether snapshot data should be moved. If set, data movement is launched after the snapshot is created.
+  snapshotMoveData: true
+  # The data mover to be used by the backup. If the value is "" or "velero", the built-in data mover will be used.
+  datamover: velero
+  # UploaderConfig specifies the configuration for the uploader
+  uploaderConfig:
+      # ParallelFilesUpload is the number of files parallel uploads to perform when using the uploader.
+      parallelFilesUpload: 10
+  # Actions to perform at different times during a backup. The only hook supported is
+  # executing a command in a container in a pod using the pod exec API. Optional.
+  hooks:
+    # Array of hooks that are applicable to specific resources. Optional.
+    resources:
+      -
+        # Name of the hook. Will be displayed in backup log.
+        name: my-hook
+        # Array of namespaces to which this hook applies. If unspecified, the hook applies to all
+        # namespaces. Optional.
+        includedNamespaces:
+        - '*'
+        # Array of namespaces to which this hook does not apply. Optional.
+        excludedNamespaces:
+        - some-namespace
+        # Array of resources to which this hook applies. The only resource supported at this time is
+        # pods.
+        includedResources:
+        - pods
+        # Array of resources to which this hook does not apply. Optional.
+        excludedResources: []
+        # This hook only applies to objects matching this label selector. Optional.
+        labelSelector:
+          matchLabels:
+            app: velero
+            component: server
+        # An array of hooks to run before executing custom actions. Only "exec" hooks are supported.
+        pre:
+          -
+            # The type of hook. This must be "exec".
+            exec:
+              # The name of the container where the command will be executed. If unspecified, the
+              # first container in the pod will be used. Optional.
+              container: my-container
+              # The command to execute, specified as an array. Required.
+              command:
+                - /bin/uname
+                - -a
+              # How to handle an error executing the command. Valid values are Fail and Continue.
+              # Defaults to Fail. Optional.
+              onError: Fail
+              # How long to wait for the command to finish executing. Defaults to 30 seconds. Optional.
+              timeout: 10s
+        # An array of hooks to run after all custom actions and additional items have been
+        # processed. Only "exec" hooks are supported.
+        post:
+          # Same content as pre above.
+# Status about the Backup. Users should not set any data here.
+status:
+  # The version of this Backup. The only version supported is 1.
+  version: 1
+  # The date and time when the Backup is eligible for garbage collection.
+  expiration: null
+  # The current phase.
+  # Valid values are New, FailedValidation, InProgress, WaitingForPluginOperations,
+  # WaitingForPluginOperationsPartiallyFailed, FinalizingafterPluginOperations,
+  # FinalizingPartiallyFailed, Completed, PartiallyFailed, Failed.
+  phase: ""
+  # An array of any validation errors encountered.
+  validationErrors: null
+  # Date/time when the backup started being processed.
+  startTimestamp: 2019-04-29T15:58:43Z
+  # Date/time when the backup finished being processed.
+  completionTimestamp: 2019-04-29T15:58:56Z
+  # Number of volume snapshots that Velero tried to create for this backup.
+  volumeSnapshotsAttempted: 2
+  # Number of volume snapshots that Velero successfully created for this backup.
+  volumeSnapshotsCompleted: 1
+  # Number of attempted BackupItemAction operations for this backup.
+  backupItemOperationsAttempted: 2
+  # Number of BackupItemAction operations that Velero successfully completed for this backup.
+  backupItemOperationsCompleted: 1
+  # Number of BackupItemAction operations that ended in failure for this backup.
+  backupItemOperationsFailed: 0
+  # Number of warnings that were logged by the backup.
+  warnings: 2
+  # Number of errors that were logged by the backup.
+  errors: 0
+  # An error that caused the entire backup to fail.
+  failureReason: ""
+```
diff --git a/site/content/docs/v1.15/api-types/backupstoragelocation.md b/site/content/docs/v1.15/api-types/backupstoragelocation.md
@@ -0,0 +1,54 @@
+---
+title: "Velero Backup Storage Locations"
+layout: docs
+---
+
+## Backup Storage Location
+
+Velero can store backups in a number of locations. These are represented in the cluster via the `BackupStorageLocation` CRD.
+
+Velero must have at least one `BackupStorageLocation`. By default, this is expected to be named `default`, however the name can be changed by specifying `--default-backup-storage-location` on `velero server`.  Backups that do not explicitly specify a storage location will be saved to this `BackupStorageLocation`.
+
+A sample YAML `BackupStorageLocation` looks like the following:
+
+```yaml
+apiVersion: velero.io/v1
+kind: BackupStorageLocation
+metadata:
+  name: default
+  namespace: velero
+spec:
+  backupSyncPeriod: 2m0s
+  provider: aws
+  objectStorage:
+    bucket: myBucket
+  credential:
+    name: secret-name
+    key: key-in-secret
+  config:
+    region: us-west-2
+    profile: "default"
+```
+
+### Parameter Reference
+
+The configurable parameters are as follows:
+
+#### Main config parameters
+
+{{< table caption="Main config parameters" >}}
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `provider` | String | Required Field | The name for whichever object storage provider will be used to store the backups. See [your object storage provider's plugin documentation](../supported-providers) for the appropriate value to use. |
+| `objectStorage` | ObjectStorageLocation | Required Field | Specification of the object storage for the given provider. |
+| `objectStorage/bucket` | String | Required Field | The storage bucket where backups are to be uploaded. |
+| `objectStorage/prefix` | String | Optional Field | The directory inside a storage bucket where backups are to be uploaded. |
+| `objectStorage/caCert` | String | Optional Field | A base64 encoded CA bundle to be used when verifying TLS connections |
+| `config` | map[string]string | None (Optional) | Provider-specific configuration keys/values to be passed to the object store plugin. See [your object storage provider's plugin documentation](../supported-providers) for details. |
+| `accessMode` | String | `ReadWrite` | How Velero can access the backup storage location. Valid values are `ReadWrite`, `ReadOnly`. |
+| `backupSyncPeriod` | metav1.Duration | Optional Field | How frequently Velero should synchronize backups in object storage. Default is Velero's server backup sync period. Set this to `0s` to disable sync. |
+| `validationFrequency` | metav1.Duration | Optional Field | How frequently Velero should validate the object storage . Default is Velero's server validation frequency. Set this to `0s` to disable validation. Default 1 minute. |
+| `credential` | [corev1.SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#secretkeyselector-v1-core) | Optional Field | The credential information to be used with this location. |
+| `credential/name` | String | Optional Field | The name of the secret within the Velero namespace which contains the credential information. |
+| `credential/key` | String | Optional Field | The key to use within the secret. |
+{{< /table >}}