opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-21 00:56:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

s3fs docs

Browse Source 
Signed-off-by: WesselAtWork <115667066+WesselAtWork@users.noreply.github.com>
This commit is contained in:
WesselAtWork
2024-02-12 18:08:22 +02:00
parent d470e7ee7d
commit d2143fac59
2 changed files with 98 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/source/markdown/podman-systemd.unit.5.md
View File

@ -1533,6 +1533,32 @@ Exec=sh -c "sleep inf"
Pod=test.pod
```
Example `s3fs.volume`:
For further details, please see the [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) project.
Remember to read the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ)
> NOTE: Enabling the cache massively speeds up access and write times on static files/objects.
> However, `use_cache` is [UNBOUNDED](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ#q-how-does-the-local-file-cache-work)!
> Be careful, it will fill up with any files accessed on the s3 bucket through the file system.
Please remember to set `S3_BUCKET`, `PATH`, `AWS_REGION`. `CACHE_DIRECTORY` should be set up by [systemd](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=)
```
[Service]
CacheDirectory=s3fs
ExecStartPre=/usr/local/bin/aws s3api put-object --bucket ${S3_BUCKET} --key ${PATH}/
[Volume]
Device=${S3_BUCKET}:/${PATH}
Type=fuse.s3fs
VolumeName=s3fs-volume
Options=iam_role,endpoint=${AWS_REGION},use_xattr,listobjectsv2,del_cache,use_cache=${CACHE_DIRECTORY}
# `iam_role` assumes inside EC2, if not, Use `profile=` instead
```
## SEE ALSO
**[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**,
**[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html)**,

73
docs/source/markdown/podman-volume-create.1.md
View File

@ -103,7 +103,7 @@ Create image named volume using the specified local image in containers/storage.
## QUOTAS
podman volume create uses `XFS project quota controls` for controlling the size and the number of inodes of builtin volumes. The directory used to store the volumes must be an `XFS` file system and be mounted with the `pquota` option.
`podman volume create` uses `XFS project quota controls` for controlling the size and the number of inodes of builtin volumes. The directory used to store the volumes must be an `XFS` file system and be mounted with the `pquota` option.
Example /etc/fstab entry:
```
@ -129,6 +129,77 @@ All containers are assigned larger project IDs (e.g. >= 100000).
All volume assigned project IDs larger project IDs starting with 200000.
This prevents xfs_quota management conflicts with containers/storage.
## MOUNT EXAMPLES
`podman volume create` allows the `type`, `device`, and `o` options to be passed to `mount(8)` when using the `local` driver.
## [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
[s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) or just `s3fs`, is a [fuse](https://github.com/libfuse/libfuse) filesystem that allows s3 prefixes to be mounted as filesystem mounts.
**Installing:**
```shell
$ doas dnf install s3fs-fuse
```
**Simple usage:**
```shell
$ s3fs --help
$ s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
```
**Equivalent through `mount(8)`**
```shell
$ mount -t fuse.s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
```
**Equivalent through `podman volume create`**
```shell
$ podman volume create s3fs-fuse-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=use_xattr,endpoint=aq-central-1
```
**The volume can then be mounted in a container with**
```shell
$ podman run -v s3fs-fuse-volume:/s3:z --rm -it fedora:latest
```
Please see the available [options](https://github.com/s3fs-fuse/s3fs-fuse/wiki/Fuse-Over-Amazon#options) on their wiki.
### Using with other container users
The above example works because the volume is mounted as the host user and inside the container `root` is mapped to the user in the host.
If the mount is accessed by a different user inside the container, a "Permission denied" error will be raised.
```shell
$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
$ ls /s3
# ls: /s3: Permission denied
```
In FUSE-land, mounts are protected for the user who mounted them; specify the `allow_other` mount option if other users need access.
> Note: This will remove the normal fuse [security measures](https://github.com/libfuse/libfuse/wiki/FAQ#why-dont-other-users-have-access-to-the-mounted-filesystem) on the mount point, after which, the normal filesystem permissions will have to protect it
```shell
$ podman volume create s3fs-fuse-other-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=allow_other,use_xattr,endpoint=aq-central-1
$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
$ ls /s3
```
### The Prefix must exist
`s3fs` will fail to mount if the prefix does not exist in the bucket.
Create a s3-directory by putting an empty object at the desired `prefix/` key
```shell
$ aws s3api put-object --bucket bucket --key prefix/
```
If performance is the priority, please check out the more performant [goofys](https://github.com/kahing/goofys).
> FUSE filesystems exist for [Google Cloud Storage](https://github.com/GoogleCloudPlatform/gcsfuse) and [Azure Blob Storage](https://github.com/Azure/azure-storage-fuse)
## SEE ALSO
**[podman(1)](podman.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[podman-volume(1)](podman-volume.1.md)**, **mount(8)**, **xfs_quota(8)**, **xfs_quota(8)**, **projects(5)**, **projid(5)**