From 1fff4e3ac9dcd531bfc55d0e862d4baab06c590f Mon Sep 17 00:00:00 2001 From: Tejas Parikh Date: Tue, 2 Feb 2021 15:49:03 -0500 Subject: [PATCH] cosi deployment doc --- README.md | 24 ++++++------- docs/deployment-guide.md | 75 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 12 deletions(-) create mode 100644 docs/deployment-guide.md diff --git a/README.md b/README.md index 46eff222..e0964b66 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ ![version](https://img.shields.io/badge/status-pre--alpha-lightgrey) ![apiVersion](https://img.shields.io/badge/apiVersion-v1alpha1-lightgreen) -# Container Object Storage Interface Spec +# Container Object Storage Interface API 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: - + + 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 + - BucketAccessClass - Represents a class of accessors 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`. @@ -25,7 +25,7 @@ All API definitions are in [`apis/objectstorage.k8s.io/`](./apis/objectstorage.k - 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 @@ -44,20 +44,20 @@ make codegen 1. Create a new issue raising a RFC for the changes following this format: -Title: [RFC] Changes to protocol xyz +Title: [RFC] Changes to protocol xyz > **Info**: -> 1. Protocol: +> 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 +> 5. Upgrade plan > (ignore if it doesn't apply) ## References - [Documentation](docs/index.md) - - [Deployment Guide](docs/deployment-guide.md) + - [Deployment Guide](docs/deployment-guide.md) - [Weekly Meetings](docs/meetings.md) - [Roadmap](https://github.com/orgs/kubernetes-sigs/projects/8) @@ -65,7 +65,7 @@ Title: [RFC] Changes to protocol xyz You can reach the maintainers of this project at: - - [#sig-storage-cosi](https://kubernetes.slack.com/messages/sig-storage-cosi) slack channel + - [#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 diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md new file mode 100644 index 00000000..1100103c --- /dev/null +++ b/docs/deployment-guide.md @@ -0,0 +1,75 @@ +--- +title: Deploying Container Object Storage Interface (COSI) On Kubernetes +--- +# Deploying Container Object Storage Interface (COSI) On Kubernetes + +This document describes steps for Kubernetes administrators to setup Container Object Storage Interface (COSI) onto a Kubernetes cluster. +## Overview + +Following components that need to be deployed in Kubernetes to setup COSI. + +- CustomResourceDefinitions (CRDs) +- Controller +- Driver +- Sidecar for the driver +- Node Adapter + +### Quick Start + +Execute following commands to setup COSI: + +```sh +# Install CRDs +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-api + +# Install controller +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-controller + +# Sample Provisioner and Sidecar +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar + +# Node Adapter +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter +``` + +### CustomResourceDefinitions + +COSI acts on following custom resource definitions (CRDs): + +- `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 +- `BucketAccessRequest` - Represents a request to access a Bucket +- `BucketAccessClass` - Represents a class of accessors with similar access requirements +- `BucketAccess` - Represents a access token or service account in the storage backend + +All [COSI custom resource definitions](../crds) can be installed using [kustomization file](../kustomization.yaml) and `kubectl` with following command: + +```sh +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-api +``` + +### Controller + +COSI controller can be setup using the [kustomization file](https://github.com/kubernetes-sigs/container-object-storage-interface-controller/blob/master/kustomization.yaml) from the [container-object-storage-interface-controller](https://github.com/kubernetes-sigs/container-object-storage-interface-controller) repository with following command: + +```sh +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-controller +``` + +The controller will be deployed in the `default` namespace. + +### Sample Driver & Sidecar + +Sample Driver & Sidecar can be setup using the [kustomization file](https://github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar/blob/master/kustomization.yaml) from the [container-object-storage-interface-provisioner-sidecar](https://github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar) repository with following command: + +```sh +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-provisioner-sidecar +``` +### Node Adapter + +Node adapter can be setup using the [kustomization file](https://github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter/blob/master/kustomization.yaml) from the [container-object-storage-interface-csi-adapter](https://github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter) repository with following command: + +```sh +kubectl create -k github.com/kubernetes-sigs/container-object-storage-interface-csi-adapter +```