add initial BucketClaim controller reconciliation

Add initial implementation for BucketClaim reconciliation based on
v1alpha2 KEP. This initial implementation covers only the first section
of Controller reconciliation for a new BucketClaim. Coverage ends at the
point where reconciliation is handed off to the Sidecar.

Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>

Author: BlaineEXE

client/apis/objectstorage/v1alpha2/bucket_types.go

@@ -18,21 +18,80 @@ package v1alpha2
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
 )
 
-// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
-// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+// BucketDeletionPolicy configures COSI's behavior when a Bucket resource is deleted.
+// +enum
+// +kubebuilder:validation:Enum:=Retain;Delete
+type BucketDeletionPolicy string
+
+const (
+	// BucketDeletionPolicyRetain configures COSI to keep the Bucket object as well as the backend
+	// bucket when a Bucket resource is deleted.
+	BucketDeletionPolicyRetain BucketDeletionPolicy = "Retain"
+
+	// BucketDeletionPolicyDelete configures COSI to delete the Bucket object as well as the backend
+	// bucket when a Bucket resource is deleted.
+	BucketDeletionPolicyDelete BucketDeletionPolicy = "Delete"
+)
 
 // BucketSpec defines the desired state of Bucket
 type BucketSpec struct {
-	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
-	// Important: Run "make" to regenerate code after modifying this file
-	// The following markers will use OpenAPI v3 schema to validate the value
-	// More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
+	// driverName is the name of the driver that fulfills requests for this Bucket.
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="self == oldSelf"
+	DriverName string `json:"driverName"`
+
+	// deletionPolicy determines whether a Bucket should be deleted when its bound BucketClaim is
+	// deleted. This is mutable to allow Admins to change the policy after creation.
+	// Possible values:
+	//  - Retain: keep both the Bucket object and the backend bucket
+	//  - Delete: delete both the Bucket object and the backend bucket
+	// +required
+	DeletionPolicy BucketDeletionPolicy `json:"deletionPolicy"`
+
+	// parameters is an opaque map of driver-specific configuration items passed to the driver that
+	// fulfills requests for this Bucket.
+	// +optional
+	// +kubebuilder:validation:XValidation:message="parameters map is immutable",rule="self == oldSelf"
+	Parameters map[string]string `json:"parameters,omitempty"`
+
+	// protocols lists object store protocols that the provisioned Bucket must support.
+	// If specified, COSI will verify that each item is advertised as supported by the driver.
+	// +optional
+	// +kubebuilder:validation:XValidation:message="protocols list is immutable",rule="self == oldSelf"
+	Protocols []ObjectProtocol `json:"protocols,omitempty"`
+
+	// bucketClaim references the BucketClaim that resulted in the creation of this Bucket.
+	// For statically-provisioned buckets, set the namespace and name of the BucketClaim that is
+	// allowed to bind to this Bucket.
+	// +required
+	BucketClaimRef BucketClaimReference `json:"bucketClaim"`
+}
+
+// BucketClaimReference is a reference to a BucketClaim object.
+type BucketClaimReference struct {
+	// name is the name of the BucketClaim being referenced.
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="self == oldSelf"
+	Name string `json:"name"`
+
+	// namespace is the namespace of the BucketClaim being referenced.
+	// If empty, the Kubernetes 'default' namespace is assumed.
+	// namespace is immutable except to update '' to 'default'.
+	// +optional
+	// +kubebuilder:validation:MinLength=0
+	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="(oldSelf == '' && self == 'default') || self == oldSelf"
+	Namespace string `json:"namespace"`
 
-	// foo is an example field of Bucket. Edit bucket_types.go to remove/update
+	// uid is the UID of the BucketClaim being referenced.
+	// Once set, the UID is immutable.
 	// +optional
-	Foo *string `json:"foo,omitempty"`
+	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="oldSelf == '' || self == oldSelf"
+	UID types.UID `json:"uid"`
 }
 
 // BucketStatus defines the observed state of Bucket.
