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

Document the need for COSI, and Developer guide #22

Merged
merged 1 commit into from
Jan 28, 2021
Merged

Document the need for COSI, and Developer guide #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 50 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,69 @@
COSI repos and images:
![version](https://img.shields.io/badge/status-pre--alpha-lightgrey)

[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) <br/>
&emsp; - [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) <br />
&emsp; - images: cosi-provisioner \
[CSI Adapter](https://github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter) <br />
&emsp; - images: cosi-node-adapter
# Container Object Storage Interface Spec

COSI deprecated repos:
This repository hosts the gRPC API for the Container Object Storage Interface (COSI) standard. The interfaces defined in the [gRPC specification](cosi.proto) are meant to be the common interface for object storage provisioning and management across various object storage vendors.

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

## Why another standard?
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is a dup from another doc. Better to link to a single source here.


[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)
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 block device.
- 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.

# Container Object Storage Specification
## Developer Guide

Kubernetes specific Container Object Storage Interface (COSI) components.
All API definitions **_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-api](https://github.com/kubernetes-sigs/container-object-storage-interface-api)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

COSI spec is a lower level API. I think it should not talk about the higher level API. It is the other way around.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two are closely inter-related. we want to move them in lockstep.i.e. If a change is made here, then it should also be made in api.


### Build and Test

1. `cosi.proto` is generated from the specification defined in `spec.md`

2. In order to update the API, make changes to `spec.md`. Then, generate `cosi.proto` using:

```sh
# generates cosi.proto
make generate
```

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).
3. Clean and Build

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/).
```sh
# cleans up old build files
make clobber
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why make clobber? can make clean do this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this is in addition to make clean as there are some intermediate files that need to be cleaned up while keeping the generated protobuf

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah

# builds the go bindings
make
```

Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
4. Do it all in 1 step:

```
# generates cosi.proto and builds the go bindings
make all
```

## References

- [Documentation](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/index.md)
- [Deployment Guide](https://github.com/kubernetes-sigs/container-object-storage-interface-api/tree/master/docs/deployment-guide.md)
- [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)

## 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

Expand Down