From d1d03390fd8fbdc6d8b8a00e53f666c081f58a3e Mon Sep 17 00:00:00 2001 From: Pavel Tcholakov Date: Fri, 6 Sep 2024 15:26:06 +0200 Subject: [PATCH 1/3] Add sections on backing up and upgrading Restate --- docs/operate/data-backup.mdx | 30 ++++++++++++++++++++++++++++++ docs/operate/upgrading.mdx | 30 ++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 docs/operate/data-backup.mdx create mode 100644 docs/operate/upgrading.mdx diff --git a/docs/operate/data-backup.mdx b/docs/operate/data-backup.mdx new file mode 100644 index 00000000..861dc3f4 --- /dev/null +++ b/docs/operate/data-backup.mdx @@ -0,0 +1,30 @@ +--- +sidebar_position: 8 +description: "Strategies for backing up and restoring the Restate data store" +--- + +import Admonition from '@theme/Admonition'; + +# Data Backup + + + Future versions of Restate will support distributed deployment with spanning multiple machnes enhancing the availability you can achieve with your Restate cluster. This document only covers single-node Restate deployments. + + +The Restate server persists both metadata (such as the details of deployed services, in-flight invocations) and data (e.g., virtual object and workflow state keys) in its data store, which is located in its base directory (by default, the `restate-data` path relative to the startup working directory). Restate is configured to perform write-ahead logging with fsync enabled to ensure that effects are fully persisted before being acknowledged to participating services. + +Backing up the full contents of the Restate base directory will ensure that you can recover this state in the event of a server failure. We recommend placing the data directory on fast block storage that supports atomic snapshots, such as Amazon EBS volume snapshots. Alternatively, you can stop the restate-server process, archive the base directory contents, and then restart the process. This ensures that the backup contains an atomic view of the persisted state. + +In addition to the data store, you should also make sure you have a back up of the effective Restate server configuration. Be aware that this may be spread across command line arguments, environment variables, and the server configuration file. + +## Restoring Backups + + + Restate cannot guarantee that it is the only instance of the given node. You must ensure that only one instance of any given Restate node is running when restoring the data store from a backup. Running multiple instances could lead to a "split-brain" scenario where different servers process invocations for the same set of services, causing state divergence. + + +To restore from backup, ensure the following: + +* Use a Restate server release that is compatible with the version that produced the data store snapshot. See the [Upgrading](upgrading) section. +* Use an equivalent [Restate server configuration](/operate/configuration/server). In particular, ensure that the `cluster-name` and `node-name` attributes match those of the previous Restate server operating on this data store. +* Exclusive access to a data store restored from the most recent atomic snapshot of the previous Restate installation. diff --git a/docs/operate/upgrading.mdx b/docs/operate/upgrading.mdx new file mode 100644 index 00000000..e6d70474 --- /dev/null +++ b/docs/operate/upgrading.mdx @@ -0,0 +1,30 @@ +--- +sidebar_position: 7 +description: "Restate installation software version upgrades, compatibility policy, rollback strategy" +--- + +# Upgrading Restate + +Restate follows [Semantic Versioning](https://semver.org/). The server persists compatibility markers which enable it to detect incompatible data versions. However, you should be careful to follow supported version migration paths and perform [data backups](data-backup) when performing software upgardes. + +## Version compatibility + + + Consult the release notes for the specific details of any new version when planning upgrades. + + +Upgrading to the latest patch version should always be possible and is recommended to benefit from the latest bug fixes and enhancements. + +Incremental minor version upgrades will retain functional compatibility with the immediate prior version. That is, for any minor version update, you will be able to upgrade from `x.y` to `x.(y+1)` while retaining all persisted data and metadata. You must not skip minor version upgrades, i.e. go directly from `x.y` to `x.(y+2)`, as it may bypass necessary data store migrations required for preserving forward compatibility. + +We recognize that unexpected compatibility issues may arise. For this reason, you can also downgrade a Restate installation to the latest patch level of the previous minor version. For example, you can safely rollback the Restate server versionf rom `x.(y).0` to `x.(y-1).z` if you encounter compatibility issues. However, this rollback is only supported if you have not used any new opt-in features exclusive to the newer version. You cannot downgrade more than one minor version behind the most recent version used with the data store using this approach. + +## Service compatibility + +Registered Restate services must use an SDK compatible with the service protocol version(s) of the running Restate server. Note that Restate SDKs follow independent versioning from the server. You can find the latest SDK compatibility matrix in the respective SDK version documentation. + +* [Restate Java SDK](https://github.com/restatedev/sdk-java#versions) +* [Restate TypeScript SDK](https://github.com/restatedev/sdk-typescript#versions) +* [Restate Go SDK](https://github.com/restatedev/sdk-go#versions) +* [Restate Python SDK](https://github.com/restatedev/sdk-python#versions) +* [Restate Rust SDK](https://github.com/restatedev/sdk-rust#versions) From 53baba98dc8caf7146d5731055da177663e821fd Mon Sep 17 00:00:00 2001 From: Pavel Tcholakov Date: Fri, 6 Sep 2024 15:51:25 +0200 Subject: [PATCH 2/3] Update docs/operate/upgrading.mdx Co-authored-by: Jack Kleeman --- docs/operate/upgrading.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operate/upgrading.mdx b/docs/operate/upgrading.mdx index e6d70474..79392441 100644 --- a/docs/operate/upgrading.mdx +++ b/docs/operate/upgrading.mdx @@ -17,7 +17,7 @@ Upgrading to the latest patch version should always be possible and is recommend Incremental minor version upgrades will retain functional compatibility with the immediate prior version. That is, for any minor version update, you will be able to upgrade from `x.y` to `x.(y+1)` while retaining all persisted data and metadata. You must not skip minor version upgrades, i.e. go directly from `x.y` to `x.(y+2)`, as it may bypass necessary data store migrations required for preserving forward compatibility. -We recognize that unexpected compatibility issues may arise. For this reason, you can also downgrade a Restate installation to the latest patch level of the previous minor version. For example, you can safely rollback the Restate server versionf rom `x.(y).0` to `x.(y-1).z` if you encounter compatibility issues. However, this rollback is only supported if you have not used any new opt-in features exclusive to the newer version. You cannot downgrade more than one minor version behind the most recent version used with the data store using this approach. +If you encounter any issues with a new version, you can downgrade a Restate installation to the latest patch level of the previous minor version. For example, you can safely rollback the Restate server version from `x.(y).0` to `x.(y-1).z` if you encounter compatibility issues. However, this rollback is only supported if you have not used any new opt-in features exclusive to the newer version. You cannot downgrade more than one minor version behind the most recent version used with the data store using this approach. ## Service compatibility From e4eef5a3dede1696e7a1665e290b741ec14a6bda Mon Sep 17 00:00:00 2001 From: Pavel Tcholakov Date: Fri, 6 Sep 2024 15:53:09 +0200 Subject: [PATCH 3/3] fix errors --- docs/operate/upgrading.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/operate/upgrading.mdx b/docs/operate/upgrading.mdx index 79392441..063e35e9 100644 --- a/docs/operate/upgrading.mdx +++ b/docs/operate/upgrading.mdx @@ -3,7 +3,9 @@ sidebar_position: 7 description: "Restate installation software version upgrades, compatibility policy, rollback strategy" --- -# Upgrading Restate +import Admonition from '@theme/Admonition'; + +# Upgrading Restate follows [Semantic Versioning](https://semver.org/). The server persists compatibility markers which enable it to detect incompatible data versions. However, you should be careful to follow supported version migration paths and perform [data backups](data-backup) when performing software upgardes.