address Bucket API review changes

Address API review recommended changes for Bucket resource.

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

Author: BlaineEXE

client/apis/objectstorage/v1alpha2/bucket_types.go

@@ -42,10 +42,11 @@ const (
 // +kubebuilder:validation:XValidation:message="existingBucketID cannot be added or removed after creation",rule="has(oldSelf.existingBucketID) == has(self.existingBucketID)"
 type BucketSpec struct {
 	// driverName is the name of the driver that fulfills requests for this Bucket.
+	// Must be 63 characters or less, beginning and ending with an alphanumeric character
+	// ([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between.
 	// +required
-	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="self == oldSelf"
-	DriverName string `json:"driverName,omitempty"`
+	DriverName DriverName `json:"driverName,omitempty"`
 
 	// 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.
@@ -58,52 +59,68 @@ type BucketSpec struct {
 	// parameters is an opaque map of driver-specific configuration items passed to the driver that
 	// fulfills requests for this Bucket.
 	// +optional
+	// +kubebuilder:validation:MinProperties=1
 	// +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.
+	// Possible values: 'S3', 'Azure', 'GCS'.
 	// +optional
 	// +listType=set
 	// +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.
+	// bucketClaimRef 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,omitzero"`
+	BucketClaimRef BucketClaimReference `json:"bucketClaimRef,omitzero"`
 
 	// existingBucketID is the unique identifier for an existing backend bucket known to the driver.
 	// Use driver documentation to determine how to set this value.
-	// This field is used only for Bucket static provisioning.
+	// This field is used only for static Bucket provisioning.
 	// This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
+	// Must be at most 2048 characters and consist only of alphanumeric characters ([a-z0-9A-Z]),
+	// dashes (-), dots (.), and underscores (_).
 	// +optional
-	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="existingBucketID is immutable",rule="self == oldSelf"
-	ExistingBucketID string `json:"existingBucketID,omitempty"`
+	ExistingBucketID DriverResourceID `json:"existingBucketID,omitempty"`
 }
 
 // BucketClaimReference is a reference to a BucketClaim object.
 // +kubebuilder:validation:XValidation:message="namespace cannot be removed once set",rule="!has(oldSelf.namespace) || has(self.namespace)"
 // +kubebuilder:validation:XValidation:message="uid cannot be removed once set",rule="!has(oldSelf.uid) || has(self.uid)"
 type BucketClaimReference struct {
 	// name is the name of the BucketClaim being referenced.
+	// Must be a valid Kubernetes resource name: at most 253 characters, consisting only of
+	// lower-case alphanumeric characters, hyphens, and periods, starting and ending with an
+	// alphanumeric character.
 	// +required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
+	// +kubebuilder:validation:XValidation:message="name must be a valid resource name",rule="!format.dns1123Subdomain().validate(self).hasValue()"
 	// +kubebuilder:validation:XValidation:message="name is immutable",rule="self == oldSelf"
 	Name string `json:"name,omitempty"`
 
 	// namespace is the namespace of the BucketClaim being referenced.
+	// Must be a valid Kubernetes Namespace name: at most 63 characters, consisting only of
+	// lower-case alphanumeric characters and hyphens, starting and ending with alphanumerics.
 	// +required
 	// +kubebuilder:validation:MinLength=1
-	// +kubebuilder:validation:MaxLength=253
+	// +kubebuilder:validation:MaxLength=63
+	// +kubebuilder:validation:XValidation:message="namespace must be a valid namespace name",rule="!format.dns1123Label().validate(self).hasValue()"
 	// +kubebuilder:validation:XValidation:message="namespace is immutable",rule="self == oldSelf"
 	Namespace string `json:"namespace,omitempty"`
 
 	// uid is the UID of the BucketClaim being referenced.
+	// Must be a valid Kubernetes UID: RFC 4122 form with lowercase hexadecimal characters
+	// (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
 	// +optional
+	// +kubebuilder:validation:MinLength=36
+	// +kubebuilder:validation:MaxLength=36
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Pattern=`^[0-9a-f]{8}-([0-9a-f]{4}\-){3}[0-9a-f]{12}$`
 	// +kubebuilder:validation:XValidation:message="uid is immutable once set",rule="oldSelf == '' || self == oldSelf"
 	UID types.UID `json:"uid,omitempty"`
 }
@@ -117,13 +134,15 @@ type BucketStatus struct {
 	ReadyToUse *bool `json:"readyToUse,omitempty"`
 
 	// bucketID is the unique identifier for the backend bucket known to the driver.
+	// Must be at most 2048 characters and consist only of alphanumeric characters ([a-z0-9A-Z]),
+	// dashes (-), dots (.), and underscores (_).
 	// +optional
-	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="boundBucketName is immutable once set",rule="self == oldSelf"
-	BucketID string `json:"bucketID,omitempty"`
+	BucketID DriverResourceID `json:"bucketID,omitempty"`
 
 	// protocols is the set of protocols the Bucket reports to support. BucketAccesses can request
 	// access to this BucketClaim using any of the protocols reported here.
+	// Possible values: 'S3', 'Azure', 'GCS'.
 	// +optional
 	// +listType=set
 	Protocols []ObjectProtocol `json:"protocols,omitempty"`

client/apis/objectstorage/v1alpha2/shared_types.go

@@ -27,6 +27,22 @@ import (
 	meta "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// DriverName represents the name of a driver.
+// Must be 63 characters or less, beginning and ending with an alphanumeric character
+// ([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between.
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=63
+// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9]([a-zA-Z0-9\-\.]{0,61}[a-zA-Z0-9])?$`
+type DriverName string
+
+// DriverResourceID represents a unique identifier for a driver bucket or access resource.
+// To prevent misuse, a driver resource ID must be at most 2048 characters and consist only of
+// alphanumeric characters ([a-z0-9A-Z]), dashes (-), dots (.), and underscores (_).
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=2048
+// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9._-]+$`
+type DriverResourceID string
+
 // TimestampedError contains an error message with timestamp.
 type TimestampedError struct {
 	// time is the timestamp when the error was encountered.

client/config/crd/objectstorage.k8s.io_buckets.yaml

@@ -40,31 +40,49 @@ spec:
           spec:
             description: spec defines the desired state of Bucket
             properties:
-              bucketClaim:
+              bucketClaimRef:
                 description: |-
-                  bucketClaim references the BucketClaim that resulted in the creation of this Bucket.
+                  bucketClaimRef 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.
                 properties:
                   name:
-                    description: name is the name of the BucketClaim being referenced.
+                    description: |-
+                      name is the name of the BucketClaim being referenced.
+                      Must be a valid Kubernetes resource name: at most 253 characters and consisting only of
+                      lower-case alphanumeric characters, hyphens, and periods, starting and ending with an
+                      alphanumeric character.
                     maxLength: 253
                     minLength: 1
                     type: string
                     x-kubernetes-validations:
+                    - message: name must be a valid resource name
+                      rule: '!format.dns1123Subdomain().validate(self).hasValue()'
                     - message: name is immutable
                       rule: self == oldSelf
                   namespace:
-                    description: namespace is the namespace of the BucketClaim being
-                      referenced.
-                    maxLength: 253
+                    description: |-
+                      namespace is the namespace of the BucketClaim being referenced.
+                      Must be a valid Kubernetes Namespace name: at most 63 characters and consisting only of
+                      lower-case alphanumeric characters and hyphens, starting and ending with alphanumerics.
+                      It must be at most 63 characters in length and consist only of lower-case alphanumeric
+                      characters and hyphens, and must start and end with an alphanumeric character.
+                    maxLength: 63
                     minLength: 1
                     type: string
                     x-kubernetes-validations:
+                    - message: namespace must be a valid namespace name
+                      rule: '!format.dns1123Label().validate(self).hasValue()'
                     - message: namespace is immutable
                       rule: self == oldSelf
                   uid:
-                    description: uid is the UID of the BucketClaim being referenced.
+                    description: |-
+                      uid is the UID of the BucketClaim being referenced.
+                      Must be a valid Kubernetes UID: RFC 4122 form with lowercase hexadecimal characters
+                      (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
+                    maxLength: 36
+                    minLength: 36
+                    pattern: ^[0-9a-f]{8}-([0-9a-f]{4}\-){3}[0-9a-f]{12}$
                     type: string
                     x-kubernetes-validations:
                     - message: uid is immutable once set
@@ -90,9 +108,13 @@ spec:
                 - Delete
                 type: string
               driverName:
-                description: driverName is the name of the driver that fulfills requests
-                  for this Bucket.
+                description: |-
+                  driverName is the name of the driver that fulfills requests for this Bucket.
+                  Must be 63 characters or less, beginning and ending with an alphanumeric character
+                  ([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between.
+                maxLength: 63
                 minLength: 1
+                pattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-\.]{0,61}[a-zA-Z0-9])?$
                 type: string
                 x-kubernetes-validations:
                 - message: driverName is immutable
@@ -101,9 +123,13 @@ spec:
                 description: |-
                   existingBucketID is the unique identifier for an existing backend bucket known to the driver.
                   Use driver documentation to determine how to set this value.
-                  This field is used only for Bucket static provisioning.
+                  This field is used only for static Bucket provisioning.
                   This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
+                  Must be at most 2048 characters and consist only of alphanumeric characters ([a-z0-9A-Z]),
+                  dashes (-), and dots (.).
+                maxLength: 2048
                 minLength: 1
+                pattern: ^[a-zA-Z0-9._-]+$
                 type: string
                 x-kubernetes-validations:
                 - message: existingBucketID is immutable
@@ -114,6 +140,7 @@ spec:
                 description: |-
                   parameters is an opaque map of driver-specific configuration items passed to the driver that
                   fulfills requests for this Bucket.
+                minProperties: 1
                 type: object
                 x-kubernetes-validations:
                 - message: parameters map is immutable
@@ -122,6 +149,7 @@ spec:
                 description: |-
                   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.
+                  Possible values: 'S3', 'Azure', 'GCS'.
                 items:
                   description: ObjectProtocol represents an object protocol type.
                   enum:
@@ -135,7 +163,7 @@ spec:
                 - message: protocols list is immutable
                   rule: self == oldSelf
             required:
-            - bucketClaim
+            - bucketClaimRef
             - deletionPolicy
             - driverName
             type: object

docs/src/api/out.md

@@ -333,9 +333,9 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `name` _string_ | name is the name of the BucketClaim being referenced. |  | MaxLength: 253 <br />MinLength: 1 <br /> |
-| `namespace` _string_ | namespace is the namespace of the BucketClaim being referenced. |  | MaxLength: 253 <br />MinLength: 1 <br /> |
-| `uid` _[UID](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#uid-types-pkg)_ | uid is the UID of the BucketClaim being referenced. |  |  |
+| `name` _string_ | name is the name of the BucketClaim being referenced.<br />Must be a valid Kubernetes resource name: at most 253 characters and consisting only of<br />lower-case alphanumeric characters, hyphens, and periods, starting and ending with an<br />alphanumeric character. |  | MaxLength: 253 <br />MinLength: 1 <br /> |
+| `namespace` _string_ | namespace is the namespace of the BucketClaim being referenced.<br />Must be a valid Kubernetes Namespace name: at most 63 characters and consisting only of<br />lower-case alphanumeric characters and hyphens, starting and ending with alphanumerics.<br />It must be at most 63 characters in length and consist only of lower-case alphanumeric<br />characters and hyphens, and must start and end with an alphanumeric character. |  | MaxLength: 63 <br />MinLength: 1 <br /> |
+| `uid` _[UID](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#uid-types-pkg)_ | uid is the UID of the BucketClaim being referenced.<br />Must be a valid Kubernetes UID: RFC 4122 form with lowercase hexadecimal characters<br />(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). |  | MaxLength: 36 <br />MinLength: 36 <br />Pattern: `^[0-9a-f]\{8\}-([0-9a-f]\{4\}\-)\{3\}[0-9a-f]\{12\}$` <br />Type: string <br /> |
 
 
 #### BucketClaimSpec
@@ -492,12 +492,12 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `driverName` _string_ | driverName is the name of the driver that fulfills requests for this Bucket. |  | MinLength: 1 <br /> |
+| `driverName` _[DriverName](#drivername)_ | driverName is the name of the driver that fulfills requests for this Bucket.<br />Must be 63 characters or less, beginning and ending with an alphanumeric character<br />([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between. |  | MaxLength: 63 <br />MinLength: 1 <br />Pattern: `^[a-zA-Z0-9]([a-zA-Z0-9\-\.]\{0,61\}[a-zA-Z0-9])?$` <br /> |
 | `deletionPolicy` _[BucketDeletionPolicy](#bucketdeletionpolicy)_ | deletionPolicy determines whether a Bucket should be deleted when its bound BucketClaim is<br />deleted. This is mutable to allow Admins to change the policy after creation.<br />Possible values:<br /> - Retain: keep both the Bucket object and the backend bucket<br /> - Delete: delete both the Bucket object and the backend bucket |  | Enum: [Retain Delete] <br /> |
-| `parameters` _object (keys:string, values:string)_ | parameters is an opaque map of driver-specific configuration items passed to the driver that<br />fulfills requests for this Bucket. |  |  |
-| `protocols` _[ObjectProtocol](#objectprotocol) array_ | protocols lists object store protocols that the provisioned Bucket must support.<br />If specified, COSI will verify that each item is advertised as supported by the driver. |  | Enum: [S3 Azure GCS] <br /> |
-| `bucketClaim` _[BucketClaimReference](#bucketclaimreference)_ | bucketClaim references the BucketClaim that resulted in the creation of this Bucket.<br />For statically-provisioned buckets, set the namespace and name of the BucketClaim that is<br />allowed to bind to this Bucket. |  |  |
-| `existingBucketID` _string_ | existingBucketID is the unique identifier for an existing backend bucket known to the driver.<br />Use driver documentation to determine how to set this value.<br />This field is used only for Bucket static provisioning.<br />This field will be empty when the Bucket is dynamically provisioned from a BucketClaim. |  | MinLength: 1 <br /> |
+| `parameters` _object (keys:string, values:string)_ | parameters is an opaque map of driver-specific configuration items passed to the driver that<br />fulfills requests for this Bucket. |  | MinProperties: 1 <br /> |
+| `protocols` _[ObjectProtocol](#objectprotocol) array_ | protocols lists object store protocols that the provisioned Bucket must support.<br />If specified, COSI will verify that each item is advertised as supported by the driver.<br />Possible values: 'S3', 'Azure', 'GCS'. |  | Enum: [S3 Azure GCS] <br /> |
+| `bucketClaimRef` _[BucketClaimReference](#bucketclaimreference)_ | bucketClaimRef references the BucketClaim that resulted in the creation of this Bucket.<br />For statically-provisioned buckets, set the namespace and name of the BucketClaim that is<br />allowed to bind to this Bucket. |  |  |
+| `existingBucketID` _[DriverResourceID](#driverresourceid)_ | existingBucketID is the unique identifier for an existing backend bucket known to the driver.<br />Use driver documentation to determine how to set this value.<br />This field is used only for static Bucket provisioning.<br />This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.<br />Must be at most 2048 characters and consist only of alphanumeric characters ([a-z0-9A-Z]),<br />dashes (-), and dots (.). |  | MaxLength: 2048 <br />MinLength: 1 <br />Pattern: `^[a-zA-Z0-9._-]+$` <br />Type: string <br /> |
 
 
 #### BucketStatus
@@ -543,6 +543,43 @@ _Appears in:_
 
 
 
+#### DriverName
+
+_Underlying type:_ _string_
+
+DriverName represents the name of a driver.
+Must be 63 characters or less, beginning and ending with an alphanumeric character
+([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between.
+
+_Validation:_
+- MaxLength: 63
+- MinLength: 1
+- Pattern: `^[a-zA-Z0-9]([a-zA-Z0-9\-\.]{0,61}[a-zA-Z0-9])?$`
+
+_Appears in:_
+- [BucketSpec](#bucketspec)
+
+
+
+#### DriverResourceID
+
+_Underlying type:_ _string_
+
+DriverResourceID represents a unique identifier for a driver bucket or access resource.
+To prevent misuse, a driver resource ID must be at most 2048 characters and consist only of
+alphanumeric characters ([a-z0-9A-Z]), dashes (-), dots (.), and underscores (_).
+
+_Validation:_
+- MaxLength: 2048
+- MinLength: 1
+- Pattern: `^[a-zA-Z0-9._-]+$`
+- Type: string
+
+_Appears in:_
+- [BucketSpec](#bucketspec)
+
+
+
 #### ObjectProtocol
 
 _Underlying type:_ _string_