Skip to content

Commit 6fe2318

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #163 from BlaineEXE/sidecar-bucket-reconcile
Add initial sidecar implementation for dynamic Bucket provisioning
2 parents 52e4283 + 30aa78d commit 6fe2318

File tree

30 files changed

+3965
-529
lines changed

30 files changed

+3965
-529
lines changed

‎client/apis/objectstorage/v1alpha2/bucket_types.go‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,14 @@ type BucketSpec struct {
7070
// allowed to bind to this Bucket.
7171
// +required
7272
BucketClaimRef BucketClaimReference `json:"bucketClaim"`
73+
74+
// existingBucketID is the unique identifier for an existing backend bucket known to the driver.
75+
// Use driver documentation to determine how to set this value.
76+
// This field is used only for Bucket static provisioning.
77+
// This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
78+
// +optional
79+
// +kubebuilder:validation:XValidation:message="existingBucketID is immutable",rule="self == oldSelf"
80+
ExistingBucketID string `json:"existingBucketID,omitempty"`
7381
}
7482

7583
// BucketClaimReference is a reference to a BucketClaim object.
@@ -97,11 +105,30 @@ type BucketClaimReference struct {
97105

98106
// BucketStatus defines the observed state of Bucket.
99107
type BucketStatus struct {
100-
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
101-
// Important: Run "make" to regenerate code after modifying this file
108+
// readyToUse indicates that the bucket is ready for consumption by workloads.
109+
ReadyToUse bool `json:"readyToUse"`
110+
111+
// bucketID is the unique identifier for the backend bucket known to the driver.
112+
// Once set, this is immutable.
113+
// +kubebuilder:validation:XValidation:message="boundBucketName is immutable",rule="oldSelf == '' || self == oldSelf"
114+
BucketID string `json:"bucketID"`
102115

103-
// For Kubernetes API conventions, see:
104-
// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
116+
// protocols is the set of protocols the Bucket reports to support. BucketAccesses can request
117+
// access to this BucketClaim using any of the protocols reported here.
118+
// +optional
119+
// +listType=set
120+
Protocols []ObjectProtocol `json:"protocols"`
121+
122+
// BucketInfo reported by the driver, rendered in the COSI_<PROTOCOL>_<KEY> format used for the
123+
// BucketAccess Secret. e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT.
124+
// This should not contain any sensitive information.
125+
// +optional
126+
BucketInfo map[string]string `json:"bucketInfo,omitempty"`
127+
128+
// Error holds the most recent error message, with a timestamp.
129+
// This is cleared when provisioning is successful.
130+
// +optional
131+
Error *TimestampedError `json:"error,omitempty"`
105132
}
106133

107134
// +kubebuilder:object:root=true

‎client/apis/objectstorage/v1alpha2/bucketaccess_types.go‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,20 @@ import (
2020
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
2121
)
2222

23+
// BucketAccessAuthenticationType specifies what authentication mechanism is used for provisioning
24+
// bucket access.
25+
type BucketAccessAuthenticationType string
26+
27+
const (
28+
// The driver will generate a protocol-appropriate access key that clients can use to
29+
// authenticate to the backend object store.
30+
BucketAccessAuthenticationTypeKey = "Key"
31+
32+
// The driver should configure the system such that Pods using the given ServiceAccount
33+
// authenticate to the backend object store automatically.
34+
BucketAccessAuthenticationTypeServiceAccount = "ServiceAccount"
35+
)
36+
2337
// BucketAccessSpec defines the desired state of BucketAccess
2438
type BucketAccessSpec struct {
2539
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster

‎client/apis/objectstorage/v1alpha2/protocols.go‎

Lines changed: 114 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,129 @@ limitations under the License.
1717
package v1alpha2
1818

1919
/*
20-
This file contains all definitions for the various object store protocols.
20+
This file describes the end-user representation of the various object store protocols.
2121
*/
2222

23+
// TODO: can we write doc generation and linting for the definitions in this file?
24+
2325
// ObjectProtocol represents an object protocol type.
2426
type ObjectProtocol string
2527

2628
const (
2729
// ObjectProtocolS3 represents the S3 object protocol type.
28-
ObjectProtocolS3 = "S3"
30+
ObjectProtocolS3 ObjectProtocol = "S3"
2931

3032
// ObjectProtocolS3 represents the Azure Blob object protocol type.
31-
ObjectProtocolAzure = "Azure"
33+
ObjectProtocolAzure ObjectProtocol = "Azure"
3234

3335
// ObjectProtocolS3 represents the Google Cloud Storage object protocol type.
34-
ObjectProtocolGcs = "GCS"
36+
ObjectProtocolGcs ObjectProtocol = "GCS"
37+
)
38+
39+
// A CosiEnvVar defines a COSI environment variable that contains backend bucket or access info.
40+
// Vars marked "Required" will be present with non-empty values in BucketAccess Secrets.
41+
// Some required vars may only be required in certain contexts, like when a specific
42+
// AuthenticationType is used.
43+
// Some vars are only relevant for specific protocols.
44+
// Non-relevant vars will not be present, even when marked "Required".
45+
// Vars are used as data keys in BucketAccess Secrets.
46+
// Vars must be all-caps and must begin with `COSI_`.
47+
type CosiEnvVar string
48+
49+
// A BucketInfoVar defines a protocol-specific COSI environment variable that contains backend
50+
// bucket info.
51+
// All protocol-specific vars include the all-caps protocol name after `COSI_`. E.g., `COSI_AZURE_`.
52+
type BucketInfoVar CosiEnvVar
53+
54+
// A CredentialVar defines a protocol-specific COSI environment variable that contains backend
55+
// bucket access credential info.
56+
// All protocol-specific vars include the all-caps protocol name after `COSI_`. E.g., `COSI_AZURE_`.
57+
type CredentialVar CosiEnvVar
58+
59+
const (
60+
// Required. The protocol associated with a BucketAccess.
61+
// Will be a string representing an ObjectProtocol type.
62+
BucketInfoVar_Protocol BucketInfoVar = "COSI_PROTOCOL"
63+
64+
// Optional. The certificate authority that clients can use to authenticate a BucketAccess.
65+
CredentialVar_CertificateAuthority CredentialVar = "COSI_CERTIFICATE_AUTHORITY"
66+
)
67+
68+
/*
69+
* S3 protocol variables
70+
*/
71+
72+
// bucket info vars
73+
const (
74+
// Required. The S3 bucket ID as used by clients.
75+
BucketInfoVar_S3_BucketId BucketInfoVar = "COSI_S3_BUCKET_ID"
76+
77+
// Required. The S3 endpoint for the bucket.
78+
BucketInfoVar_S3_Endpoint BucketInfoVar = "COSI_S3_ENDPOINT"
79+
80+
// Required. The S3 region for the bucket.
81+
BucketInfoVar_S3_Region BucketInfoVar = "COSI_S3_REGION"
82+
83+
// Required. The S3 addressing style. One of `path` or `virtual`.
84+
// See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html.
85+
BucketInfoVar_S3_AddressingStyle BucketInfoVar = "COSI_S3_ADDRESSING_STYLE"
86+
)
87+
88+
// nolint:gosec // credential vars, not hardcoded credentials
89+
const (
90+
// Required for `AuthenticationType=Key`. The S3 access key ID.
91+
CredentialVar_S3_AccessKeyId CredentialVar = "COSI_S3_ACCESS_KEY_ID" // nolint:gosec // no a cred
92+
93+
// Required for `AuthenticationType=Key`. The S3 access secret key.
94+
CredentialVar_S3_AccessSecretKey CredentialVar = "COSI_S3_ACCESS_SECRET_KEY" // nolint:gosec // no a cred
95+
)
96+
97+
/*
98+
* Azure protocol variables
99+
*/
100+
101+
// bucket info vars
102+
const (
103+
// Required. The ID of the Azure storage account.
104+
BucketInfoVar_Azure_StorageAccount BucketInfoVar = "COSI_AZURE_STORAGE_ACCOUNT"
105+
)
106+
107+
// nolint:gosec // credential vars, not hardcoded credentials
108+
const (
109+
// Required for `AuthenticationType=Key`. Azure SAS access token.
110+
// Note that this includes the resource URI as well as token in its definition.
111+
// See: https://learn.microsoft.com/en-us/azure/storage/common/media/storage-sas-overview/sas-storage-uri.svg
112+
CredentialVar_Azure_AccessToken CredentialVar = "COSI_AZURE_ACCESS_TOKEN"
113+
114+
// Optional. The timestamp when access will expire.
115+
// Empty if unset. Otherwise, date+time in ISO 8601 format.
116+
CredentialVar_Azure_ExpiryTimestamp CredentialVar = "COSI_AZURE_EXPIRY_TIMESTAMP"
117+
)
118+
119+
/*
120+
* Google Cloud Storage (GCS) protocol variables
121+
*/
122+
123+
// bucket info vars
124+
const (
125+
// Required. The GCS project ID.
126+
BucketInfoVar_GCS_ProjectId BucketInfoVar = "COSI_GCS_PROJECT_ID"
127+
128+
// Required. GCS bucket name as used by clients.
129+
BucketInfoVar_GCS_BucketName BucketInfoVar = "COSI_GCS_BUCKET_NAME"
130+
)
131+
132+
// nolint:gosec // credential vars, not hardcoded credentials
133+
const (
134+
// Required for `AuthenticationType=Key`. HMAC access ID.
135+
CredentialVar_GCS_AccessId CredentialVar = "COSI_GCS_ACCESS_ID"
136+
137+
// Required for `AuthenticationType=Key`. HMAC secret.
138+
CredentialVar_GCS_AccessSecret CredentialVar = "COSI_GCS_ACCESS_SECRET"
139+
140+
// GCS private key name.
141+
CredentialVar_GCS_PrivateKeyName CredentialVar = "COSI_GCS_PRIVATE_KEY_NAME"
142+
143+
// GCS service account name.
144+
CredentialVar_GCS_ServiceAccount CredentialVar = "COSI_GCS_SERVICE_ACCOUNT"
35145
)

‎client/apis/objectstorage/v1alpha2/zz_generated.deepcopy.go‎

Lines changed: 18 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,16 @@ spec:
9393
x-kubernetes-validations:
9494
- message: driverName is immutable
9595
rule: self == oldSelf
96+
existingBucketID:
97+
description: |-
98+
existingBucketID is the unique identifier for an existing backend bucket known to the driver.
99+
Use driver documentation to determine how to set this value.
100+
This field is used only for Bucket static provisioning.
101+
This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
102+
type: string
103+
x-kubernetes-validations:
104+
- message: existingBucketID is immutable
105+
rule: self == oldSelf
96106
parameters:
97107
additionalProperties:
98108
type: string
@@ -122,6 +132,54 @@ spec:
122132
type: object
123133
status:
124134
description: status defines the observed state of Bucket
135+
properties:
136+
bucketID:
137+
description: |-
138+
bucketID is the unique identifier for the backend bucket known to the driver.
139+
Once set, this is immutable.
140+
type: string
141+
x-kubernetes-validations:
142+
- message: boundBucketName is immutable
143+
rule: oldSelf == '' || self == oldSelf
144+
bucketInfo:
145+
additionalProperties:
146+
type: string
147+
description: |-
148+
BucketInfo reported by the driver, rendered in the COSI_<PROTOCOL>_<KEY> format used for the
149+
BucketAccess Secret. e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT.
150+
This should not contain any sensitive information.
151+
type: object
152+
error:
153+
description: |-
154+
Error holds the most recent error message, with a timestamp.
155+
This is cleared when provisioning is successful.
156+
properties:
157+
message:
158+
description: |-
159+
message is a string detailing the encountered error.
160+
NOTE: message will be logged, and it should not contain sensitive information.
161+
type: string
162+
time:
163+
description: time is the timestamp when the error was encountered.
164+
format: date-time
165+
type: string
166+
type: object
167+
protocols:
168+
description: |-
169+
protocols is the set of protocols the Bucket reports to support. BucketAccesses can request
170+
access to this BucketClaim using any of the protocols reported here.
171+
items:
172+
description: ObjectProtocol represents an object protocol type.
173+
type: string
174+
type: array
175+
x-kubernetes-list-type: set
176+
readyToUse:
177+
description: readyToUse indicates that the bucket is ready for consumption
178+
by workloads.
179+
type: boolean
180+
required:
181+
- bucketID
182+
- readyToUse
125183
type: object
126184
required:
127185
- spec

‎docs/src/api/out.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,8 @@ _Appears in:_
6666
| `status` _[BucketAccessStatus](#bucketaccessstatus)_ | status defines the observed state of BucketAccess | | |
6767

6868

69+
70+
6971
#### BucketAccessClass
7072

7173

@@ -370,6 +372,8 @@ _Appears in:_
370372
| `Delete` | BucketDeletionPolicyDelete configures COSI to delete the Bucket object as well as the backend<br />bucket when a Bucket resource is deleted.<br /> |
371373

372374

375+
376+
373377
#### BucketList
374378

375379

@@ -408,6 +412,7 @@ _Appears in:_
408412
| `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. | | |
409413
| `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. | | |
410414
| `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. | | |
415+
| `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. | | |
411416

412417

413418
#### BucketStatus
@@ -421,6 +426,36 @@ BucketStatus defines the observed state of Bucket.
421426
_Appears in:_
422427
- [Bucket](#bucket)
423428

429+
| Field | Description | Default | Validation |
430+
| --- | --- | --- | --- |
431+
| `readyToUse` _boolean_ | readyToUse indicates that the bucket is ready for consumption by workloads. | | |
432+
| `bucketID` _string_ | bucketID is the unique identifier for the backend bucket known to the driver.<br />Once set, this is immutable. | | |
433+
| `protocols` _[ObjectProtocol](#objectprotocol) array_ | protocols is the set of protocols the Bucket reports to support. BucketAccesses can request<br />access to this BucketClaim using any of the protocols reported here. | | |
434+
| `bucketInfo` _object (keys:string, values:string)_ | BucketInfo reported by the driver, rendered in the COSI_<PROTOCOL>_<KEY> format used for the<br />BucketAccess Secret. e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT.<br />This should not contain any sensitive information. | | |
435+
| `error` _[TimestampedError](#timestampederror)_ | Error holds the most recent error message, with a timestamp.<br />This is cleared when provisioning is successful. | | |
436+
437+
438+
#### CosiEnvVar
439+
440+
_Underlying type:_ _string_
441+
442+
A CosiEnvVar defines a COSI environment variable that contains backend bucket or access info.
443+
Vars marked "Required" will be present with non-empty values in BucketAccess Secrets.
444+
Some required vars may only be required in certain contexts, like when a specific
445+
AuthenticationType is used.
446+
Some vars are only relevant for specific protocols.
447+
Non-relevant vars will not be present, even when marked "Required".
448+
Vars are used as data keys in BucketAccess Secrets.
449+
Vars must be all-caps and must begin with `COSI_`.
450+
451+
452+
453+
_Appears in:_
454+
- [BucketInfoVar](#bucketinfovar)
455+
- [CredentialVar](#credentialvar)
456+
457+
458+
424459

425460

426461
#### ObjectProtocol
@@ -435,7 +470,13 @@ _Appears in:_
435470
- [BucketClaimSpec](#bucketclaimspec)
436471
- [BucketClaimStatus](#bucketclaimstatus)
437472
- [BucketSpec](#bucketspec)
473+
- [BucketStatus](#bucketstatus)
438474

475+
| Field | Description |
476+
| --- | --- |
477+
| `S3` | ObjectProtocolS3 represents the S3 object protocol type.<br /> |
478+
| `Azure` | ObjectProtocolS3 represents the Azure Blob object protocol type.<br /> |
479+
| `GCS` | ObjectProtocolS3 represents the Google Cloud Storage object protocol type.<br /> |
439480

440481

441482
#### TimestampedError
@@ -448,6 +489,7 @@ TimestampedError contains an error message with timestamp.
448489

449490
_Appears in:_
450491
- [BucketClaimStatus](#bucketclaimstatus)
492+
- [BucketStatus](#bucketstatus)
451493

452494
| Field | Description | Default | Validation |
453495
| --- | --- | --- | --- |

0 commit comments

Comments
 (0)