Merge pull request #2307 from skriss/v1.3-docs-changelog

v1.3.0 docs & changelog
2026-07-25 17:43:00 +00:00 · 2020-03-02 09:43:52 -07:00
parent a9f0726df3 b7f6b5170d
commit 8fec8ed7fb
80 changed files with 85 additions and 92 deletions
@@ -1,11 +1,11 @@
 ## Current release:
-  * [CHANGELOG-1.2.md][12]
+  * [CHANGELOG-1.3.md][13]

 ## Development release:
-  * [CHANGELOG-1.3.md][13]
  * [Unreleased Changes][0]

 ## Older releases:
+  * [CHANGELOG-1.2.md][12]
  * [CHANGELOG-1.1.md][11]
  * [CHANGELOG-1.0.md][10]
  * [CHANGELOG-0.11.md][9]
@@ -1,58 +1,58 @@
-## v1.3.0-beta.2
-#### 2020-02-24
+## v1.3.0
+#### 2020-03-02

 ### Download
-https://github.com/vmware-tanzu/velero/releases/tag/v1.3.0-beta.2
+https://github.com/vmware-tanzu/velero/releases/tag/v1.3.0

 ### Container Image
-`velero/velero:v1.3.0-beta.2`
+`velero/velero:v1.3.0`

 ### Documentation
-https://velero.io/docs/v1.3.0-beta.2/
+https://velero.io/docs/v1.3.0/

 ### Upgrading
-```bash
-kubectl set image \
-  --namespace velero \
-  deployment/velero velero=velero/velero:v1.3.0-beta.2
+https://velero.io/docs/v1.3.0/upgrade-to-1.3/
+
+### Highlights
+
+#### Custom Resource Definition Backup and Restore Improvements
+
+This release includes a number of related bug fixes and improvements to how Velero backs up and restores custom resource definitions (CRDs) and instances of those CRDs.
+
+We found and fixed three issues around restoring CRDs that were originally created via the `v1beta1` CRD API.  The first issue affected CRDs that  had the `PreserveUnknownFields` field set to `true`.  These CRDs could not be restored into 1.16+ Kubernetes clusters, because the `v1` CRD API does not allow this field to be set to `true`. We added code to the restore process to check for this scenario, to set the `PreserveUnknownFields` field to `false`, and to instead set `x-kubernetes-preserve-unknown-fields` to `true` in the OpenAPIv3 structural schema, per Kubernetes guidance. For more information on this, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#pruning-versus-preserving-unknown-fields). The second issue affected CRDs without structural schemas. These CRDs need to be backed up/restored through the `v1beta1` API, since all CRDs created through the `v1` API must have structural schemas. We added code to detect these CRDs and always back them up/restore them through the `v1beta1` API. Finally, related to the previous issue, we found that our restore code was unable to handle backups with multiple API versions for a given resource type, and we’ve remediated this as well.
+
+We also improved the CRD restore process to enable users to properly restore CRDs and instances of those CRDs in a single restore operation. Previously, users found that they needed to run two separate restores: one to restore the CRD(s), and another to restore instances of the CRD(s).  This was due to two deficiencies in the Velero code. First, Velero did not wait for a CRD to be fully accepted by the Kubernetes API server and ready for serving before moving on; and second, Velero did not refresh its cached list of available APIs in the target cluster after restoring CRDs, so it was not aware that it could restore instances of those CRDs.
+
+We fixed both of these issues by (1) adding code to wait for CRDs to be “ready” after restore before moving on, and (2) refreshing the cached list of APIs after restoring CRDs, so any instances of newly-restored CRDs could subsequently be restored.
+
+With all of these fixes and improvements in place, we hope that the CRD backup and restore experience is now seamless across all supported versions of Kubernetes.
+
+
+#### Multi-Arch Docker Images
+
+Thanks to community members [@Prajyot-Parab](https://github.com/Prajyot-Parab) and [@shaneutt](https://github.com/shaneutt), Velero now provides multi-arch container images by using Docker manifest lists.  We are currently publishing images for `linux/amd64`, `linux/arm64`, `linux/arm`, and `linux/ppc64le` in [our Docker repository](https://hub.docker.com/r/velero/velero/tags?page=1&name=v1.3&ordering=last_updated).
+
+Users don’t need to change anything other than updating their version tag - the v1.3 image is `velero/velero:v1.3.0`, and Docker will automatically pull the proper architecture for the host.
+
+For more information on manifest lists, see [Docker’s documentation](https://docs.docker.com/registry/spec/manifest-v2-2/). 
+
+
+#### Bug Fixes, Usability Enhancements, and More
+
+We fixed a large number of bugs and made some smaller usability improvements in this release. Here are a few highlights:
+
+- Support private registries with custom ports for the restic restore helper image ([PR #1999](https://github.com/vmware-tanzu/velero/pull/1999), [@cognoz](https://github.com/cognoz))
+- Use AWS profile from BackupStorageLocation when invoking restic ([PR #2096](https://github.com/vmware-tanzu/velero/pull/2096), [@dinesh](https://github.com/dinesh))
+- Allow restores from schedules in other clusters ([PR #2218](https://github.com/vmware-tanzu/velero/pull/2218), [@cpanato](https://github.com/cpanato))
+- Fix memory leak & race condition in restore code ([PR #2201](https://github.com/vmware-tanzu/velero/pull/2201), [@skriss](https://github.com/skriss))

-# if using restic:
-kubectl set image \
-  --namespace velero \
-  daemonset/restic restic=velero/velero:v1.3.0-beta.2
-```

 ### All Changes
