Skip to content

Commit

Permalink
Small docs updates
Browse files Browse the repository at this point in the history 
Four small changes:
1. The notice about 1.4.0 was stale now that we've released newer
   version(s).
2. The build-from-source instructions were hard to copy/paste because
   they required interactive input.
3. The CSI driver wasn't mentioned in the docs.
4. The AUR repo is unmaintained (not updated since last July), so we
   shouldn't point customers to it.

I also did a little bit of minor clarifying/editing.

Signed-off-by: James Bornholt <[email protected]>
  • Loading branch information
@jamesbornholt
jamesbornholt committed Mar 11, 2024
1 parent 81ae0da commit d2ed32e
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 47 deletions.
19 changes: 9 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,7 @@ but probably not the right fit for applications that:
* make edits to existing files (don't work on your Git repository or run `vim` in Mountpoint 😄)

Mountpoint for Amazon S3 does not implement all the features of a POSIX file system, and there are some differences that may affect compatibility with your application. See [Mountpoint file system behavior](doc/SEMANTICS.md) for a detailed description of Mountpoint for Amazon S3's behavior and POSIX support and how they could affect your application.

> [!NOTE]
> For troubleshooting file operations which may not be supported by Mountpoint, see the [troubleshooting documentation](doc/TROUBLESHOOTING.md).
To troubleshoot file operations that may not be supported by Mountpoint, see the [troubleshooting documentation](doc/TROUBLESHOOTING.md).

## Current status

Expand All @@ -26,7 +24,7 @@ Mountpoint for Amazon S3 is generally available! We're tracking future feature d
### Notices

> [!IMPORTANT]
> Mountpoint for Amazon S3 v1.4.0 released on January 26, 2024, contains an issue that causes intermittent read failures. Amazon S3 fixed the issue and released Mountpoint for Amazon S3 v1.4.1 on February 16, 2024.
> Mountpoint for Amazon S3 v1.4.0, released on January 26, 2024, contains an [issue](https://github.com/awslabs/mountpoint-s3/pull/751) that causes intermittent read failures. We recommend that customers using v1.4.0 upgrade to v1.4.1 or later.
## Getting started

Expand All @@ -41,12 +39,13 @@ On Ubuntu, use these commands instead (for Graviton instances, replace `x86_64`
sudo apt-get install -y ./mount-s3.deb

> [!NOTE]
> See [Installing Mountpoint for Amazon S3](https://github.com/awslabs/mountpoint-s3/blob/main/doc/INSTALL.md) for detailed instructions and other installation options (including Docker or building from source).
> See [Installing Mountpoint for Amazon S3](https://github.com/awslabs/mountpoint-s3/blob/main/doc/INSTALL.md) for detailed instructions and other installation options, including the [Mountpoint for Amazon S3 CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/s3-csi.html) for Kubernetes applications, or building from source.
Once you've got Mountpoint for Amazon S3 installed, you can mount your Amazon S3 bucket.
You'll need valid AWS credentials to access your bucket;
for example, Mountpoint will automatically use credentials from [an IAM role associated with your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html),
or you can use the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
You'll need valid AWS credentials to access your bucket.
Mountpoint will automatically use credentials from [an IAM role associated with your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html),
or the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables,
or from [several other sources](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md#aws-credentials).

To mount your bucket, run this command,
replacing `DOC-EXAMPLE-BUCKET` with the name of your bucket
Expand All @@ -64,8 +63,8 @@ When you're finished accessing your bucket, you can unmount it (you might need `

umount /path/to/mount

> [!IMPORTANT]
> See [Configuring Mountpoint for Amazon S3](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md) for more details on how to configure and use Mountpoint, including options for providing AWS credentials.
> [!NOTE]
> See [Configuring Mountpoint for Amazon S3](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md) for more details on how to configure and use Mountpoint.
### Compatibility with other storage services

Expand Down
72 changes: 35 additions & 37 deletions doc/INSTALL.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# Installing Mountpoint for Amazon S3

We recommend installing Mountpoint for Amazon S3 by downloading and installing prebuilt packages using the command line.
Other installation options are also available, but are not officially supported by AWS.
We recommend installing Mountpoint for Amazon S3 by [downloading and installing prebuilt packages using the command line](#download-and-install-mountpoint-for-amazon-s3-from-the-command-line),
or [using the Mountpoint for Amazon S3 CSI driver for Kubernetes](#install-in-a-kubernetes-cluster-with-the-mountpoint-for-amazon-s3-csi-driver).
Other installation options are also available.

Mountpoint for Amazon S3 is only available for Linux operating systems.

## Download and install Mountpoint for Amazon S3 from the command line (recommended)
## Download and install Mountpoint for Amazon S3 from the command line

The instructions for downloading and installing Mountpoint for Amazon S3 depend on which Linux operating system you are using.

Expand Down Expand Up @@ -147,58 +148,55 @@ To verify the authenticity and integrity of a downloaded Mountpoint for Amazon S
```
The output should report a `Good signature`. If the output includes the phrase `BAD signature`, re-download the Mountpoint for Amazon S3 package file and repeat these steps. If the issue persists, do not finish installing Mountpoint for Amazon S3. The output may include a warning about a trusted signature. This does not indicate a problem, only that you have not independently verified the Mountpoint for Amazon S3 public key.
## Install in a Kubernetes cluster with the Mountpoint for Amazon S3 CSI driver
To use Mountpoint for Amazon S3 with applications running in a Kubernetes cluster,
we recommend installing and using the [Mountpoint for Amazon S3 CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/s3-csi.html).
You can install the CSI driver on a self-managed Kubernetes cluster by following its [installation instructions](https://github.com/awslabs/mountpoint-s3-csi-driver/blob/main/docs/install.md#installation),
or if you use Amazon EKS,
it is also available as an [EKS managed add-on](https://docs.aws.amazon.com/eks/latest/userguide/s3-csi.html).
## Running Mountpoint for Amazon S3 in a Docker container
You can run Mountpoint for Amazon S3 in a Docker container using our provided Dockerfiles.
We don't recommend this option, as running a FUSE file system like Mountpoint inside a container
requires giving the container broad root-level privileges to your host system.
See [Running Mountpoint for Amazon S3 in a Docker container](../docker/README.md) for instructions on using Mountpoint with Docker.
## Installing previous Mountpoint for Amazon S3 releases
We recommend always installing the latest Mountpoint for Amazon S3 release,
but if you need to install a previous version,
you can find links to them on the [GitHub Releases](https://github.com/awslabs/mountpoint-s3/releases) page.
## Building Mountpoint for Amazon S3 from source
You can build Mountpoint for Amazon S3 from source. However, binaries built in this way are not officially supported by AWS.
1. Install the necessary dependencies.
* For RPM-based distributions (Amazon Linux, Fedora, CentOS, RHEL, SUSE), enter the following command:
* For RPM-based distributions (Amazon Linux, Fedora, CentOS, RHEL), run the following command:
```
sudo yum install fuse fuse-devel cmake3 clang git pkgconfig
sudo yum install -y fuse fuse-devel cmake3 clang git pkgconfig
```
* For DEB-based distributions (Debian, Ubuntu), enter the following command:
* For DEB-based distributions (Debian, Ubuntu), run the following command:
```
sudo apt-get install fuse libfuse-dev cmake clang git pkg-config
sudo apt-get install -y fuse libfuse-dev cmake clang git pkg-config
```
2. Install the Rust compiler using [rustup](https://rustup.rs/) by entering the following commands:
2. Install the Rust compiler using [rustup](https://rustup.rs/):
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source "$HOME/.cargo/env"
```
3. Clone the Mountpoint for Amazon S3 source code from GitHub by entering the following command:
3. Clone the Mountpoint for Amazon S3 source code from GitHub:
```
git clone --recurse-submodules https://github.com/awslabs/mountpoint-s3.git
```
4. Build Mountpoint for Amazon S3 by entering the following commands:
4. Build Mountpoint for Amazon S3:
```
cd mountpoint-s3
cargo build --release
```
5. The final binary will be at `target/release/mount-s3`. Optionally, you can install this binary by copying it to the `/usr/bin` directory with the following command:
5. The final binary will be at `target/release/mount-s3`. Optionally, you can install this binary by copying it to the `/usr/bin` directory:
```
sudo cp target/release/mount-s3 /usr/bin/
```
## Running Mountpoint for Amazon S3 in a Docker container
You can run Mountpoint for Amazon S3 in a Docker container using our provided Dockerfiles.
We don't recommend this option, as running a FUSE file system like Mountpoint inside a container
requires giving the container broad root-level privileges to your host system.
See [Running Mountpoint for Amazon S3 in a Docker container](../docker/README.md) for instructions on using Mountpoint with Docker.
## Community-supported installation options
These installation options are not provided by AWS.
### Arch Linux
If you're using Arch Linux, you can use the unofficial [AUR](https://aur.archlinux.org/packages/mountpoint-s3-git) package. Using [Yay](https://github.com/Jguer/yay):
yay -S mountpoint-s3-git
## Installing previous Mountpoint for Amazon S3 releases
We recommend always installing the latest Mountpoint for Amazon S3 release,
but if you need to install a previous version,
you can find links to them on the [GitHub Releases](https://github.com/awslabs/mountpoint-s3/releases) page.

0 comments on commit d2ed32e

Please sign in to comment.