Amazon EBS Storage mit CSI-Treiber in Kubernetes integrieren

Architektur und Grundlagen

Der Amazon EBS CSI-Treiber erweitert Kubernetes um die Fähigkeit, AWS Elastic Block Store (EBS) als persistenten Speicher zu nutzen. Technisch basiert alles auf dem Container Storage Interface (CSI)-Standard. Der folgende Aufbau kombiniert die beiden standardisierten CSI-Komponenten mit AWS- und Kubernetes-spezifischen Ressourcen, die für den Betrieb des EBS-CSI-Treibers erforderlich sind:

• CSI-Controller (Deployment): Überwacht und steuert Storage-Anfragen zentral.
• CSI-Node-Plugin (DaemonSet): Bindet Volumes an EC2-Arbeitsknoten im Cluster an.
• IAM-Rolle: Verleiht dem Treiber die nötigen AWS-Berechtigungen. Die Managed Policy AmazonEBSCSIDriverPolicy regelt alle notwendigen Aktionen, von der Volume-Erstellung bis zur Verbindung mit EC2-Nodes.
• StorageClass: Legt fest, wie Kubernetes-Volumes intern als EBS-Volumes provisioniert werden, mit zahlreichen Parametern zur Feinabstimmung, darunter Typ, Verschlüsselung, oder Perfomance.

Zusätzlich setzt der EBS-CSI-Treiber auf Kubernetes-seitige CSI-Sidecar-Container wie external-provisioner, external-attacher und livenessprobe, die die Kommunikation zwischen dem Treiber und der Kubernetes Control Plane ermöglichen und dynamische Volume-Vorgänge auslösen.

Die gesamte CSI-Integration läuft nur auf EC2-basierten Worker-Knoten. Fargate wird aktuell nicht unterstützt, da AWS Fargate keine Blockspeichergeräte wie EBS anbinden kann. Volumes sind per Default als ReadWriteOnce an einen einzelnen Pod gebunden; Multi-Attach gibt es nur für ausgewählte EBS-Typen wie io1 oder io2 und in bestimmten Szenarien.

Da EBS-Volumes physisch an eine bestimmte Availability Zone (AZ) gebunden sind, ist es wichtig, deren Platzierung im Cluster zu berücksichtigen. Daher spielt das Verständnis der zugrunde liegenden Topologie eine wesentliche Rolle bei der Planung und Provisionierung.

Da, wie erwähnt, EBS-Volumes immer an eine bestimmte Availability Zone (AZ) gebunden sind, erfolgt das Scheduling der Pods in den jeweiligen Zonen. Optional kann dies in der StorageClass mit allowedTopologies weiter eingeschränkt oder gesteuert werden.
Falls Snapshots genutzt werden sollen, kann der optionale CSI Snapshot Controller mit entsprechenden VolumeSnapshot-Ressourcen installiert werden.

Voraussetzungen für die Installation

Vor dem Deployment sollten folgende Bedingungen erfüllt sein:

• Ein lauffähiger EKS-Cluster (klassisch oder Auto Mode)
• Administrativer Zugriff auf die AWS-Konsole oder Command Line Interface (CLI)
• Die neueste Version von kubectl und eksctl
• Fähigkeit, IAM-Rollen und ServiceAccounts im Cluster zu erstellen und zu verbinden
• Keine ältere, manuell installierte Version des EBS-CSI-Treibers darf aktiv sein

Es gilt zu beachten, dass in EKS Auto Mode der EBS-CSI-Treiber nicht manuell installiert werden kann. Die Integration wird dort von AWS automatisch verwaltet und ist nur in Regionen verfügbar, in denen EBS-Speicherressourcen für Auto-Mode-Cluster unterstützt werden. Monitoring-Integrationen wie Prometheus sind in Auto-Mode-Clustern derzeit ebenfalls nur eingeschränkt verfügbar (siehe die AWS-Dokumentation zu EKS Auto Mode).

Schritt 1: Anlegen der IAM-Rolle mit AWS Policy

Für den EBS-CSI-Treiber ist eine dedizierte IAM-Rolle Pflicht. Sie gewährt dem Treiber Zugriff auf die AWS-EBS- und EC2-APIs, regelt die Provisionierung und, falls nötig, die Verschlüsselung per KMS-Schlüssel.

