README
¶
Introduction to PMEM-CSI for Kubernetes*
Intel PMEM-CSI is a CSI storage driver for container orchestrators like Kubernetes. It makes local persistent memory (PMEM) available as a filesystem volume to container applications. Currently, PMEM-CSI can utilize non-volatile memory devices that can be controlled via the libndctl utility library. In this readme, we use persistent memory to refer to a non-volatile dual in-line memory module (NVDIMM).
The v1.0 release is the latest feature release and is regularly updated with newer base images and bug fixes. 0.9 is still supported.
Documentation is part of the source code for each release and also available in rendered form for easier reading:
- latest 1.0.x release
- latest 0.9.x release
- latest 0.8.x release
- latest 0.7.x release
- latest documentation, in development
Supported Kubernetes versions
PMEM-CSI implements the CSI specification version 1.x, which is only supported by Kubernetes versions >= v1.13. The following table summarizes the status of support for PMEM-CSI on different Kubernetes versions:
| Kubernetes version | Required alpha feature gates | Support status |
|---|---|---|
| 1.13 | CSINodeInfo, CSIDriverRegistry, CSIBlockVolume | unsupported 1 |
| 1.14 | unsupported 2 | |
| 1.15 | CSIInlineVolume | unsupported 3 |
| 1.16 | unsupported 4 | |
| 1.17 | unsupported 5 | |
| 1.18 | unsupported 6 | |
| 1.19 | unsupported 6 | |
| 1.20 | unsupported 6 | |
| 1.21 | untested | |
| 1.22 | supported | |
| 1.23 | supported | |
| 1.24 | supported | |
| 1.25 | supported |
1 Several relevant features are only available in alpha
quality in Kubernetes 1.13 and the combination of skip attach and
block volumes is completely broken, with the
fix only being
available in later versions. The external-provisioner v1.0.1 for
Kubernetes 1.13 lacks the --strict-topology flag and therefore late
binding is unreliable. It's also a release that is not supported
officially by upstream anymore.
2 Lacks support for ephemeral inline volumes. Not supported officially by upstream anymore.
3 Not supported officially by upstream anymore.
4 No longer supported by current external-provisioner 2.0.0 because support for the v1beta CSI APIs was removed. Also not supported officially by upstream anymore.
5 Kubernetes 1.17 uses deprecated beta storage APIs.
6 Storage capacity tracking is expected to be enabled. It became beta in Kubernetes 1.21.
Feature status
PMEM-CSI is under active development. New features are added continuously and old features may be removed. To minimize the impact of feature changes on production usage, the project uses the following approach:
- New features are considered alpha while their API and usage are under discussion.
- Stable features are supported and tested across up- and downgrades between all supported PMEM-CSI releases. Whether a release is still supported is documented in the release notes.
- Alpha features may be removed at any time. Stable features will be marked as deprecated first and then may be removed after half a year. Deprecations are announced in the release notes of the release that deprecates the feature.
The following table lists the features that are stable:
| Feature | Introduced in |
|---|---|
| LVM mode | v0.5.0 |
| Direct mode | v0.5.0 |
| Persistent volumes | v0.5.0 |
| CSI Ephemeral volumes | v0.6.0 |
| Raw block volumes | v0.6.0 |
| Capacity-aware pod scheduling | v0.7.0 |
| Operator API | v0.9.0 |
Release notes are prepared only for major new releases (such as v0.6.0) but not for automatic updates (such as v0.6.1). For more information on releases, see release management.
Demo
Click the image to watch the animated demo on asciinema.org:
License
All of the source code required to build PMEM-CSI is available under
Open Source licenses. The source code files identify the external Go
modules that are used. Binaries are distributed as container images on
Docker* Hub. Those images contain license texts under
/usr/local/share/package-licenses and source code under
/usr/local/share/package-sources.
Content
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hack
|
|
|
tooling
Package tooling contains dependencies for some of the code that we only need at build time.
|
Package tooling contains dependencies for some of the code that we only need at build time. |
|
pkg
|
|
|
apis/pmemcsi
Package pmemcsi contains pmemcsi API versions.
|
Package pmemcsi contains pmemcsi API versions. |
|
apis/pmemcsi/v1beta1
Package v1beta1 contains API Schema definitions for the pmem-csi v1beta1 API group +groupName=pmem-csi.intel.com
|
Package v1beta1 contains API Schema definitions for the pmem-csi v1beta1 API group +groupName=pmem-csi.intel.com |
|
deployments
The deployments package reads the reference YAML files and optionally modifies them for deployment.
|
The deployments package reads the reference YAML files and optionally modifies them for deployment. |
|
errors
Package errors contain some well-defined errors that may have to be passed up from low-level layers in the PMEM-CSI stack up to the gRPC interface.
|
Package errors contain some well-defined errors that may have to be passed up from low-level layers in the PMEM-CSI stack up to the gRPC interface. |
|
imagefile
Package imagefile contains code to create a file with the following content:
|
Package imagefile contains code to create a file with the following content: |
|
imagefile/test
Package test contains a black-box test for the imagefile package.
|
Package test contains a black-box test for the imagefile package. |
|
k8sutil
The package k8sutil contains some helper code which simplifies interaction with a Kubernetes cluster.
|
The package k8sutil contains some helper code which simplifies interaction with a Kubernetes cluster. |
|
logger
Package logger defines an interface for adding a structured logger to a context and retrieving it again.
|
Package logger defines an interface for adding a structured logger to a context and retrieving it again. |
|
math
Package math contains some arithmetic helper functions.
|
Package math contains some arithmetic helper functions. |
|
pmem-csi-operator/controller/deployment/testcases
Package testcases contains test cases for the operator which can be used both during unit and E2E testing.
|
Package testcases contains test cases for the operator which can be used both during unit and E2E testing. |
|
types
Package types contains some type definitions that are used in various places.
|
Package types contains some type definitions that are used in various places. |
|
test
|
|
|
e2e/deploy
Package deploy contains code which provides information about the cluster and deploying PMEM-CSI inside it.
|
Package deploy contains code which provides information about the cluster and deploying PMEM-CSI inside it. |
|
e2e/operator/validate
Package validate contains code to check objects deployed by the operator as part of an E2E test.
|
Package validate contains code to check objects deployed by the operator as part of an E2E test. |
|
e2e/versionskew
Package versionskew testing ensures that APIs and state is compatible across up- and downgrades.
|
Package versionskew testing ensures that APIs and state is compatible across up- and downgrades. |
|
test-config
Package testconfig reads config strings from test-config.sh or the environment.
|
Package testconfig reads config strings from test-config.sh or the environment. |
|
third-party
|
|
|
go-fibmap
Package fibmap implements FIBMAP/FIEMAP and related Linux ioctl for dealing with low level file allocation.
|
Package fibmap implements FIBMAP/FIEMAP and related Linux ioctl for dealing with low level file allocation. |