diff --git a/README.md b/README.md index a9d16bad..46eff222 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,73 @@ -COSI repos and images: - -[Spec](https://github.com/kubernetes-sigs/container-object-storage-interface-spec) \ -[API](https://github.com/kubernetes-sigs/container-object-storage-interface-api) \ -[Controller](https://github.com/kubernetes-sigs/container-object-storage-interface-controller)
-  - [images: cosi-controller](https://quay.io/repository/containerobjectstorage/objectstorage-controller?tab=tags) \ - [Provisioner Sidecar](https://github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar)
-   - images: cosi-provisioner \ - [CSI Adapter](https://github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter)
-   - images: cosi-node-adapter - -
+![version](https://img.shields.io/badge/status-pre--alpha-lightgrey) ![apiVersion](https://img.shields.io/badge/apiVersion-v1alpha1-lightgreen) + + +# Container Object Storage Interface Spec + +This repository hosts the API defintion of the Custom Resource Definitions (CRD) used for the Container Object Storage Interface (COSI) project. The provisioned unit of storage is a `Bucket`. The following CRDs are defined for managing the lifecycle of Buckets: + + - BucketRequest - Represents a request to provision a Bucket + - BucketClass - Represents a class of Buckets with similar characteristics + - Bucket - Represents a Bucket or its equivalent in the storage backend -COSI deprecated repos: + The following CRDs are defined for managing the lifecycle of workloads accessing the Bucket: + + - BucketAccessRequest - Represents a request to access a Bucket + - BucketAccessClass - Represents a class of accesors with similar access requirements + - BucketAccess - Represents a access token or service account in the storage backend -[Spec](https://github.com/container-object-storage-interface/spec) \ -[API](https://github.com/container-object-storage-interface/api) \ -[Manager (i.e. Controller)](https://github.com/container-object-storage-interface/cosi-controller-manager) \ -[Provisioner Sidecar](https://github.com/container-object-storage-interface/cosi-provisioner-sidecar) \ -[Ephemeral CSI Driver](https://github.com/container-object-storage-interface/ephemeral-csi-driver) +**NOTE**: All of the APIs are defined under the API group `objectstorage.k8s.io`. +For more information about COSI, visit our [documentation](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/index.md). -# Container Object Storage Interface (COSI) API +## Developer Guide -API definitions for Container Object Storage. +All API definitions are in [`apis/objectstorage.k8s.io/`](./apis/objectstorage.k8s.io/). All API changes **_MUST_** satisfy the following requirements: -## Community, discussion, contribution, and support + - Must be backwards compatible + - Must be in-sync with the API definitions in [sigs.k8s.io/container-object-storage-interface-spec](https://github.com/kubernetes-sigs/container-object-storage-interface-spec) + +### Build and Test + +1. Test and Build the project -If you are new to a SIG Storage project, check out this [contributing guide](https://github.com/kubernetes/community/blob/master/sig-storage/CONTRIBUTING.md) -and the [community page](https://github.com/kubernetes/community/tree/master/sig-storage). +``` +make all +``` -If you are new to the SIG Storage COSI project, check out the [spec](https://github.com/kubernetes-sigs/container-object-storage-interface-spec/blob/master/spec.md), [KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support), and [project board](https://github.com/orgs/kubernetes-sigs/projects/). +2. Generate CRDs -Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/). +``` +make codegen +``` + +## Adding new fields to protocols + +1. Create a new issue raising a RFC for the changes following this format: + +Title: [RFC] Changes to protocol xyz +> **Info**: +> 1. Protocol: +> 2. Fields Added: +> 3. Why is this change neccessary? +> ...(describe why here)... +> 4. Which other COSI projects are affected by this change? +> 5. Upgrade plan +> (ignore if it doesn't apply) + +## References + + - [Documentation](docs/index.md) + - [Deployment Guide](docs/deployment-guide.md) + - [Weekly Meetings](docs/meetings.md) + - [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8) + +## Community, discussion, contribution, and support You can reach the maintainers of this project at: -- [Slack](https://kubernetes.slack.com/messages/sig-storage-cosi) -- [Mailing List](https://groups.google.com/g/container-object-storage-interface-wg?pli=1) + - [#sig-storage-cosi](https://kubernetes.slack.com/messages/sig-storage-cosi) slack channel + - [container-object-storage-interface](https://groups.google.com/g/container-object-storage-interface-wg?pli=1) mailing list ### Code of conduct -Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). \ No newline at end of file +Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..afb7cc5b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,40 @@ +Container Object Storage Interface (COSI) +------------------------------------------ + +Container Object Storage Interface (COSI) is a set of abstractions for provisioning and management of object storage. It aims to be a common layer of abstraction across multiple object storage vendors, such that workloads can request and automatically be provisioned object storage buckets. + +The goals of this project are: + + - Automate object storage provisioning, access and management + - Provide a common layer of abstraction for consuming object storage + - Facilitate lift and shift of workloads across object storage providers (i.e. prevent vendor lock-in) + +## Why another standard? + +Kubernetes abstracts file/block storage via the CSI standard. The primitives for file/block storage do not extend well to object storage. Here is the **_extremely_** concise and incomplete list of reasons why: + + - Unit of provisioned storage - Bucket instead of filesystem mount or blockdevice. + - Access is over the network instead of local POSIX calls. + - No common protocol for consumption across various implementations of object storage. + - Management policies and primitives - for instance, mounting and unmounting do not apply to object storage. + +The existing primitives in CSI do not apply to objectstorage. Thus the need for a new standard to automate the management of objectstorage. + +## Links + + - [User Guide](user-guide.md) + - [Deployment Guide](deployment-guide.md) + - [How to write a COSI driver](how-to-write-a-cosi-driver.md) + - [How to make your application COSI-compatible](how-to-make-your-application-cosi-compatible.md) + +## Advanced + + - [Protocols](protocols.md) + - [Architecture](architecture.md) + - [Internals](internals.md) + +## Other + + - [Project Board](https://github.com/orgs/kubernetes-sigs/projects/8) + - [Weekly Meetings](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/meetings.md) + - [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8) diff --git a/docs/meetings.md b/docs/meetings.md new file mode 100644 index 00000000..86fc7d7e --- /dev/null +++ b/docs/meetings.md @@ -0,0 +1,23 @@ +--- +title: Weekly Community Meetings +--- + +# Weekly Meetings +---------------- + +## Engineering meeting + - Monday at 11:00AM - 11:30AM PT + - [SIG Storage Zoom Meeting Room](https://zoom.us/s/614261834) (Password is ```77777```) + - [Meeting Recordings](https://www.youtube.com/channel/UCiOeuJ6L4rYNC1jwZFRmC5Q/search?query=object+bucket+standup) + - [Meeting Notes](https://docs.google.com/document/d/1KTh1y9klby64t7btNULtxLWDkRC9SAWE-SZnJeFZqug/edit?usp=sharing) + +## Community Meeting + - [Thursday at 10:00AM - 11:00AM PT](https://calendar.google.com/calendar/event?eid=MmM5bzU5bWtjaG41Z2dlcXViaWtmNGxpbmZfMjAyMTAxMjhUMTgwMDAwWiB2dnZvNDhyNmNwcmNjaWkxbHNhdmE2cDJ1Y0Bn&ctz=America/Los_Angeles) + - [SIG Storage Zoom Meeting Room](https://zoom.us/s/614261834) (Password is ```77777```) + - [Meeting Recordings](https://www.youtube.com/channel/UCiOeuJ6L4rYNC1jwZFRmC5Q/search?query=object+bucket+review) + - [Meeting Notes](https://docs.google.com/document/d/1KTh1y9klby64t7btNULtxLWDkRC9SAWE-SZnJeFZqug/edit?usp=sharing) + +## Organizers + + - Sidhartha Mani (@wlan0) + - Jeff Vance (@jeffvance)