Outscale Block Storage Unit (BSU) CSI Driver

NEW: Helm chart rewrite. See migration guide for more information.

---

🌐 Links

• Project repo: github.com/outscale/osc-bsu-csi-driver
• Helm chart: osc-bsu-csi-driver
• 🤝 Contribution Guide: CONTRIBUTING.md
• Join our community on Discord

---

📄 Table of Contents

• Overview
• Compatibility
• Features
• Kubernetes Usage
• Configuration (StorageClass Parameters)
• Installation
• Troubleshooting
• Upgrade Notes
• Examples
• Development
• Contributing
• License

---

🧭 Overview

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.

We currently maintain two branches: v1.x (main) and v0.x (OSC-MIGRATION). If you use v0.x, see the migration guide: Upgrading from v0.x to v1.0.0. v0.x will continue to receive bug and CVE fixes while in use, but no new features will be added.

---

🔗 Compatibility

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	v1.12.0	1.25

---

✨ Features

The CSI driver is based on two services:

• Controller service: runs as a Deployment on control-plane nodes; calls the Outscale API to create, modify, attach/detach and delete volumes and snapshots,
• Node service: runs as a DaemonSet on 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 and iopsPerGB can 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.

---

☸️ Kubernetes Usage

• 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).

---

🛠 Configuration (StorageClass Parameters)

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.
iopsPerGB	integer	—	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.

---

📦 Installation

See Deploy for step-by-step installation (Helm/Manifests) and cluster-specific notes.

Chart configuration: see Helm Chart Configuration.

---

🐞 Troubleshooting

Common issues and diagnostics are covered in Troubleshooting.

---

⬆️ Upgrade Notes

Upgrading from v0.x to v1.0.0

Follow the migration guide.

Upgrading from v1.6 to v1.7

maxBsuVolumes is now computed automatically at driver startup. Manual configuration is usually unnecessary, even when multiple BSU volumes are mounted by the OS.

Upgrading to Helm chart v2

Most values have been renamed, and need to be set again using the new names during the upgrade. Please refer to the upgrade guide.

---

💡 Examples

• Dynamic Provisioning
• Block Volume
• Volume Snapshot
• StorageClasses
• Volume Resizing
• Volume Updates (VolumeAttributeClasses)
• Encryption

---

🧪 Development

See Development Process.

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before opening a pull request.

---

📜 License

© 2025 Outscale SAS

This project complies with the REUSE Specification.

See LICENSES/ directory for full license information.