@@ -46,6 +105,7 @@ type BucketStatus struct {
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
 // Bucket is the Schema for the buckets API
 type Bucket struct {

client/apis/objectstorage/v1alpha2/bucketaccess_types.go

@@ -20,8 +20,21 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
-// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+// ObjectStoreProtocol identifies an object storage protocol.
+// +enum
+// +kubebuilder:validation:Enum:=S3;Azure;GCS
+type ObjectStoreProtocol string
+
+const (
+	// ObjectStoreProtocolS3 identifies the AWS S3 object storage protocol.
+	ObjectStoreProtocolS3 ObjectStoreProtocol = "S3"
+
+	// ObjectStoreProtocolAzure identifies the Azure Blob object storage protocol.
+	ObjectStoreProtocolAzure ObjectStoreProtocol = "Azure"
+
+	// ObjectStoreProtocolGcs identifies the Google Cloud Storage (GCS) object storage protocol.
+	ObjectStoreProtocolGcs ObjectStoreProtocol = "GCS"
+)
 
 // BucketAccessSpec defines the desired state of BucketAccess
 type BucketAccessSpec struct {
@@ -60,6 +73,7 @@ type BucketAccessStatus struct {
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
 // BucketAccess is the Schema for the bucketaccesses API
 type BucketAccess struct {

client/apis/objectstorage/v1alpha2/bucketaccessclass_types.go

@@ -60,6 +60,7 @@ type BucketAccessClassStatus struct {
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
 // BucketAccessClass is the Schema for the bucketaccessclasses API
 type BucketAccessClass struct {

client/apis/objectstorage/v1alpha2/bucketclaim_types.go

@@ -20,19 +20,29 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
-// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
-
 // BucketClaimSpec defines the desired state of BucketClaim
+// +kubebuilder:validation:ExactlyOneOf=bucketClassName;existingBucketName
 type BucketClaimSpec struct {
-	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
-	// Important: Run "make" to regenerate code after modifying this file
-	// The following markers will use OpenAPI v3 schema to validate the value
-	// More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
+	// bucketClassName selects the BucketClass for provisioning the BucketClaim.
+	// This field is used only for BucketClaim dynamic provisioning.
+	// If unspecified, existingBucketName must be specified for binding to an existing Bucket.
+	// +optional
+	// +kubebuilder:validation:XValidation:message="bucketClassName is immutable",rule="self == oldSelf"
+	BucketClassName string `json:"bucketClassName,omitempty"`
+
+	// protocols lists object storage protocols that the provisioned Bucket must support.
+	// If specified, COSI will verify that each item is advertised as supported by the driver.
+	// +optional
+	// +kubebuilder:validation:XValidation:message="protocols list is immutable",rule="self == oldSelf"
+	Protocols []ObjectProtocol `json:"protocols,omitempty"`
 
-	// foo is an example field of BucketClaim. Edit bucketclaim_types.go to remove/update
+	// existingBucketName selects the name of an existing Bucket resource that this BucketClaim
+	// should bind to.
+	// This field is used only for BucketClaim static provisioning.
+	// If unspecified, bucketClassName must be specified for dynamically provisioning a new bucket.
 	// +optional
-	Foo *string `json:"foo,omitempty"`
+	// +kubebuilder:validation:XValidation:message="existingBucketName is immutable",rule="self == oldSelf"
+	ExistingBucketName string `json:"existingBucketName,omitempty"`
 }
 
 // BucketClaimStatus defines the observed state of BucketClaim.
@@ -60,6 +70,7 @@ type BucketClaimStatus struct {
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
 // BucketClaim is the Schema for the bucketclaims API
 type BucketClaim struct {
@@ -79,6 +90,7 @@ type BucketClaim struct {
 }
 
 // +kubebuilder:object:root=true
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
 // BucketClaimList contains a list of BucketClaim
 type BucketClaimList struct {

client/apis/objectstorage/v1alpha2/bucketclass_types.go

@@ -20,62 +20,45 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
-// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
-
-// BucketClassSpec defines the desired state of BucketClass
+// BucketClassSpec defines the BucketClass.
 type BucketClassSpec struct {
-	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
-	// Important: Run "make" to regenerate code after modifying this file
-	// The following markers will use OpenAPI v3 schema to validate the value
-	// More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
-
-	// foo is an example field of BucketClass. Edit bucketclass_types.go to remove/update
-	// +optional
-	Foo *string `json:"foo,omitempty"`
-}
-
-// BucketClassStatus defines the observed state of BucketClass.
-type BucketClassStatus struct {
-	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
-	// Important: Run "make" to regenerate code after modifying this file
-
-	// For Kubernetes API conventions, see:
-	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
+	// driverName is the name of the driver that fulfills requests for this BucketClass.
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	DriverName string `json:"driverName"`
+
+	// deletionPolicy determines whether a Bucket created through the BucketClass should be deleted
+	// when its bound BucketClaim is deleted.
+	// Possible values:
+	//  - Retain: keep both the Bucket object and the backend bucket
+	//  - Delete: delete both the Bucket object and the backend bucket
+	// +required
+	DeletionPolicy BucketDeletionPolicy `json:"deletionPolicy"`
 
-	// conditions represent the current state of the BucketClass resource.
-	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
-	//
-	// Standard condition types include:
-	// - "Available": the resource is fully functional
-	// - "Progressing": the resource is being created or updated
-	// - "Degraded": the resource failed to reach or maintain its desired state
-	//
-	// The status of each condition is one of True, False, or Unknown.
-	// +listType=map
-	// +listMapKey=type
+	// parameters is an opaque map of driver-specific configuration items passed to the driver that
+	// fulfills requests for this BucketClass.
 	// +optional
-	Conditions []metav1.Condition `json:"conditions,omitempty"`
+	Parameters map[string]string `json:"parameters,omitempty"`
 }
 
 // +kubebuilder:object:root=true
-// +kubebuilder:subresource:status
+// +kubebuilder:metadata:annotations="api-approved.kubernetes.io=https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support"
 
-// BucketClass is the Schema for the bucketclasses API
+// BucketClass defines a named "class" of object storage buckets.
+// Different classes might map to different object storage protocols, quality-of-service levels,
+// backup policies, or any other arbitrary configuration determined by storage administrators.
+// The name of a BucketClass object is significant, and is how users can request a particular class.
 type BucketClass struct {
 	metav1.TypeMeta `json:",inline"`
 
 	// metadata is a standard object metadata
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
 
-	// spec defines the desired state of BucketClass
+	// spec defines the BucketClass. spec is entirely immutable.
 	// +required
+	// +kubebuilder:validation:XValidation:message="BucketClass spec is immutable",rule="self == oldSelf"
 	Spec BucketClassSpec `json:"spec"`
-
-	// status defines the observed state of BucketClass
-	// +optional
-	Status BucketClassStatus `json:"status,omitempty,omitzero"`
 }
 
 // +kubebuilder:object:root=true

client/apis/objectstorage/v1alpha2/definitions.go

@@ -17,6 +17,10 @@ limitations under the License.
 package v1alpha2
 
 const (
+	// ProtectionFinalizer is applied to a COSI resource object to protect it from deletion while
+	// COSI processes deletion of the object's intermediate and backend resources.
+	ProtectionFinalizer = `objectstorage.k8s.io/protection`
+
 	// RpcEndpointDefault is the default RPC endpoint unix socket location.
 	RpcEndpointDefault = "unix:///var/lib/cosi/cosi.sock"
 

client/apis/objectstorage/v1alpha2/protocols.go

@@ -0,0 +1,35 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+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 v1alpha2
+
+/*
+This file contains all definitions for the various object store protocols.
+*/
+
+// ObjectProtocol represents an object protocol type.
+type ObjectProtocol string
+
+const (
+	// ObjectProtocolS3 represents the S3 object protocol type.
+	ObjectProtocolS3 = "S3"
+
+	// ObjectProtocolS3 represents the Azure Blob object protocol type.
+	ObjectProtocolAzure = "Azure"
+
+	// ObjectProtocolS3 represents the Google Cloud Storage object protocol type.
+	ObjectProtocolGcs = "GCS"
+)