Voraussetzung ist, dass Ihr EKS-Cluster über einen aktivierten OIDC-Identity Provider verfügt. Dies können Sie mit folgendem Befehl prüfen:

eksctl utils associate-iam-oidc-provider --cluster my-cluster --approve

Anschließend kann die IAM-Rolle samt Verknüpfung mit dem ServiceAccount erstellt werden:

eksctl create iamserviceaccount \
  --name ebs-csi-controller-sa \
  --namespace kube-system \
  --cluster my-cluster \
  --role-name AmazonEKS_EBS_CSI_DriverRole \
  --role-only \
  --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --approve

Wenn Sie --role-only angeben, wird nur die IAM-Rolle erstellt – nicht der zugehörige Kubernetes-ServiceAccount. Um die Verbindung direkt zu erzeugen, lassen Sie --role-only weg. Alternativ kann die Rolle später manuell über den ServiceAccount im Cluster verbunden werden, wenn Sie das offizielle EKS-Add-on installiert haben.

Falls Sie verschlüsselte Volumes nutzen, fügen Sie Ihrer Rolle den Zugriff auf den gewünschten KMS-Schlüssel hinzu.

In speziellen Sicherheitsumgebungen kann anstelle der Managed Policy AmazonEBSCSIDriverPolicy auch eine benutzerdefinierte Policy mit eingeschränkten Rechten verwendet werden (siehe AWS-Dokumentation zu Amazon EBS CSI Driver IAM Permissions).

Schritt 2: Installation des EBS CSI-Treibers als EKS-Add-on

AWS empfiehlt, den EBS-CSI-Treiber als offizielles Add-on zu installieren, da dies automatische Updates, Security-Fixes und eine einfachere Verwaltung ermöglicht. Die Installation erfolgt über das AWS CLI mit dem Befehl:

aws eks create-addon \
  --cluster-name my-cluster \
  --addon-name aws-ebs-csi-driver \
  --service-account-role-arn arn:aws:iam::<ACCOUNT_ID>:role/AmazonEKS_EBS_CSI_DriverRole

Alternativ kann das Add-on auch über die AWS-Konsole installiert werden. Vor der Installation sollte jede ältere, manuell verwaltete Version des EBS-CSI-Treibers entfernt werden, um Konflikte zu vermeiden. Die IAM-Rolle muss korrekt mit dem Kubernetes-ServiceAccount über IRSA verbunden sein, da die Installation andernfalls fehlschlägt. In EKS Auto Mode Clustern wird der Treiber automatisch bereitgestellt, eine manuelle Installation ist dort nicht möglich. Optional kann die gewünschte Add-on-Version über die Option --addon-version <VERSION> angegeben werden, um sicherzustellen, dass die installierte Version mit der Cluster-Version kompatibel ist.

Schritt 3: StorageClass für dynamische EBS-Volumes definieren

Die StorageClass ist das Herzstück der automatisierten Provisionierung von EBS-Volumes in Kubernetes. Sie legt fest, welcher Volume-Typ verwendet wird, ob das Volume verschlüsselt ist, welches Dateisystem zum Einsatz kommt und welche Performance-Parameter, wie IOPS oder Durchsatz, gesetzt werden. Mit der StorageClass steuert Kubernetes die dynamische Erstellung der EBS-Volumes, sobald ein Pod ein entsprechendes PersistentVolumeClaim (PVC) anfordert.

Ein Beispiel für eine StorageClass, die gp3-Volumes nutzt, könnte wie folgt aussehen:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-gp3-sc
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  encrypted: "true"
  kmsKeyId: arn:aws:kms:region:account-id:key/key-id   # optional, nur bei eigener KMS-Verschlüsselung
  csi.storage.k8s.io/fstype: ext4
  iops: "3000"        # relevant für gp3, io1 und io2
  throughput: "125"   # relevant nur für gp3

Mit volumeBindingMode: WaitForFirstConsumer wird das Volume erst erstellt und an einen Pod gebunden, sobald dieser im Cluster geplant wird. Dadurch wird automatisch die passende Availability Zone gewählt, sodass das Volume auf demselben Knoten verfügbar ist. Optional können über allowedTopologies bestimmte AZs festgelegt werden, um die Platzierung gezielt einzuschränken und ungewollte Cross-AZ-Bindungen zu vermeiden.

