Document COSI API, resources, and add a simple getting started section #17
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,43 +1,73 @@ | ||
|   | ||
|
|
||
|
|
||
| # 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 | ||
|
|
||
| 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 | ||
|
|
||
| **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). | ||
|
There was a problem hiding this comment. documentation link returns 404 |
||
|
|
||
| ## Developer Guide | ||
|
|
||
| All API definitions are in [`apis/objectstorage.k8s.io/`](./apis/objectstorage.k8s.io/). All API changes **_MUST_** satisfy the following requirements: | ||
|
|
||
| - 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) | ||
|
There was a problem hiding this comment. Should we detail a bit more here, not all of the API but only the protocol structure right? There was a problem hiding this comment. might be overkill for inital doc PR |
||
|
|
||
| ### Build and Test | ||
|
|
||
| 1. Test and Build the project | ||
|
|
||
| ``` | ||
| make all | ||
| ``` | ||
|
|
||
| 2. Generate CRDs | ||
|
|
||
| ``` | ||
| make codegen | ||
| ``` | ||
|
|
||
| ## Adding new fields to protocols | ||
|
There was a problem hiding this comment. We should make this an issue template in the repository. There was a problem hiding this comment. I agree, template is already in place. |
||
|
|
||
| 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) | ||
|
There was a problem hiding this comment. @tparikh is working on the deployment guide |
||
| - [Weekly Meetings](docs/meetings.md) | ||
| - [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8) | ||
|
There was a problem hiding this comment. Project Board & Roadmap point to same board. Might want to consider just one |
||
|
|
||
| ## Community, discussion, contribution, and support | ||
|
|
||
| You can reach the maintainers of this project at: | ||
|
|
||
| - [#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). | ||
|
There was a problem hiding this comment. This link is one level more direct: https://github.com/kubernetes/community/blob/master/code-of-conduct.md There was a problem hiding this comment. but maybe you prefer the link to be inside the repo here? |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | ||
|
There was a problem hiding this comment. Instead of "lift and shift", or in addition to this goal, I would include the important goal of app portability across the same protocols. There was a problem hiding this comment. do you have a one-liner that i could just add to that list? |
||
|
|
||
| ## 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. | ||
|
There was a problem hiding this comment. "objectstorage" -> "object storage" There was a problem hiding this comment. You mention POSIX but do you want to also mention that, unlike POSIX and iSCSI, there is no standard defining bucket provisioning? There was a problem hiding this comment. It is implicitly assumed at the beginning of this section. Should we mention this though? |
||
|
|
||
| ## Links | ||
|
|
||
| - [User Guide](user-guide.md) <!-- this should explain all use cases of COSI, and include a section for best pratices --> | ||
|
There was a problem hiding this comment. yeah, @tparikh needs to get working fast to add these docs |
||
| - [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) <!-- cosi protocols as the API between COSI and applications --> | ||
|
|
||
| - [Architecture](architecture.md) <!-- components, object lifecycles, and [sidecar <-> driver] swimlane diagram etc. --> | ||
|
|
||
| - [Internals](internals.md) <!-- implementation details such as finalizers, bucket naming scheme etc. --> | ||
|
|
||
|
|
||
| ## 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) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| --- | ||
|
There was a problem hiding this comment. Replace with There was a problem hiding this comment. I thought doc purely technical. I prefer meeting.md can be merged into the top level readme. |
||
| title: Weekly Community Meetings | ||
| --- | ||
|
There was a problem hiding this comment. Remove this block? I don't think it is needed. |
||
|
|
||
| # Weekly Meetings | ||
| ---------------- | ||
|
There was a problem hiding this comment. Delete this line There was a problem hiding this comment. This is a part of markdown |
||
|
|
||
| ## Engineering meeting | ||
| - Monday at 11:00AM - 11:30AM PT | ||
|
There was a problem hiding this comment. Add link to calendar event similar to community meeting here as well. There was a problem hiding this comment. I dont have a public link for now. We'll have to move forward with this for now |
||
| - [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) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: Definition