README
¶
Mountpoint for Amazon S3 CSI Driver
[!TIP] Mountpoint for Amazon S3 CSI Driver v2 is available!
The v2 introduces Mountpoint Pod sharing, EKS Pod Identity support, support for running on SELinux-enabled environments like ROSA, simplified caching configuration and more!
See Mountpoint for Amazon S3 CSI Driver v2 for new features, and Upgrading Mountpoint for Amazon S3 CSI Driver from v1 to v2 for more details on breaking changes and necessary steps for upgrading to v2.
Overview
The Mountpoint for Amazon S3 Container Storage Interface (CSI) Driver allows your Kubernetes applications to access Amazon S3 objects through a file system interface. Built on Mountpoint for Amazon S3, the Mountpoint CSI driver presents an Amazon S3 bucket as a storage volume accessible by containers in your Kubernetes cluster. The Mountpoint CSI driver implements the CSI specification for container orchestrators (CO) to manage storage volumes.
For Amazon EKS clusters, the Mountpoint for Amazon S3 CSI driver is also available as an EKS add-on to provide automatic installation and management.
Features
- Static Provisioning - Associate an existing S3 bucket with a PersistentVolume (PV) for consumption within Kubernetes.
- Mount Options - Mount options can be specified in the PersistentVolume (PV) resource to define how the volume should be mounted. For Mountpoint-specific options, take a look at the Mountpoint docs for configuration.
- Mountpoint Pod Sharing - Multiple workloads can share a single Mountpoint instance when appropriate, improving resource utilization. See Mountpoint Pod Sharing for more details.
- Managed Local Cache - Use an emptyDir or a generic ephemeral volume as a local cache with Mountpoint. See Caching Configuration for more details.
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 for a detailed description of Mountpoint's behavior and POSIX support and how they could affect your application.
Installation
The S3 CSI Driver is distributed through the following supported channels:
- EKS Addon (recommended for EKS clusters) — see Amazon EKS guide
- Helm repository —
helm repo add aws-mountpoint-s3-csi-driver https://awslabs.github.io/mountpoint-s3-csi-driver
[!WARNING] Installing directly from a GitHub branch (
main,release-X.Y, or any other) is not supported. Charts in the GitHub repository may reference unreleased images or contain in-progress changes that are incompatible with published binaries. Please migrate to the Helm repository or EKS Addon installation methods.
See Driver Installation for detailed instructions.
Container Images
| Driver Version | ECR Public Image |
|---|---|
| v2.8.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.8.0 |
Previous Images
| Driver Version | ECR Public Image |
|---|---|
| v2.7.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.7.0 |
| v2.6.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.6.0 |
| v2.5.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.5.0 |
| v2.4.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.4.1 |
| v2.4.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.4.0 |
| v2.3.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.3.0 |
| v2.2.2 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.2.2 |
| v2.2.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.2.1 |
| v2.2.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.2.0 |
| v2.1.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.1.0 |
| v2.0.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v2.0.0 |
| v1.15.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.15.0 |
| v1.14.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.14.1 |
| v1.14.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.14.0 |
| v1.13.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.13.0 |
| v1.12.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.12.0 |
| v1.11.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.11.0 |
| v1.10.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.10.0 |
| v1.9.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.9.0 |
| v1.8.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.8.1 |
| v1.8.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.8.0 |
| v1.7.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.7.0 |
| v1.6.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.6.0 |
| v1.5.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.5.1 |
| v1.4.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.4.0 |
| v1.3.1 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.3.1 |
| v1.3.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.3.0 |
| v1.2.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.2.0 |
| v1.1.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.1.0 |
| v1.0.0 | public.ecr.aws/mountpoint-s3-csi-driver/aws-mountpoint-s3-csi-driver:v1.0.0 |
Releases
The Mountpoint for S3 CSI Driver follows semantic versioning. The version will be bumped following the rules below:
- Significant breaking changes will be released as a
MAJORupdate. - New features will be released as a
MINORupdate. - Bug or vulnerability fixes will be released as a
PATCHupdate.
Monthly releases will contain at minimum a MINOR version bump, even if the content would normally be treated as a PATCH version.
Unstable Releases
Unstable versions (i.e., beta, alpha, or rc) are for testing purposes only and should not be used in production environments or with valuable data. The security and correctness of these releases are not guaranteed. Use unstable versions at your own risk.
Support
Support will be provided for the latest version, and we may backport bug fixes or vulnerabilities to it as well as the previous major version.
This policy is non-binding and subject to change.
Compatibility
The Mountpoint for S3 CSI Driver is compatible with Kubernetes versions v1.31+ and implements the CSI Specification v1.9.0. The driver supports x86-64 and arm64 architectures.
Distros Support Matrix
The following table provides the support status for various distros with regards to CSI Driver version:
| Distro | Stable | Removed | Currently Supported EKS Versions |
|---|---|---|---|
| Amazon Linux 2 | 1.0.0 | 2.8.0 | — |
| Amazon Linux 2023 | 1.0.0 | — | 1.31 – 1.36 |
| Ubuntu 20.04 | 1.0.0 | 2.5.0 | — |
| Ubuntu 22.04 | 1.0.0 | 2.8.0 | — |
| Ubuntu 24.04 | 2.0.0 | — | 1.31 – 1.36 |
| Bottlerocket >1.19.2 | 1.4.0 | — | 1.31 – 1.36 |
Documentation
- Driver Installation
- Configuring volumes and credentials
- Troubleshooting
- Kubernetes Static Provisioning Example
- Driver Uninstallation
- Development and Contributing
Contributing
We welcome contributions to the Mountpoint for Amazon S3 CSI driver! Please see CONTRIBUTING.md for more information on how to report bugs or submit pull requests.
Security
If you discover a potential security issue in this project we ask that you notify AWS Security via our vulnerability reporting page. Please do not create a public GitHub issue.
Code of conduct
This project has adopted the Amazon Open Source Code of Conduct. See CODE_OF_CONDUCT.md for more details.
License
This project is licensed under the Apache-2.0 License. It builds on a number of other awesome projects with open source licenses, and licenses for other projects can be found under the following locations in the CSI Driver's container image:
- Linux packages under
/usr/share/licenses/* - The CSI Driver's Go dependencies under
/LICENSES/*(starting from v1.15.0) - Mountpoint's Rust dependencies under
/mountpoint-s3/THIRD_PARTY_LICENSES
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aws-s3-csi-controller
command
`aws-s3-csi-controller` is the entrypoint binary for the CSI Driver's controller component.
|
`aws-s3-csi-controller` is the entrypoint binary for the CSI Driver's controller component. |
|
aws-s3-csi-daemonset-mounter
command
`aws-s3-csi-daemonset-mounter` is the entrypoint binary running on the secondary (mounter) DaemonSet.
|
`aws-s3-csi-daemonset-mounter` is the entrypoint binary running on the secondary (mounter) DaemonSet. |
|
aws-s3-csi-driver
command
|
|
|
aws-s3-csi-mounter
command
`aws-s3-csi-mounter` is the entrypoint binary running on Mountpoint Pods.
|
`aws-s3-csi-mounter` is the entrypoint binary running on Mountpoint Pods. |
|
pkg
|
|
|
api/v2
Package v2 contains API Schema definitions for the s3.csi.aws.com v2 API group.
|
Package v2 contains API Schema definitions for the s3.csi.aws.com v2 API group. |
|
driver/node/credentialprovider
Package credentialprovider provides utilities for obtaining AWS credentials to use.
|
Package credentialprovider provides utilities for obtaining AWS credentials to use. |
|
driver/node/credentialprovider/awsprofile
Package awsprofile provides utilities for creating and deleting AWS Profile (i.e., credentials & config files).
|
Package awsprofile provides utilities for creating and deleting AWS Profile (i.e., credentials & config files). |
|
driver/node/credentialprovider/awsprofile/awsprofiletest
Package awsprofiletest provides testing utilities for AWS Profiles.
|
Package awsprofiletest provides testing utilities for AWS Profiles. |
|
driver/node/credentialprovider/mocks
Package mock_credentialprovider is a generated GoMock package.
|
Package mock_credentialprovider is a generated GoMock package. |
|
driver/node/envprovider
Package envprovider provides utilities for accessing environment variables to pass Mountpoint.
|
Package envprovider provides utilities for accessing environment variables to pass Mountpoint. |
|
driver/node/mounter/mocks
Package mock_driver is a generated GoMock package.
|
Package mock_driver is a generated GoMock package. |
|
driver/node/volumecontext
Package volumecontext provides utilities for accessing volume context passed via CSI RPC.
|
Package volumecontext provides utilities for accessing volume context passed via CSI RPC. |
|
driver/version
Package version provides build- and run-time version information of the driver.
|
Package version provides build- and run-time version information of the driver. |
|
mountpoint/mounter
Package mounter provides functionalities for mounting and unmount Mountpoint instances.
|
Package mounter provides functionalities for mounting and unmount Mountpoint instances. |
|
mountpoint/mountoptions
Package mountoptions provides utilities for passing mount options between containers (e.g., Mountpoint and CSI Driver Node Pods) running in the same node.
|
Package mountoptions provides utilities for passing mount options between containers (e.g., Mountpoint and CSI Driver Node Pods) running in the same node. |
|
mountpoint/runner
Package runner provides utilities for running Mountpoint instances.
|
Package runner provides utilities for running Mountpoint instances. |
|
podmounter/mppod/watcher
Package watcher provides utilities for watching Mountpoint Pods in the cluster.
|
Package watcher provides utilities for watching Mountpoint Pods in the cluster. |
|
util/log
Package log provides shared klog initialization for CSI Driver components.
|
Package log provides shared klog initialization for CSI Driver components. |
|
util/testutil/assert
Package assert provides utilities for making assertions during tests.
|
Package assert provides utilities for making assertions during tests. |
|
tests
|
|
|
e2e-kubernetes
module
|