From 8756cae692eef2ac507c421a1b965f18801ba187 Mon Sep 17 00:00:00 2001 From: Christoph Herzog Date: Tue, 20 Aug 2024 09:00:54 +0200 Subject: [PATCH] Volumes documentation --- pages/edge/configuration.mdx | 24 ++++++ pages/edge/learn/_meta.json | 3 +- pages/edge/learn/volumes.mdx | 139 +++++++++++++++++++++++++++++++++++ 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 pages/edge/learn/volumes.mdx diff --git a/pages/edge/configuration.mdx b/pages/edge/configuration.mdx index 25b72d6..151756d 100644 --- a/pages/edge/configuration.mdx +++ b/pages/edge/configuration.mdx @@ -128,6 +128,30 @@ redirect: force_https: false ``` +### Volumes + +Configure persistent volume storage for your apps. + +*Note*: currently volumes are limited to a specific region, and provide +read-write-many semantics. +This means databases and other more complex use-cases will not work well just yet. + +Learn more about volumes [here](/edge/learn/volumes). + +```yaml filename="app.yaml" copy +volumes: + # A name for your volume. + # Must be unique for the given app. + - name: data + # Where to moint the volume into the filesystem. + # You can specify multiple mounts with optional subpaths. + mounts: + # Mount the volume to `/data`. + - mount_path: /data + # Optional: the subdirectory of the volume to mount. + # subpath: /subpath +``` + ### `capabilities` #### `instaboot` diff --git a/pages/edge/learn/_meta.json b/pages/edge/learn/_meta.json index 82c1888..02d6195 100644 --- a/pages/edge/learn/_meta.json +++ b/pages/edge/learn/_meta.json @@ -4,5 +4,6 @@ "deployment-modes": "Deployment Modes", "remote-sessions": "Remote Sessions", "connecting-domains-to-edge": "Connecting Custom Domains to Edge", - "secrets": "Secrets" + "secrets": "Secrets", + "volumes": "Volumes" } diff --git a/pages/edge/learn/volumes.mdx b/pages/edge/learn/volumes.mdx new file mode 100644 index 0000000..e448170 --- /dev/null +++ b/pages/edge/learn/volumes.mdx @@ -0,0 +1,139 @@ +import { Callout } from "nextra-theme-docs"; + +# Volumes + +Volumes provide persistent disk storage for applications. + +They also support remote access with any S3 compatible client. + + + +In the current initial implementation, volumes are restricted to a single +[Edge region](/edge/learn/regions). + +Volumes also at the moment only provide *read-write-many* semantics. +Due the automatic auto-scaling for apps, this means that volumes are not currently +well-suited for databases or other more complex use cases that require a single writer. + +Keep in mind that volumes can be accessed concurrently, and even from different +nodes. + +These restrictions (including the single-region restriction) will be lifted +in the future. + + +## Using Volumes With rclone + +* Every app may have multiple volumes. +* Each volume has a name, which must be unique for the application. +* Volumes can be mounted at a chosen path. +* Each volume can be mounted multiple times. + +Simply extend your [app configuration](/edge/configuration) with a `volumes` +section: + +```yaml filename="app.yaml" copy +# ... + +volumes: + # A name for your volume. + # Must be unique for the given app. + - name: data + # Where to mount the volume into the filesystem. + # You can specify multiple mounts with optional subpaths. + mounts: + # Mount the volume to `/data`. + - mount_path: /data + # Optional: the subdirectory of the volume to mount. + # subpath: /subpath +``` + +This will create a new "data" volume, which will be mounted at `/data`. + +Now just re-deploy your app with `wasmer deploy`. +The volume will be automatically created. + +Your application can now use the mount path and treat it as persistent storage. + + +The name of a volume acts as a unique identifier. +If you change the name the old volume - including it's data - will be deleted! + + +### Deleting Volumes + +To delete a volume, simply remove it from your app configuration and re-deploy. +The data will be purged, and your app will not have access to the volume anymore. + + +If you rename or remove a volume from the `app.yaml` configuration, +all data will be deleted when you deploy, and can not be recovered. + +Make sure this is what you want before deploying! + + +## Inspecting Volumes + +You can inspect volumes in two ways: + +* in the web frontend on your app dashboard: + Go to the "Storage" tab - you will see a list of volumes with their size. +* using the CLI: + Run `wasmer app volumes list [app]` to list all volumes and their sizes. + +## Remotely Accessing Volumes + +Volumes are not only available to your apps, but can also be remotely accessed +through the standard S3 API, or through a builtin web UI. + +You can use the CLI to retrieve S3 credentials: + +```bash +wasmer app volumes s3-credentials +``` + +This will print the S3 API URL, access key and secret key. + + + +You can visit the above URL in your browser to access a builtin web UI! + + +### Configuring rclone + +[rclone](https://rclone.org/) is a popular CLI client that allows full access +to your volumes. It even allows mounting a volume to your local machine! + +You can get an rclone configuration snippet through the CLI: + +```bash +wasmer app volumes s3-credentials --rclone-print +``` + +This will print out a configuration snippet that can be added to the rclone +configuration file. + + +The config file is usually located at `~/.config/rclone/rclone.conf`, but you +can retrieve the active path with `rclone config file`. + + + +Some examples of using rclone: + +(Note: replace `` with the name of the rclone target) + +```bash +# List all volumes in this app: +rclone lsd : + +# List files in a given volume: +rclone lsd : + +# Copy a file to a volume: +rclone copy ./local-filename :/remote-filename + +# Mount a volume to a local directory +mkdir my-volume +rclone mount : ./my-volume +```