+  * Corrected the selfLink for Backup CR in site/docs/master/output-file-format.md (#2292, @RushinthJohn)
  * Back up schema-less CustomResourceDefinitions as v1beta1, even if they are retrieved via the v1 endpoint. (#2264, @nrb)
  * Bug fix: restic backup volume snapshot to the second location failed (#2244, @jenting)
  * Added support of using PV name from volumesnapshotter('SetVolumeID') in case of PV renaming during the restore (#2216, @mynktl)
  * Replaced deprecated helm repo url at all it appearance at docs. (#2209, @markrity)
-
-## v1.3.0-beta.1
-#### 2020-02-04
-
-### Download
-https://github.com/vmware-tanzu/velero/releases/tag/v1.3.0-beta.1
-
-### Container Image
-`velero/velero:v1.3.0-beta.1`
-
-### Documentation
-https://velero.io/docs/v1.3.0-beta.1/
-
-### Upgrading
-```bash
-kubectl set image \
-  --namespace velero \
-  deployment/velero velero=velero/velero:v1.3.0-beta.1
-
-# if using restic:
-kubectl set image \
-  --namespace velero \
-  daemonset/restic restic=velero/velero:v1.3.0-beta.1
-```
-
-### All Changes
  * added support for arm and arm64 images (#2227, @shaneutt)
  * when restoring from a schedule, validate by checking for backup(s) labeled with the schedule name rather than existence of the schedule itself, to allow for restoring from deleted schedules and schedules in other clusters (#2218, @cpanato)
  * bug fix: back up server-preferred version of CRDs rather than always the `v1beta1` version (#2230, @skriss)
@@ -1 +0,0 @@
-added support for ppc64le images and manifest lists
@@ -1 +0,0 @@
-Wait for CustomResourceDefinitions to be ready before restoring CustomResources. Also refresh the resource list from the Kubernetes API server after restoring CRDs in order to properly restore CRs.
@@ -1 +0,0 @@
-add support for a private registry with a custom port in a restic-helper image
@@ -1 +0,0 @@
-return better error message to user when cluster config can't be found via `--kubeconfig`, `$KUBECONFIG`, or in-cluster config
@@ -1 +0,0 @@
-remove the `fsfreeze-pause` image being published from this repo; replace it with `ubuntu:bionic` in the nginx example app
@@ -1 +0,0 @@
-bug fix: deep-copy backup's labels when constructing snapshot tags, so the PV name isn't added as a label to the backup
@@ -1 +0,0 @@
-Enableing Velero to switch credentials (`AWS_PROFILE`) if multiple s3-compatible backupLocations are present
@@ -1 +0,0 @@
-bug fix: don't restore cluster-scoped resources when restoring specific namespaces and IncludeClusterResources is nil
@@ -1 +0,0 @@
-bug fix: restore both `replicasets.apps` *and* `replicasets.extensions` before `deployments`
@@ -1 +0,0 @@
-bug fix: only prioritize restoring `replicasets.apps`, not `replicasets.extensions`
@@ -1 +0,0 @@
-Enable pruning unknown CRD fields
@@ -1 +0,0 @@
-repopulate backup_last_successful_timestamp metrics for each schedule after server restart
@@ -1 +0,0 @@
-When restoring a v1 CRD with PreserveUnknownFields = True, make sure that the preservation behavior is maintained by copying the flag into the Open API V3 schema, but update the flag so as to allow the Kubernetes API server to accept the CRD without error.
@@ -1 +0,0 @@
-Bug fix: Check for nil LastMaintenanceTime in ResticRepository dueForMaintenance
@@ -1 +0,0 @@
-bug fix: fix race condition resulting in restores sometimes succeeding despite restic restore failures
@@ -1 +0,0 @@
-Replaced deprecated helm repo url at all it appearance at docs.
@@ -1 +0,0 @@
-bump restic to 0.9.6 to fix some issues with non AWS standard regions
@@ -1 +0,0 @@
-Added support of using PV name from volumesnapshotter('SetVolumeID') in case of PV renaming during the restore
@@ -1 +0,0 @@
-remove the schedule validation and instead of checking the schedule because we might be in another cluster we check if a backup exist with the schedule name.
@@ -1 +0,0 @@
-added support for arm and arm64 images
@@ -1 +0,0 @@
-bug fix: back up server-preferred version of CRDs rather than always the `v1beta1` version
@@ -1 +0,0 @@
-Bug fix: restic backup volume snapshot to the second location failed
@@ -1 +0,0 @@
-Back up schema-less CustomResourceDefinitions as v1beta1, even if they are retrieved via the v1 endpoint.
@@ -1 +0,0 @@
-Corrected the selfLink for Backup CR in site/docs/master/output-file-format.md
@@ -56,10 +56,10 @@ defaults:
      gh: https://github.com/vmware-tanzu/velero/tree/master
      layout: "docs"
  - scope:
-      path: docs/v1.3.0-beta.2
+      path: docs/v1.3.0
    values:
-      version: v1.3.0-beta.2
-      gh: https://github.com/vmware-tanzu/velero/tree/v1.3.0-beta.2
+      version: v1.3.0
+      gh: https://github.com/vmware-tanzu/velero/tree/v1.3.0
      layout: "docs"
  - scope:
      path: docs/v1.2.0
@@ -157,10 +157,10 @@ collections:
  - casestudies

 versioning: true
-latest: v1.2.0
+latest: v1.3.0
 versions:
 - master
- v1.3.0-beta.2
+- v1.3.0
 - v1.2.0
 - v1.1.0
 - v1.0.0
@@ -13,8 +13,8 @@ toc:
        url: /basic-install
      - page: Customize Installation
        url: /customize-installation
-      - page: Upgrade to 1.2
-        url: /upgrade-to-1.2
+      - page: Upgrade to 1.3
+        url: /upgrade-to-1.3
      - page: Supported providers
        url: /supported-providers
      - page: Evaluation install 
@@ -3,7 +3,7 @@
 # that the navigation for older versions still work.

 master: master-toc
-v1.3.0-beta.2: v1-3-0-beta-2-toc
+v1.3.0: v1-3-0-toc
 v1.2.0: v1-2-0-toc
 v1.1.0: v1-1-0-toc
 v1.0.0: v1-0-0-toc
@@ -13,8 +13,8 @@ toc:
        url: /basic-install
      - page: Customize Installation
        url: /customize-installation
-      - page: Upgrade to 1.2
-        url: /upgrade-to-1.2
+      - page: Upgrade to 1.3
+        url: /upgrade-to-1.3
      - page: Supported providers
        url: /supported-providers
      - page: Evaluation install 
@@ -39,6 +39,8 @@ toc:
        url: /namespace
      - page: Extend with hooks
        url: /hooks
+      - page: CSI Support (beta)
+        url: /csi
  - title: Plugins
    subfolderitems:
      - page: Overview
@@ -27,7 +27,7 @@ If you encounter issues, review the [troubleshooting docs][30], [file an issue][

 ## 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.3.0-beta.2/start-contributing/) documentation for guidance on how to setup Velero for development.
+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.3.0/start-contributing/) documentation for guidance on how to setup Velero for development.

 ## Changelog

@@ -52,7 +52,7 @@ Example:

 We use a package to generate mocks for our interfaces.

-Example: if you want to change this mock: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/pkg/restic/mocks/restorer.go
+Example: if you want to change this mock: https://github.com/vmware-tanzu/velero/blob/v1.3.0/pkg/restic/mocks/restorer.go

 Run:

@@ -241,5 +241,5 @@ After creating the Velero server in your cluster, try this example:

 ## Additional Reading 

-* [Official Velero Documentation](https://velero.io/docs/v1.3.0-beta.2/)
+* [Official Velero Documentation](https://velero.io/docs/v1.3.0/)
 * [Oracle Cloud Infrastructure Documentation](https://docs.cloud.oracle.com/)
@@ -0,0 +1,15 @@
+# Container Storage Interface Snapshot Support in Velero
+
+_This feature is under development. Documentation may not be up-to-date and features may not work as expected._
+
+Velero supports taking Container Storage Interface (CSI) snapshots as a beta feature on clusters that meet the following prerequisites.
+
+ 1. The cluster is Kubernetes version 1.17 or greater.
+ 1. The cluster is running a CSI driver capable of support volume snapshots at the [v1beta1 API level](https://kubernetes.io/blog/2019/12/09/kubernetes-1-17-feature-cis-volume-snapshot-beta/).
+ 1. The Velero server is running with the `--features EnableCSI` feature flag to enable CSI logic in Velero's core.
+ 1. The Velero [CSI plugin](https://github.com/vmware-tanzu/velero-plugin-for-csi/) is installed to integrate with the CSI volume snapshot APIs.
+
+# Roadmap
+
+Velero's support level for CSI volume snapshotting will follow upstream Kubernetes support for it, and will reach general availability sometime
+after volume snapshotting is GA in upstream Kubernetes. Beta support is expected to launch in Velero v1.4.
@@ -87,5 +87,5 @@ Once parsed into a `[]string`, the features can then be registered using the `Ne
 Velero adds the `LD_LIBRARY_PATH` into the list of environment variables to provide the convenience for plugins that requires C libraries/extensions in the runtime.

 [1]: https://github.com/vmware-tanzu/velero-plugin-example
-[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/pkg/plugin/logger.go
-[3]: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/pkg/restore/restic_restore_action.go
+[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0/pkg/plugin/logger.go
+[3]: https://github.com/vmware-tanzu/velero/blob/v1.3.0/pkg/restore/restic_restore_action.go
@@ -22,7 +22,7 @@ Examples of cases where Velero is useful:

 Yes, with some exceptions. For example, when Velero restores pods it deletes the `nodeName` from the
 pod so that it can be scheduled onto a new node. You can see some more examples of the differences
-in [pod_action.go](https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/pkg/restore/pod_action.go)
+in [pod_action.go](https://github.com/vmware-tanzu/velero/blob/v1.3.0/pkg/restore/pod_action.go)

 ## I'm using Velero in multiple clusters. Should I use the same bucket to store all of my backups?

@@ -77,5 +77,5 @@ velero backup logs nginx-hook-test | grep hookCommand


 [1]: api-types/backup.md
-[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/examples/nginx-app/with-pv.yaml
+[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0/examples/nginx-app/with-pv.yaml
 [3]: cloud-common.md
@@ -22,7 +22,7 @@ rootBucket/
  "metadata": {
    "name": "test-backup",
    "namespace": "velero",
-    "selfLink": "/apis/velero.io/v1/namespaces/velero/backups/testtest",
+    "selfLink": "/apis/velero.io/v1/namespaces/velero/backups/test-backup",
    "uid": "a12345cb-75f5-11e7-b4c2-abcdef123456",
    "resourceVersion": "337075",
    "creationTimestamp": "2017-07-31T13:39:15Z"
@@ -17,5 +17,5 @@ Please browse our list of resources, including a playlist of past online communi

 If you are ready to jump in and test, add code, or help with documentation, please use the navigation on the left under `Contribute`.

-[1]: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/CODE_OF_CONDUCT.md
-[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/CONTRIBUTING.md
+[1]: https://github.com/vmware-tanzu/velero/blob/v1.3.0/CODE_OF_CONDUCT.md
+[2]: https://github.com/vmware-tanzu/velero/blob/v1.3.0/CONTRIBUTING.md
@@ -23,7 +23,7 @@ If you're not yet running Velero v1.2, see the following:

    ```bash
    Client:
-        Version: v1.3.0-beta.2
+        Version: v1.3.0
        Git commit: <git SHA>
    ```

@@ -31,12 +31,12 @@ If you're not yet running Velero v1.2, see the following:

    ```bash
    kubectl set image deployment/velero \
-        velero=velero/velero:v1.3.0-beta.2 \
+        velero=velero/velero:v1.3.0 \
        --namespace velero

    # optional, if using the restic daemon set
    kubectl set image daemonset/restic \
-        restic=velero/velero:v1.3.0-beta.2 \
+        restic=velero/velero:v1.3.0 \
        --namespace velero
    ```

@@ -50,11 +50,11 @@ If you're not yet running Velero v1.2, see the following:

    ```bash
    Client:
-        Version: v1.3.0-beta.2
+        Version: v1.3.0
        Git commit: <git SHA>

    Server:
-        Version: v1.3.0-beta.2
+        Version: v1.3.0
    ```

 [0]: basic-install.md#install-the-cli
@@ -18,7 +18,7 @@ Alternatively, for quickly loading the website, under the `velero/site/` directo
 bundle exec jekyll serve --livereload --future
 ```

-For more information on how to run the website locally, please see our [jekyll documentation](https://github.com/vmware-tanzu/velero/blob/v1.3.0-beta.2/site/README-JEKYLL.md).
+For more information on how to run the website locally, please see our [jekyll documentation](https://github.com/vmware-tanzu/velero/blob/v1.3.0/site/README-JEKYLL.md).

 ## Adding a blog post
				`@@ -1 +0,0 @@`
				`added support for ppc64le images and manifest lists`
				`@@ -1 +0,0 @@`
				`Wait for CustomResourceDefinitions to be ready before restoring CustomResources. Also refresh the resource list from the Kubernetes API server after restoring CRDs in order to properly restore CRs.`
				`@@ -1 +0,0 @@`
				`add support for a private registry with a custom port in a restic-helper image`
				`@@ -1 +0,0 @@`
				return better error message to user when cluster config can't be found via `--kubeconfig`, `$KUBECONFIG`, or in-cluster config
				`@@ -1 +0,0 @@`
				remove the `fsfreeze-pause` image being published from this repo; replace it with `ubuntu:bionic` in the nginx example app
				`@@ -1 +0,0 @@`
				`bug fix: deep-copy backup's labels when constructing snapshot tags, so the PV name isn't added as a label to the backup`
				`@@ -1 +0,0 @@`
				Enableing Velero to switch credentials (`AWS_PROFILE`) if multiple s3-compatible backupLocations are present
				`@@ -1 +0,0 @@`
				`bug fix: don't restore cluster-scoped resources when restoring specific namespaces and IncludeClusterResources is nil`
				`@@ -1 +0,0 @@`
				bug fix: restore both `replicasets.apps` and `replicasets.extensions` before `deployments`
				`@@ -1 +0,0 @@`
				bug fix: only prioritize restoring `replicasets.apps`, not `replicasets.extensions`