NEW: Helm chart rewrite. See migration guide for more information.
- Project repo: github.com/outscale/osc-bsu-csi-driver
- Helm chart: osc-bsu-csi-driver
- 🤝 Contribution Guide: CONTRIBUTING.md
- Join our community on Discord
- Overview
- Compatibility
- Features
- Kubernetes Usage
- Configuration (StorageClass Parameters)
- Installation
- Troubleshooting
- Upgrade Notes
- Examples
- Development
- Contributing
- License
The Outscale Block Storage Unit (BSU) CSI Driver implements the Container Storage Interface (CSI) for OUTSCALE BSU volumes. It allows container orchestrators (e.g., Kubernetes) to provision, attach, mount, snapshot, modify and expand BSU volumes.
CSI Specification Compatibility Matrix
| Plugin Version | Compatible CSI Version | Minimum K8s version |
|---|---|---|
| <= v0.0.14beta | v1.3.0 | 1.16 |
| v0.0.15 | v1.5.0 | 1.20 |
| v0.1.0 – v1.3.0 | v1.5.0 | 1.20 |
| v0.1.0 – v1.6.x | v1.8.0 | 1.20 |
| v1.7.x - v1.8.x | v1.10.0 | 1.20 |
| v1.9.x | v1.10.0 | 1.20 |
| v1.10.x and later | v1.12.0 | 1.25 |
Recommended Kubernetes version: >= v1.34
The CSI driver is based on two services:
- Controller service: runs as a
Deploymenton control-plane nodes; calls the Outscale API to create, modify, attach/detach and delete volumes and snapshots, - Node service: runs as a
DaemonSeton all nodes requiring volumes; mounts, formats and resize filesystems.
The following CSI capabilities are supported by the driver:
Plugin capabilities
| Service | Support | Comments |
|---|---|---|
| CONTROLLER_SERVICE | ✅ | implements the controller service, handling calls the Outscale API to create/modify/attach/detach/delete volumes and snapshots |
| VOLUME_ACCESSIBILITY_CONSTRAINTS | ✅ | There are constraints limiting which volumes can be mounted on a specific node (e.g. belonging to the same subregion) |
| GROUP_CONTROLLER_SERVICE | ❌ | Volume and snapshot groups are not supported |
| SNAPSHOT_METADATA_SERVICE | ❌ | Snapshot metadata are not available |
| VolumeExpansion | Support | Comments |
|---|---|---|
| ONLINE | ✅ | Volumes can be resized while mounted |
Controller capabilities
| Capability | Support | Comments |
|---|---|---|
| CREATE_DELETE_VOLUME | ✅ | Volumes can be created |
| PUBLISH_UNPUBLISH_VOLUME | ✅ | Volumes need to be published on nodes |
| LIST_VOLUMES | ❌ | Volumes cannot be listed |
| GET_CAPACITY | ❌ | Total storage capacity is unknown |
| CREATE_DELETE_SNAPSHOT | ✅ | Snapshots can be created and used as a source for new volumes |
| LIST_SNAPSHOTS | ✅ | Snapshots can be listed |
| CLONE_VOLUME | ❌ | Volumes cannot be cloned |
| PUBLISH_READONLY | ❌ | Volumes cannot be published as read-only |
| EXPAND_VOLUME | ✅ | Volumes can be resized |
| LIST_VOLUMES_PUBLISHED_NODES | ❌ | LIST_VOLUME/GET_VOLUME additional capability |
| VOLUME_CONDITION | ❌ | The volume condition is not known |
| GET_VOLUME (alpha) | ❌ | The status of a volume is not reported |
| SINGLE_NODE_MULTI_WRITER | ❌ | Volumes cannot be accessed from multiple sources |
| MODIFY_VOLUME | ✅ | Volumes can be modified |
| GET_SNAPSHOT (alpha) | ❌ | The status of a snapshot is not reported |
Notes
- EXPAND_VOLUME: offline (cold/detached) and online (hot/attached) volumes can be resized.
- MODIFY_VOLUME:
volumeType,iopsandiopsPerGBcan be updated via VolumeAttributeClasses on both offline and online volumes.
Node capabilities
| Capability | Support | Comments |
|---|---|---|
| STAGE_UNSTAGE_VOLUME | ✅ | Volumes need to be staged on a node |
| GET_VOLUME_STATS | ✅ | The status of a volume is not reported |
| EXPAND_VOLUME | ✅ | Volumes can be resized |
| VOLUME_CONDITION | ❌ | The volume condition is not known |
| SINGLE_NODE_MULTI_WRITER | ❌ | Volumes cannot be accessed from multiple sources |
| VOLUME_MOUNT_GROUP | ❌ | Volumes mount groups are not supported |
Notes
- EXPAND_VOLUME: offline (cold/detached) and online (hot/attached) volumes can be resized.
- Static provisioning: import existing BSU volumes and mount via PVCs.
- Dynamic provisioning: create on-demand volumes via PVCs.
- Block volumes: raw block device support for latency-sensitive apps (e.g., MySQL).
- Volume snapshots: create and restore from snapshots.
- Volume encryption: LUKS +
cryptsetup.
Prerequisites
- A Kubernetes cluster within a compatible version range (see Compatibility).
- Driver access to OUTSCALE APIs using AK/SK credentials (for example via an EIM user with an appropriate policy such as
example-eim-policy.json).
These parameters are passed via the StorageClass to CreateVolumeRequest.parameters:
StorageClass parameters
| Parameter | Values | Default | Description |
|---|---|---|---|
csi.storage.k8s.io/fstype |
xfs, ext2/3/4 |
ext4 |
Filesystem to format the volume with. |
type |
io1, gp2, standard |
gp2 |
BSU volume type. |
iops |
integer | — | Either iops or iopsPerGB is required when type=io1; total IOPS. |
iopsPerGB |
integer | — | Either iops or iopsPerGB is required when type=io1; IOPS per GiB. |
encrypted |
true, false |
false |
Enable LUKS encryption. |
csi.storage.k8s.io/node-stage-secret-name |
string | — | Name of the node-stage secret (see CSI docs). |
csi.storage.k8s.io/node-stage-secret-namespace |
string | — | Namespace of the node-stage secret (see CSI docs). |
kmsKeyId |
string | — | Not yet supported. |
luks-cipher |
string | — | LUKS cipher; default depends on cryptsetup version. |
luks-hash |
string | — | Password derivation hash; default depends on cryptsetup version. |
luks-key-size |
string | — | Encryption key size; default depends on cryptsetup version. |
Notes
- Parameter names are case-sensitive.
See Deploy for step-by-step installation (Helm/Manifests) and cluster-specific notes.
Chart configuration: see Helm Chart Configuration.
Controller metrics
| Metric name | Type | Labels | Description |
|---|---|---|---|
| osc_csi_volume_iops | gauge | pvc, namespace, pv, storage_class, volume_attribute_class, volume_id, volume_type | IOPS configuration of volumes |
All metrics share the same base labels: instance and driver.
Node metrics
| Metric name | Type | Labels | Description |
|---|---|---|---|
| osc_csi_volume_attachments | gauge | pv, device | Volume attachment information |
| osc_csi_blockdevice_read_ops_total | counter | pv, device | The total number of completed read operations |
| osc_csi_blockdevice_write_ops_total | counter | pv, device | The total number of completed write operations |
| osc_csi_blockdevice_in_flight | gauge | pv, device | The number of I/Os currently in flight |
| osc_csi_blockdevice_time_in_queue_total | counter | pv, device | The total wait time, in milliseconds, for all requests |
All metrics share the same base labels: node, instance and driver.
Common issues and diagnostics are covered in Troubleshooting.
Volumes created by v1.12.0+ using iopsPerGB have their IOPS raised when resized.
Volumes created by a previous version will not be upgraded by default.
You can either:
- manually add tags to existing volumes:
octl iaas api CreateTags --ResourceIds vol-xxx,vol-xxx --Tags.0.Key CSIIOPSPerGB --Tags.0.Value <iopsPerGB value> --Tags.1.Key CSIUpdateIOPSOnResize --Tags.1.Value true
- configure the CSI driver to assume that all untagged volumes are configured using
iopsPerGBand raise IOPS when resizing to maintain a constant IOPS/size ratio:
helm [...] --set driver.updateIOPSOnResize=assume
Follow the migration guide.
maxBsuVolumes is now computed automatically at driver startup. Manual configuration is usually unnecessary, even when multiple BSU volumes are mounted by the OS.
Most values have been renamed, and need to be set again using the new names during the upgrade. Please refer to the upgrade guide.
- Dynamic Provisioning
- Block Volume
- Volume Snapshot
- StorageClasses
- Volume Resizing
- Volume Updates (VolumeAttributeClasses)
- Encryption
See Development Process.
Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before opening a pull request.
© 2025 Outscale SAS
This project complies with the REUSE Specification.
See LICENSES/ directory for full license information.