Driver APIs and controller definition

First pass on driver APIs, including a list of TODOs to be addressed in a PR revision or on some future PRs

PROJECT

@@ -7,4 +7,14 @@ layout:
 - go.kubebuilder.io/v4
 projectName: ceph-csi-operator
 repo: github.com/ceph/ceph-csi-operator
+resources:
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: ceph.io
+  group: csi
+  kind: Driver
+  path: github.com/ceph/ceph-csi-operator/api/v1alpha1
+  version: v1alpha1
 version: "3"

api/v1alpha1/driver_types.go

@@ -0,0 +1,267 @@
+/*
+Copyright 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	storagev1 "k8s.io/api/storage/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+type LogSpec struct {
+	// Log level for driver pods,
+	// Supported values from 0 to 5. 0 for general useful logs (the default), 5 for trace level verbosity.
+	// Default to 0
+	LogLevel   int `json:"logLevel,omitempty"`
+	MaxFiles   int `json:"maxFiles,omitempty"`
+	MaxLogSize int `json:"maxLogSize,omitempty"`
+}
+
+// TODO: Add a porper description
+type SnapshotPolicyType string
+
+const (
+	AutoDetectSnapshotPolicy SnapshotPolicyType = "auto-detect"
+	GroupSnapshotPolicy      SnapshotPolicyType = "group"
+	SnapshotSnapshotPolicy   SnapshotPolicyType = "snapshot"
+)
+
+type EncryptionSpec struct {
+	ConfigMapRef corev1.LocalObjectReference `json:"configMapName,omitempty"`
+}
+
+type PodCommonSpec struct {
+	// Pod's user defined priority class name
+	PrioritylClassName *string `json:"priorityClassName,omitempty"`
+
+	// Pod's labels
+	Labels map[string]string `json:"labels,omitempty"`
+
+	// Pod's annotations
+	Annotations map[string]string `json:"annotations,omitempty"`
+
+	// Pod's affinity settings
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
+
+	// Pod's tolerations list
+	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
+}
+
+type PluginResourcesSpec struct {
+	Registrar corev1.ResourceRequirements `json:"registerer,omitempty"`
+	Liveness  corev1.ResourceRequirements `json:"liveness,omitempty"`
+	Plugin    corev1.ResourceRequirements `json:"plugin,omitempty"`
+}
+
+type PluginSpec struct {
+	// Embedded common pods spec
+	PodCommonSpec `json:"inline"`
+
+	// Driver's plugin daemonset update strategy, supported values are OnDelete and RollingUpdate.
+	// Default value is RollingUpdate with MaxAvailabile set to 1
+	UpdateStrategy appsv1.DaemonSetUpdateStrategy `json:"updateStrategy,omitempty"`
+
+	// Resource requirements for plugin's containers
+	Resources *PluginResourcesSpec `json:"resources,omitempty"`
+
+	Volumes []corev1.Volume `json:"pluginVolumes,omitempty"`
+
+	// kubelet directory path, if kubelet configured to use other than /var/lib/kubelet path.
+	KubeletDirPath string `json:"kubeletDirPath"`
+
+	// Control the host mount of /etc/selinux for csi plugin pods. Defaults to false
+	EnableSeLinuxHostMount bool `json:"EnableSeLinuxHostMount,omitempty"`
+
+	// To indicate the image pull policy to be applied to all the containers in the csi driver pods.
+	ImagePullPolicy string `json:"imagePullPolicy"`
+}
+
+type ProvisionerResourcesSpec struct {
+	Attacher      corev1.ResourceRequirements `json:"attacher,omitempty"`
+	Snapshotter   corev1.ResourceRequirements `json:"snapshotter,omitempty"`
+	Resizer       corev1.ResourceRequirements `json:"resizer,omitempty"`
+	Provisioner   corev1.ResourceRequirements `json:"provisioner,omitempty"`
+	OMapGenerator corev1.ResourceRequirements `json:"omapGenerator,omitempty"`
+	Liveness      corev1.ResourceRequirements `json:"liveness,omitempty"`
+	Plugin        corev1.ResourceRequirements `json:"plugin,omitempty"`
+}
+
+type ProvisionerSpec struct {
+	// Embedded common pods spec
+	PodCommonSpec `json:"inline"`
+
+	// Set replicas for csi provisioner deployment. Defaults to 2
+	Replicas *int32 `json:"provisionerReplicas,omitempty"`
+
+	// Resource requirements for provisioner's containers
+	Resources *ProvisionerResourcesSpec `json:"resources,omitempty"`
+}
+
+type LivenessSpec struct {
+	// Port to expose liveness metrics
+	MetricsPort int `json:"metricsPort,omitempty"`
+}
+
+type LeaderElectionSpec struct {
+	// Duration in seconds that non-leader candidates will wait to force acquire leadership.
+	// Default to 137 seconds.
+	LeaseDuration int `json:"leaseDuration,omitempty"`
+
+	// Deadline in seconds that the acting leader will retry refreshing leadership before giving up.
+	// Defaults to 107 seconds.
+	RenewDeadline int `json:"renewDeadline,omitempty"`
+
+	// Retry Period in seconds the LeaderElector clients should wait between tries of actions.
+	// Defaults to 26 seconds.
+	RetryPeriod int `json:"retryPeriod,omitempty"`
+}
+
+type CephFsClientType string
+
+const (
+	KernelCephFsClient CephFsClientType = "kernel"
+	FuseCephFsClient   CephFsClientType = "Fuse"
+)
+
+// DriverSpec defines the desired state of Driver
+type DriverSpec struct {
+	// Logging configuration for driver's pods
+	Logging *LogSpec `json:"logging,omitempty"`
+
+	// Cluster name identifier to set as metadata on the CephFS subvolume and RBD images. This will be useful in cases
+	// like for example, when two container orchestrator clusters (Kubernetes/OCP) are using a single ceph cluster.
+	ClusterName *string `json:"clusterName,omitempty"`
+
+	// Set to true to enable adding volume metadata on the CephFS subvolume and RBD images.
+	// Not all users might be interested in getting volume/snapshot details as metadata on CephFS subvolume and RBD images.
+	// Hence enable metadata is false by default.
+	EnableMetadata *bool `json:"enableMetadata,omitempty"`
+
+	// Set the gRPC timeout for gRPC call issued by the driver components
+	GRpcTimeout int `json:"grpcTimeout,omitempty"`
+
+	// Set to true enable snapshot functionality (deplys a snapshooter sidecar)
+	// EnableVolumeSnapshoots     *bool `json:"enableVolumeSnapshoots,omitempty"`
+	// EnableVolumeGroupSnapshoot *bool `json:"enableVolumeGroupSnapshoot,omitempty"`
+	// none, autodetect, volume, volumeAndVolumeGroup
+	SnapshootPolicy SnapshotPolicyType `json:"SnapshootPolicy,omitempty"`
+
+	// OMAP generator will generate the omap mapping between the PV name and the RBD image.
+	// Ned to be enabled when we are using rbd mirroring feature.
+	// By default OMAP generator sidecar is deployed with Csi provisioner pod, to disable
+	// it set it to false.
+	GenerateOMapInfo *bool `json:"generateOMapInfo,omitempty"`
+
+	// Policy for modifying a volume's ownership or permissions when the PVC is being mounted.
+	// supported values are documented at https://kubernetes-csi.github.io/docs/support-fsgroup.html
+	FsGroupPolicy storagev1.FSGroupPolicy `json:"fsGroupPolicy,omitempty"`
+
+	// Driver's encryption settings
+	Encryption *EncryptionSpec `json:"encryption,omitempty"`
+
+	// Driver's plugin configuration
+	Plugin *PluginSpec `json:"plugin,omitempty"`
+
+	// Driver's provisioner configuration
+	Provisioner *ProvisionerSpec `json:"provisioner,omitempty"`
+
+	// Whether to skip any attach operation altogether for CephCsi PVCs.
+	// See more details [here](https://kubernetes-csi.github.io/docs/skip-attach.html#skip-attach-with-csi-driver-object).
+	// If set to false it skips the volume attachments and makes the creation of pods using the CephCsi PVC fast.
+	// **WARNING** It's highly discouraged to use this for RWO volumes. for RBD PVC it can cause data corruption,
+	// csi-addons operations like Reclaimspace and PVC Keyrotation will also not be supported if set to false
+	// since we'll have no VolumeAttachments to determine which node the PVC is mounted on.
+	// Refer to this [issue](https://github.com/kubernetes/kubernetes/issues/103305) for more details.
+	AttachRequired *bool `json:"attachRequired,omitempty"`
+
+	// Liveness metrics configuration.
+	// disabled by default.
+	Liveness *LivenessSpec `json:"liveness,omitempty"`
+
+	// Leader election setting
+	LeaderElection *LeaderElectionSpec `json:"leaderElection,omitempty"`
+
+	// TODO: do we want Csi addon specific field? or should we generalize to
+	// a list of additonal sidecars?
+	DeployCsiAddons *bool `json:"deployCsiAddons,omitempty"`
+
+	// Set mount options to use https://docs.ceph.com/en/latest/man/8/mount.ceph/#options
+	// Set to "ms_mode=secure" when connections.encrypted is enabled in CephCluster CR
+	KernelMountOptions map[string]string `json:"kernelMountOptions,omitempty"`
+
+	// --------------
+	// CephFS toggles
+	// --------------
+
+	// Select between between cephfs kernel driver and ceph-fuse
+	// If you select a non-kernel client, your application may be disrupted during upgrade.
+	// See the upgrade guide: https://rook.io/docs/rook/latest/ceph-upgrade.html
+	// NOTE! cephfs quota is not supported in kernel version < 4.17
+	CephFsClientType CephFsClientType `json:"cephFsClientType,omitempty"` // defualt is Kernal
+}
+
+type DriverPhaseType string
+
+const (
+	ReadyDriverPhase DriverPhaseType = "Ready"
+)
+
+type DriverReasonType string
+
+// TODO: Add failure reason codes
+const ()
+
+// DriverStatus defines the observed state of Driver
+type DriverStatus struct {
+	// TODO: Consider to move away from a single phase to a conditions based approach
+	// or the a Ready list approach. Main reason this reconciler address multiple
+
+	// The last known state of the latest reconcile
+	Phase DriverPhaseType `json:"phase,omitempty"`
+
+	// The reason for the last transition change.
+	Reason DriverReasonType `json:"reason,omitempty"`
+
+	// A human readable message indicating details about the last transition.
+	Message string `json:"message,omitempty"`
+}
+
+//+kubebuilder:object:root=true
+//+kubebuilder:subresource:status
+
+// Driver is the Schema for the drivers API
+type Driver struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   DriverSpec   `json:"spec,omitempty"`
+	Status DriverStatus `json:"status,omitempty"`
+}
+
+//+kubebuilder:object:root=true
+
+// DriverList contains a list of Driver
+type DriverList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []Driver `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&Driver{}, &DriverList{})
+}

api/v1alpha1/groupversion_info.go

@@ -0,0 +1,36 @@
+/*
+Copyright 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package v1alpha1 contains API Schema definitions for the csi v1alpha1 API group
+// +kubebuilder:object:generate=true
+// +groupName=csi.ceph.io
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/scheme"
+)
+
+var (
+	// GroupVersion is group version used to register these objects
+	GroupVersion = schema.GroupVersion{Group: "csi.ceph.io", Version: "v1alpha1"}
+
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
+
+	// AddToScheme adds the types in this group-version to the given scheme.
+	AddToScheme = SchemeBuilder.AddToScheme
+)