Skip to content
This repository was archived by the owner on Dec 6, 2024. It is now read-only.

Commit 321abab

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #17 from wlan0/master
Document COSI API, resources, and add a simple getting started section
2 parents 1e91ae4 + d80c752 commit 321abab

File tree

3 files changed

+121
-28
lines changed

3 files changed

+121
-28
lines changed

Diff for: ‎README.md

+58-28
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,73 @@
1-
COSI repos and images:
2-
3-
[Spec](https://github.com/kubernetes-sigs/container-object-storage-interface-spec) \
4-
[API](https://github.com/kubernetes-sigs/container-object-storage-interface-api) \
5-
[Controller](https://github.com/kubernetes-sigs/container-object-storage-interface-controller) <br/>
6-
&emsp; - [images: cosi-controller](https://quay.io/repository/containerobjectstorage/objectstorage-controller?tab=tags) \
7-
[Provisioner Sidecar](https://github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar) <br />
8-
&emsp; - images: cosi-provisioner \
9-
[CSI Adapter](https://github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter) <br />
10-
&emsp; - images: cosi-node-adapter
11-
12-
<br />
1+
![version](https://img.shields.io/badge/status-pre--alpha-lightgrey) ![apiVersion](https://img.shields.io/badge/apiVersion-v1alpha1-lightgreen)
2+
3+
4+
# Container Object Storage Interface Spec
5+
6+
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:
7+
8+
- BucketRequest - Represents a request to provision a Bucket
9+
- BucketClass - Represents a class of Buckets with similar characteristics
10+
- Bucket - Represents a Bucket or its equivalent in the storage backend
1311

14-
COSI deprecated repos:
12+
The following CRDs are defined for managing the lifecycle of workloads accessing the Bucket:
13+
14+
- BucketAccessRequest - Represents a request to access a Bucket
15+
- BucketAccessClass - Represents a class of accesors with similar access requirements
16+
- BucketAccess - Represents a access token or service account in the storage backend
1517

16-
[Spec](https://github.com/container-object-storage-interface/spec) \
17-
[API](https://github.com/container-object-storage-interface/api) \
18-
[Manager (i.e. Controller)](https://github.com/container-object-storage-interface/cosi-controller-manager) \
19-
[Provisioner Sidecar](https://github.com/container-object-storage-interface/cosi-provisioner-sidecar) \
20-
[Ephemeral CSI Driver](https://github.com/container-object-storage-interface/ephemeral-csi-driver)
18+
**NOTE**: All of the APIs are defined under the API group `objectstorage.k8s.io`.
2119

20+
For more information about COSI, visit our [documentation](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/index.md).
2221

23-
# Container Object Storage Interface (COSI) API
22+
## Developer Guide
2423

25-
API definitions for Container Object Storage.
24+
All API definitions are in [`apis/objectstorage.k8s.io/`](./apis/objectstorage.k8s.io/). All API changes **_MUST_** satisfy the following requirements:
2625

27-
## Community, discussion, contribution, and support
26+
- Must be backwards compatible
27+
- 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)
28+
29+
### Build and Test
30+
31+
1. Test and Build the project
2832

29-
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)
30-
and the [community page](https://github.com/kubernetes/community/tree/master/sig-storage).
33+
```
34+
make all
35+
```
3136

32-
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/).
37+
2. Generate CRDs
3338

34-
Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
39+
```
40+
make codegen
41+
```
42+
43+
## Adding new fields to protocols
44+
45+
1. Create a new issue raising a RFC for the changes following this format:
46+
47+
Title: [RFC] Changes to protocol xyz
48+
> **Info**:
49+
> 1. Protocol:
50+
> 2. Fields Added:
51+
> 3. Why is this change neccessary?
52+
> ...(describe why here)...
53+
> 4. Which other COSI projects are affected by this change?
54+
> 5. Upgrade plan
55+
> (ignore if it doesn't apply)
56+
57+
## References
58+
59+
- [Documentation](docs/index.md)
60+
- [Deployment Guide](docs/deployment-guide.md)
61+
- [Weekly Meetings](docs/meetings.md)
62+
- [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8)
63+
64+
## Community, discussion, contribution, and support
3565

3666
You can reach the maintainers of this project at:
3767

38-
- [Slack](https://kubernetes.slack.com/messages/sig-storage-cosi)
39-
- [Mailing List](https://groups.google.com/g/container-object-storage-interface-wg?pli=1)
68+
- [#sig-storage-cosi](https://kubernetes.slack.com/messages/sig-storage-cosi) slack channel
69+
- [container-object-storage-interface](https://groups.google.com/g/container-object-storage-interface-wg?pli=1) mailing list
4070

4171
### Code of conduct
4272

43-
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
73+
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).

Diff for: ‎docs/index.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
Container Object Storage Interface (COSI)
2+
------------------------------------------
3+
4+
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.
5+
6+
The goals of this project are:
7+
8+
- Automate object storage provisioning, access and management
9+
- Provide a common layer of abstraction for consuming object storage
10+
- Facilitate lift and shift of workloads across object storage providers (i.e. prevent vendor lock-in)
11+
12+
## Why another standard?
13+
14+
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:
15+
16+
- Unit of provisioned storage - Bucket instead of filesystem mount or blockdevice.
17+
- Access is over the network instead of local POSIX calls.
18+
- No common protocol for consumption across various implementations of object storage.
19+
- Management policies and primitives - for instance, mounting and unmounting do not apply to object storage.
20+
21+
The existing primitives in CSI do not apply to objectstorage. Thus the need for a new standard to automate the management of objectstorage.
22+
23+
## Links
24+
25+
- [User Guide](user-guide.md) <!-- this should explain all use cases of COSI, and include a section for best pratices -->
26+
- [Deployment Guide](deployment-guide.md)
27+
- [How to write a COSI driver](how-to-write-a-cosi-driver.md)
28+
- [How to make your application COSI-compatible](how-to-make-your-application-cosi-compatible.md)
29+
30+
## Advanced
31+
32+
- [Protocols](protocols.md) <!-- cosi protocols as the API between COSI and applications -->
33+
- [Architecture](architecture.md) <!-- components, object lifecycles, and [sidecar <-> driver] swimlane diagram etc. -->
34+
- [Internals](internals.md) <!-- implementation details such as finalizers, bucket naming scheme etc. -->
35+
36+
## Other
37+
38+
- [Project Board](https://github.com/orgs/kubernetes-sigs/projects/8)
39+
- [Weekly Meetings](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/meetings.md)
40+
- [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8)

Diff for: ‎docs/meetings.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Weekly Community Meetings
3+
---
4+
5+
# Weekly Meetings
6+
----------------
7+
8+
## Engineering meeting
9+
- Monday at 11:00AM - 11:30AM PT
10+
- [SIG Storage Zoom Meeting Room](https://zoom.us/s/614261834) (Password is ```77777```)
11+
- [Meeting Recordings](https://www.youtube.com/channel/UCiOeuJ6L4rYNC1jwZFRmC5Q/search?query=object+bucket+standup)
12+
- [Meeting Notes](https://docs.google.com/document/d/1KTh1y9klby64t7btNULtxLWDkRC9SAWE-SZnJeFZqug/edit?usp=sharing)
13+
14+
## Community Meeting
15+
- [Thursday at 10:00AM - 11:00AM PT](https://calendar.google.com/calendar/event?eid=MmM5bzU5bWtjaG41Z2dlcXViaWtmNGxpbmZfMjAyMTAxMjhUMTgwMDAwWiB2dnZvNDhyNmNwcmNjaWkxbHNhdmE2cDJ1Y0Bn&ctz=America/Los_Angeles)
16+
- [SIG Storage Zoom Meeting Room](https://zoom.us/s/614261834) (Password is ```77777```)
17+
- [Meeting Recordings](https://www.youtube.com/channel/UCiOeuJ6L4rYNC1jwZFRmC5Q/search?query=object+bucket+review)
18+
- [Meeting Notes](https://docs.google.com/document/d/1KTh1y9klby64t7btNULtxLWDkRC9SAWE-SZnJeFZqug/edit?usp=sharing)
19+
20+
## Organizers
21+
22+
- Sidhartha Mani (@wlan0)
23+
- Jeff Vance (@jeffvance)

0 commit comments

Comments
 (0)