API Reference
Packages
objectstorage.k8s.io/v1alpha2
Package v1alpha2 contains API Schema definitions for the objectstorage v1alpha2 API group.
Resource Types
- Bucket
- BucketAccess
- BucketAccessClass
- BucketAccessClassList
- BucketAccessList
- BucketClaim
- BucketClaimList
- BucketClass
- BucketClassList
- BucketList
AccessedBucket
AccessedBucket identifies a Bucket and corresponding access parameters.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
bucketName string | bucketName is the name of a Bucket the access should have permissions for. | MaxLength: 253 MinLength: 1 | |
accessMode BucketAccessMode | accessMode is the Read/Write access mode that the access should have for the bucket. | Enum: [ReadWrite ReadOnly WriteOnly] |
Bucket
Bucket is the Schema for the buckets API
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | Bucket | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BucketSpec | spec defines the desired state of Bucket | ||
status BucketStatus | status defines the observed state of Bucket |
BucketAccess
BucketAccess is the Schema for the bucketaccesses API
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketAccess | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BucketAccessSpec | spec defines the desired state of BucketAccess | ||
status BucketAccessStatus | status defines the observed state of BucketAccess |
BucketAccessAuthenticationType
Underlying type: string
BucketAccessAuthenticationType specifies what authentication mechanism is used for provisioning bucket access.
Validation:
- Enum: [ Key ServiceAccount]
Appears in:
BucketAccessClass
BucketAccessClass is the Schema for the bucketaccessclasses API
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketAccessClass | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BucketAccessClassSpec | spec defines the desired state of BucketAccessClass |
BucketAccessClassList
BucketAccessClassList contains a list of BucketAccessClass
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketAccessClassList | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items BucketAccessClass array |
BucketAccessClassSpec
BucketAccessClassSpec defines the desired state of BucketAccessClass
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
driverName string | driverName is the name of the driver that fulfills requests for this BucketAccessClass. | MinLength: 1 | |
authenticationType BucketAccessAuthenticationType | authenticationType specifies which authentication mechanism is used bucket access. Possible values: - Key: The driver should generate a protocol-appropriate access key that clients can use to authenticate to the backend object store. - ServiceAccount: The driver should configure the system such that Pods using the given ServiceAccount authenticate to the backend object store automatically. | Enum: [Key ServiceAccount] | |
parameters object (keys:string, values:string) | parameters is an opaque map of driver-specific configuration items passed to the driver that fulfills requests for this BucketAccessClass. | ||
featureOptions BucketAccessFeatureOptions | featureOptions can be used to adjust various COSI access provisioning behaviors. |
BucketAccessFeatureOptions
BucketAccessFeatureOptions defines various COSI access provisioning behaviors.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
disallowedBucketAccessModes BucketAccessMode array | disallowedBucketAccessModes is a list of disallowed Read/Write access modes. A BucketAccess using this class will not be allowed to request access to a BucketClaim with any access mode listed here. | Enum: [ReadWrite ReadOnly WriteOnly] | |
disallowMultiBucketAccess boolean | disallowMultiBucketAccess disables the ability for a BucketAccess to reference multiple BucketClaims when set. |
BucketAccessList
BucketAccessList contains a list of BucketAccess
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketAccessList | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items BucketAccess array |
BucketAccessMode
Underlying type: string
BucketAccessMode describes the Read/Write mode an access should have for a bucket.
Validation:
- Enum: [ReadWrite ReadOnly WriteOnly]
Appears in:
| Field | Description |
|---|---|
ReadWrite | BucketAccessModeReadWrite represents read-write access mode. |
ReadOnly | BucketAccessModeReadOnly represents read-only access mode. |
WriteOnly | BucketAccessModeWriteOnly represents write-only access mode. |
BucketAccessSpec
BucketAccessSpec defines the desired state of BucketAccess
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
bucketClaims BucketClaimAccess array | bucketClaims is a list of BucketClaims the provisioned access must have permissions for, along with per-BucketClaim access parameters and system output definitions. At least one BucketClaim must be referenced. Multiple references to the same BucketClaim are not permitted. | MinItems: 1 | |
bucketAccessClassName string | bucketAccessClassName selects the BucketAccessClass for provisioning the access. | MaxLength: 253 MinLength: 1 | |
protocol ObjectProtocol | protocol is the object storage protocol that the provisioned access must use. | Enum: [S3 Azure GCS] | |
serviceAccountName string | serviceAccountName is the name of the Kubernetes ServiceAccount that user application Pods intend to use for access to referenced BucketClaims. This has different behavior based on the BucketAccessClass's defined AuthenticationType: - Key: This field is ignored. - ServiceAccount: This field is required. The driver should configure the system so that Pods using the ServiceAccount authenticate to the object storage backend automatically. | MaxLength: 253 |
BucketAccessStatus
BucketAccessStatus defines the observed state of BucketAccess.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
readyToUse boolean | readyToUse indicates that the BucketAccess is ready for consumption by workloads. | ||
accountID string | accountID is the unique identifier for the backend access known to the driver. This field is populated by the COSI Sidecar once access has been successfully granted. | ||
accessedBuckets AccessedBucket array | accessedBuckets is a list of Buckets the provisioned access must have permissions for, along with per-Bucket access options. This field is populated by the COSI Controller based on the referenced BucketClaims in the spec. | ||
driverName string | driverName holds a copy of the BucketAccessClass driver name from the time of BucketAccess provisioning. This field is populated by the COSI Controller. | ||
authenticationType BucketAccessAuthenticationType | authenticationType holds a copy of the BucketAccessClass authentication type from the time of BucketAccess provisioning. This field is populated by the COSI Controller. | Enum: [ Key ServiceAccount] | |
parameters object (keys:string, values:string) | parameters holds a copy of the BucketAccessClass parameters from the time of BucketAccess provisioning. This field is populated by the COSI Controller. | ||
error TimestampedError | error holds the most recent error message, with a timestamp. This is cleared when provisioning is successful. |
BucketClaim
BucketClaim is the Schema for the bucketclaims API
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketClaim | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BucketClaimSpec | spec defines the desired state of BucketClaim | ||
status BucketClaimStatus | status defines the observed state of BucketClaim |
BucketClaimAccess
BucketClaimAccess selects a BucketClaim for access, defines access parameters for the corresponding bucket, and specifies where user-consumable bucket information and access credentials for the accessed bucket will be stored.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
bucketClaimName string | bucketClaimName is the name of a BucketClaim the access should have permissions for. The BucketClaim must be in the same Namespace as the BucketAccess. | MaxLength: 253 MinLength: 1 | |
accessMode BucketAccessMode | accessMode is the Read/Write access mode that the access should have for the bucket. Possible values: ReadWrite, ReadOnly, WriteOnly. | Enum: [ReadWrite ReadOnly WriteOnly] | |
accessSecretName string | accessSecretName is the name of a Kubernetes Secret that COSI should create and populate with bucket info and access credentials for the bucket. The Secret is created in the same Namespace as the BucketAccess and is deleted when the BucketAccess is deleted and deprovisioned. The Secret name must be unique across all bucketClaimRefs for all BucketAccesses in the same Namespace. | MaxLength: 253 MinLength: 1 |
BucketClaimList
BucketClaimList contains a list of BucketClaim
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketClaimList | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items BucketClaim array |
BucketClaimReference
BucketClaimReference is a reference to a BucketClaim object.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | name is the name of the BucketClaim being referenced. | MaxLength: 253 MinLength: 1 | |
namespace string | 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'. | MaxLength: 253 MinLength: 0 | |
uid UID | uid is the UID of the BucketClaim being referenced. |
BucketClaimSpec
BucketClaimSpec defines the desired state of BucketClaim
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
bucketClassName string | 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. | MaxLength: 253 | |
protocols ObjectProtocol array | 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. | Enum: [S3 Azure GCS] | |
existingBucketName string | 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. | MaxLength: 253 |
BucketClaimStatus
BucketClaimStatus defines the observed state of BucketClaim.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
boundBucketName string | boundBucketName is the name of the Bucket this BucketClaim is bound to. | MaxLength: 253 | |
readyToUse boolean | readyToUse indicates that the bucket is ready for consumption by workloads. | ||
protocols ObjectProtocol array | protocols is the set of protocols the bound Bucket reports to support. BucketAccesses can request access to this BucketClaim using any of the protocols reported here. | Enum: [S3 Azure GCS] | |
error TimestampedError | error holds the most recent error message, with a timestamp. This is cleared when provisioning is successful. |
BucketClass
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.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketClass | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec BucketClassSpec | spec defines the BucketClass. spec is entirely immutable. |
BucketClassList
BucketClassList contains a list of BucketClass
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketClassList | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items BucketClass array |
BucketClassSpec
BucketClassSpec defines the BucketClass.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
driverName string | driverName is the name of the driver that fulfills requests for this BucketClass. | MinLength: 1 | |
deletionPolicy BucketDeletionPolicy | 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 | Enum: [Retain Delete] | |
parameters object (keys:string, values:string) | parameters is an opaque map of driver-specific configuration items passed to the driver that fulfills requests for this BucketClass. |
BucketDeletionPolicy
Underlying type: string
BucketDeletionPolicy configures COSI's behavior when a Bucket resource is deleted.
Validation:
- Enum: [Retain Delete]
Appears in:
| Field | Description |
|---|---|
Retain | BucketDeletionPolicyRetain configures COSI to keep the Bucket object as well as the backend bucket when a Bucket resource is deleted. |
Delete | BucketDeletionPolicyDelete configures COSI to delete the Bucket object as well as the backend bucket when a Bucket resource is deleted. |
BucketList
BucketList contains a list of Bucket
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | objectstorage.k8s.io/v1alpha2 | ||
kind string | BucketList | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items Bucket array |
BucketSpec
BucketSpec defines the desired state of Bucket
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
driverName string | driverName is the name of the driver that fulfills requests for this Bucket. | MinLength: 1 | |
deletionPolicy BucketDeletionPolicy | 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 | Enum: [Retain Delete] | |
parameters object (keys:string, values:string) | parameters is an opaque map of driver-specific configuration items passed to the driver that fulfills requests for this Bucket. | ||
protocols ObjectProtocol array | 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. | Enum: [S3 Azure GCS] | |
bucketClaim BucketClaimReference | 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. | ||
existingBucketID string | 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 will be empty when the Bucket is dynamically provisioned from a BucketClaim. |
BucketStatus
BucketStatus defines the observed state of Bucket.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
readyToUse boolean | readyToUse indicates that the bucket is ready for consumption by workloads. | ||
bucketID string | bucketID is the unique identifier for the backend bucket known to the driver. | ||
protocols ObjectProtocol array | 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. | Enum: [S3 Azure GCS] | |
bucketInfo object (keys:string, values:string) | BucketInfo reported by the driver, rendered in the COSI_ BucketAccess Secret. e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT. This should not contain any sensitive information. | ||
error TimestampedError | Error holds the most recent error message, with a timestamp. This is cleared when provisioning is successful. |
CosiEnvVar
Underlying type: string
A CosiEnvVar defines a COSI environment variable that contains backend bucket or access info.
Vars marked "Required" will be present with non-empty values in BucketAccess Secrets.
Some required vars may only be required in certain contexts, like when a specific
AuthenticationType is used.
Some vars are only relevant for specific protocols.
Non-relevant vars will not be present, even when marked "Required".
Vars are used as data keys in BucketAccess Secrets.
Vars must be all-caps and must begin with COSI_.
Appears in:
ObjectProtocol
Underlying type: string
ObjectProtocol represents an object protocol type.
Validation:
- Enum: [S3 Azure GCS]
Appears in:
| Field | Description |
|---|---|
S3 | ObjectProtocolS3 represents the S3 object protocol type. |
Azure | ObjectProtocolS3 represents the Azure Blob object protocol type. |
GCS | ObjectProtocolS3 represents the Google Cloud Storage object protocol type. |
TimestampedError
TimestampedError contains an error message with timestamp.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
time Time | time is the timestamp when the error was encountered. | ||
message string | message is a string detailing the encountered error. NOTE: message will be logged, and it should not contain sensitive information. |