Die Parameter im Detail:

• type legt den EBS-Volumentyp fest (zum Beispiel gp3, gp2, io1 oder io2).
• encrypted: "true" aktiviert die Verschlüsselung, optional kann über kmsKeyId ein eigener KMS-Schlüssel verwendet werden.
• csi.storage.k8s.io/fstype bestimmt das Dateisystem des Volumes, beispielsweise ext4 oder xfs.
• iops und throughput steuern die Performance des Volumes, sind jedoch nur für bestimmte Typen relevant.

Mit dieser StorageClass können Kubernetes-Workloads dynamisch Volumes anfordern, die automatisch an die passende AZ gebunden werden und die gewünschten Performance- und Sicherheitsanforderungen erfüllen. Die Anwendung erfolgt klassisch über:

kubectl apply -f storageclass.yaml

Schritt 4: PersistentVolumeClaim für EBS Storage beantragen

Nachdem die StorageClass definiert ist, kann ein Pod über einen PersistentVolumeClaim (PVC) ein EBS-Volume dynamisch anfordern. Ein PVC beschreibt die benötigte Speichermenge, den Zugriffsmodus und die zu verwendende StorageClass. Im folgenden Beispiel wird ein PVC mit 20 GiB Speicher erstellt, der über die StorageClass ebs-gp3-sc dynamisch provisioniert wird.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ebs-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: ebs-gp3-sc
  resources:
    requests:
      storage: 20Gi

Mit diesem PVC sorgt Kubernetes automatisch dafür, dass das EBS-Volume erstellt, der richtigen Availability Zone zugeordnet und an den Pod gebunden wird, sobald dieser im Cluster geplant wird. Das Volume steht dem Pod dann wie ein lokales Dateisystem zur Verfügung. Die Erstellung erfolgt klassisch über:

kubectl apply -f pvc.yaml

Durch diesen Mechanismus wird die dynamische Provisionierung und Bindung vollständig automatisiert, sodass sich Entwickler und Operatoren nicht um die direkte Verwaltung von EBS-Volumes kümmern müssen.

Schritt 5: Funktion und Status prüfen

Nach der Installation des EBS-CSI-Treibers sollte geprüft werden, ob die Komponenten korrekt laufen und die Storage-Ressourcen wie erwartet bereitgestellt werden. Zunächst sollten die EBS-CSI-Pods im Namespace kube-system im Zustand Running sein. Dies lässt sich mit dem Befehl kubectl get pods -n kube-system | grep ebs überprüfen. Anschließend empfiehlt es sich, sicherzustellen, dass die StorageClass korrekt im Cluster gelistet ist (kubectl get storageclass) und dass die PersistentVolumeClaims (PVCs) den Status Bound anzeigen (kubectl get pvc). Parallel kann in der AWS-Management-Konsole überprüft werden, ob das entsprechende EBS-Volume sichtbar und korrekt zugeordnet ist.

Falls Snapshots oder Restores benötigt werden, sollte zusätzlich der CSI Snapshot Controller installiert und konfiguriert sein. Neben dem Controller müssen auch die VolumeSnapshot CustomResourceDefinitions (CRDs) im Cluster vorhanden sein, um Snapshot- und Restore-Funktionen nutzen zu können. Beide Komponenten lassen sich als Kubernetes Add-ons installieren.

Fehler oder Probleme lassen sich in der Regel anhand des Pod-Status, der Logs des CSI-Treibers oder der IAM-Berechtigungen diagnostizieren. Technische Besonderheiten sind zu beachten: EBS-Volumes sind standardmäßig nur als ReadWriteOnce an einen einzelnen Pod oder Node gebunden. Multi-Attach ist nur für ausgewählte EBS-Typen wie io1 oder io2 und in speziellen Szenarien möglich. Volumes werden nach Availability Zone (AZ) geplant, was insbesondere in Multi-AZ-Setups sinnvoll ist. Über die StorageClass oder die IAM-Rolle können AWS-Tags gesetzt werden. Monitoring-Metriken lassen sich mit Prometheus sammeln, wobei im EKS-Auto-Mode nicht immer alle Metriken direkt verfügbar sind. Schließlich läuft der EBS-CSI-Treiber nur auf klassischen EC2-Worker-Nodes; Fargate wird nicht unterstützt.