Merge pull request #299 from xiangrumei/master

modify opensds docs
sodafoundation · Mar 9, 2018 · a193a1a · a193a1a
2 parents dab4c09 + c8c1c8d
commit a193a1a
Show file tree

Hide file tree

Showing 16 changed files with 1,445 additions and 19 deletions.
diff --git a/docs/readthedocs/community/euac.md b/docs/readthedocs/community/euac.md
@@ -0,0 +1,11 @@
+# EUAC
+OpenSDS End-User Advisory Committee
+
+## Mission
+To assist and support the OpenSDS community in its objectives by providing technical and strategic guidance real-world storage challenges.
+
+## Members
+* Cosimo Rossetti (Vodafone)
+* Yusuke Sato (Yahoo Japan)
+* Kei Kusunoki (NTT Communications)
+* Yuji Yazawa (Toyota ITC)
diff --git a/docs/readthedocs/tsc.md → docs/readthedocs/community/tsc.md b/docs/readthedocs/tsc.md → docs/readthedocs/community/tsc.md
@@ -1,8 +1,8 @@
 # TSC
-OpenSDS Technical Steering Commitee
+OpenSDS Technical Steering Committee
 
 ## Mission
-To provide technical guidance for OpenSDS community development.
+The primary decision makeing forum for OpenSDS projects and servers to set the overall technical direction and strategy for OpenSDS.
 
 ## Members
 * Anjaneya Chagam (Intel)

diff --git a/docs/readthedocs/contributing/Community-Contributing.md b/docs/readthedocs/contributing/Community-Contributing.md
@@ -0,0 +1,57 @@
+# OpenSDS
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/opensds/opensds?branch=master)](https://goreportcard.com/report/github.com/opensds/opensds)
+[![Build Status](https://travis-ci.org/opensds/opensds.svg?branch=master)](https://travis-ci.org/opensds/opensds)
+[![Coverage Status](https://coveralls.io/repos/github/opensds/opensds/badge.svg?branch=master)](https://coveralls.io/github/opensds/opensds?branch=master)
+
+<img src="https://www.opensds.io/wp-content/uploads/sites/18/2016/11/logo_opensds.png" width="100">
+
+## How to contribute
+
+opensds is Apache 2.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on commit message formatting, contact points for developers and other resources to make getting your contribution into opensds easier.
+
+## Email and chat
+
+- Email: [opensds-dev](https://groups.google.com/forum/?hl=en#!forum/opensds-dev)
+- Slack: #[opensds](https://opensds.slack.com) 
+
+Before you start, NOTICE that ```master``` branch is the relatively stable version
+provided for customers and users. So all code modifications SHOULD be submitted to
+```development``` branch.
+
+## Getting started
+
+- Fork the repository on GitHub.
+- Read the README.md and INSTALL.md for project information and build instructions.
+
+For those who just get in touch with this project recently, here is a proposed contributing [tutorial](https://github.com/opensds/opensds/wiki/OpenSDS-Controller-Project-Contribution-Tutorial).
+
+## Contribution Workflow
+
+### Code style
+
+The coding style suggested by the Golang community is used in opensds. See the [doc](https://github.com/golang/go/wiki/CodeReviewComments) for more details.
+
+Please follow this style to make opensds easy to review, maintain and develop.
+
+### Report issues
+
+A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and will thank you for it!
+
+When reporting issues, refer to this format:
+
+- What version of env (opensds, os, golang etc) are you using?
+- Is this a BUG REPORT or FEATURE REQUEST?
+- What happened?
+- What you expected to happen?
+- How to reproduce it?(as minimally and precisely as possible)
+
+### Propose blueprints
+
+- Raise your idea as an [issues](https://github.com/opensds/opensds/issues)
+- After reaching consensus in the issue discussion, complete the development on the forked repo and submit a PR. 
+  Here are the [PRs](https://github.com/opensds/opensds/pulls?q=is%3Apr+is%3Aclosed) that are already closed.
+- If a PR is submitted by one of the core members, it has to be merged by a different core member.
+- After PR is sufficiently discussed, it will get merged, abondoned or rejected depending on the outcome of the discussion.
+
+Thank you for your contribution !
diff --git a/docs/readthedocs/contributing/Tutorials-for-Beginners.md b/docs/readthedocs/contributing/Tutorials-for-Beginners.md
@@ -0,0 +1,50 @@
+If you are a beginner and expect opensds project as the gate to open source world, this tutorial is one of the best
+choices for you. Just follow the guidance and you will find the pleasure to becoming a contributor.
+
+## Step 1: Fork opensds repository
+
+Before making modifications of opensds project, you need to make sure that this project have been forked to your own
+repository. It means that there will be parallel development between opensds repo and your own repo, so be careful
+to avoid the inconsistency between these two repos.
+
+## Step 2: Clone the remote repository
+
+If you want to download the code to the local machine, ```git``` is the best way:
+```
+git clone https://your_repo_url/opensds.git
+```
+
+## Step 3: Configure upstream repository
+
+To reduce the conflicts between your remote repo and opensds repo, we SUGGEST you configure opensds as the upstream repo:
+```
+git remote add upstream https://github.com/opensds/opensds.git
+git fetch upstream
+```
+
+## Step 4: Develop code locally
+
+To avoid inconsistency between multiple branches, we SUGGEST checking out to a new branch:
+```
+git checkout -b new_branch_name upstream/devlopment
+git pull
+```
+Then you can change the code arbitrarily.
+
+## Step 5: Push the code to the remote repository
+
+After updating the code, you should push the update in the formal way:
+```
+git add .
+git status (Check the update status)
+git commit -m "Your commit title"
+git commit --amend (Add the concrete description of your commit)
+git push origin new_branch_name
+```
+
+## Step 6: Pull a request to opensds repository
+
+In the last step, your need to pull a compare request between your new branch and opensds development branch. After
+finishing the pull request, the travis CI will be automatically set up for building test.
+
+The tutorial is done, enjoy your contributing work!
diff --git a/docs/readthedocs/index.rst b/docs/readthedocs/index.rst
@@ -13,30 +13,42 @@ Welcome to OpenSDS's documentation!
 OpenSDS is a software defined storage controller that provides unified block, file, object storage services. Mainly includes two projects of OpenSDS and NBP.
 
 
-
 .. toctree::
    :maxdepth: 3
-   :caption: OpenSDS
+   :caption: Community
 
-   opensds   
+   community/euac.md
+   community/tsc.md
 
 .. toctree::
    :maxdepth: 3
-   :caption: NBP
+   :caption: Introduction
+
+   introduction/opensds
+   introduction/nbp
+   introduction/design-specs
 
-   nbp   
+
 
 .. toctree::
    :maxdepth: 3
-   :caption: Design-specs
+   :caption: Installation
 
-   design-specs
+   installation/How-to-Run-Containerized-OpenSDS-for-Testing-Work
+   installation/Local-Cluster-Installation-through-Ansible
+   installation/Local-Cluster-Installation-with-Ceph
+   installation/Local-Cluster-Installation-with-Cinder-Standalone
+   installation/Local-Cluster-Installation-with-LVM
+   installation/OpenSDS-Integration-with-Kubernetes-CSI
+   installation/OpenSDS-Integration-with-Kubernetes-Flexvolume
+   installation/OpenSDS-Integration-with-Kubernetes-Service-Catalog
 
 .. toctree::
    :maxdepth: 3
-   :caption: tsc
+   :caption: Contributing
 
-   tsc
+   contributing/Tutorials-for-Beginners
+   contributing/Community-Contributing
 
 
 

diff --git a/docs/readthedocs/installation/How-to-Run-Containerized-OpenSDS-for-Testing-Work.md b/docs/readthedocs/installation/How-to-Run-Containerized-OpenSDS-for-Testing-Work.md
@@ -0,0 +1,127 @@
+## Pre-configuration
+Before you start, some configurations are required:
+```shell
+export BackendType="sample" # 'sample' is the default option, currently also support 'lvm'
+
+mkdir -p /etc/opensds && sudo cat > /etc/opensds/opensds.conf <<OPENSDS_GLOABL_CONFIG_DOC
+[osdslet]
+api_endpoint = 0.0.0.0:50040
+graceful = True
+log_file = /var/log/opensds/osdslet.log
+socket_order = inc
+
+[osdsdock]
+api_endpoint = 0.0.0.0:50050
+log_file = /var/log/opensds/osdsdock.log
+# Enabled backend types, such as 'sample', 'lvm', 'ceph', 'cinder', etc.
+enabled_backends = ${BackendType}
+
+[sample]
+name = sample
+description = Sample backend for testing
+driver_name = default
+
+[ceph]
+name = ceph
+description = Ceph Test
+driver_name = ceph
+config_path = /etc/opensds/driver/ceph.yaml
+
+[cinder]
+name = cinder
+description = Cinder Test
+driver_name = cinder
+config_path = /etc/opensds/driver/cinder.yaml
+
+[lvm]
+name = lvm
+description = LVM Test
+driver_name = lvm
+config_path = /etc/opensds/driver/lvm.yaml
+
+[database]
+# Enabled database types, such as etcd, mysql, fake, etc.
+driver = etcd
+endpoint = 127.0.0.1:2379,127.0.0.1:2380
+OPENSDS_GLOABL_CONFIG_DOC
+```
+If you choose `lvm` as backend, you need to make sure physical volume and volume group existed. Besides, you need to configure lvm driver.
+```
+sudo pvdisplay # Check if physical volume existed
+sudo vgdisplay # Check if volume group existed
+
+mkdir -p /etc/opensds/driver && sudo cat > /etc/opensds/driver/lvm.yaml <<OPENSDS_DRIVER_CONFIG_DOC
+tgtBindIp: 0.0.0.0
+pool:
+  "vg001":
+    diskType: SSD
+    AZ: default
+OPENSDS_DRIVER_CONFIG_DOC
+```
+
+## OpenSDS Service Installation
+If you are a lazy one, just like me, you probably want to do this:(`docker-compose` required)
+```
+wget https://raw.githubusercontent.com/opensds/opensds/master/docker-compose.yml
+
+docker-compose up
+```
+
+Or you can do this:
+```
+docker run -d --net=host -v /usr/share/ca-certificates/:/etc/ssl/certs quay.io/coreos/etcd:latest
+
+docker run -d --net=host -v /etc/opensds:/etc/opensds opensdsio/opensds-controller:latest
+
+docker run -d --net=host --privileged=true -v /etc/opensds:/etc/opensds opensdsio/opensds-dock:latest
+```
+
+If you are a smart guy, you probably need to configure your service ip and database endpoint:
+```
+export HostIP="your_real_ip"
+docker run -d --net=host -v /usr/share/ca-certificates/:/etc/ssl/certs quay.io/coreos/etcd:latest \
+ -name etcd0 \
+ -advertise-client-urls http://${HostIP}:2379,http://${HostIP}:4001 \
+ -listen-client-urls http://0.0.0.0:2379,http://0.0.0.0:4001 \
+ -initial-advertise-peer-urls http://${HostIP}:2380 \
+ -listen-peer-urls http://0.0.0.0:2380 \
+ -initial-cluster-token etcd-cluster-1 \
+ -initial-cluster etcd0=http://${HostIP}:2380 \
+ -initial-cluster-state new
+
+docker run -d --net=host -v /etc/opensds:/etc/opensds opensdsio/opensds-controller:latest /usr/bin/osdslet --api-endpoint=0.0.0.0:50040 --db-endpoint=${HostIP}:2379,${HostIP}:2380
+
+docker run -d --net=host --privileged=true -v /etc/opensds:/etc/opensds opensdsio/opensds-dock:latest /usr/bin/osdsdock --api-endpoint=0.0.0.0:50050 --db-endpoint=${HostIP}:2379,${HostIP}:2380
+```
+
+## Test
+
+### Download cli tool.
+```
+curl -sSL https://raw.githubusercontent.com/opensds/opensds/master/osdsctl/bin/osdsctl | mv osdsctl /usr/local/bin/
+
+export OPENSDS_ENDPOINT=http://127.0.0.1:50040
+osdsctl pool list
+```
+
+### Create a default profile firstly.
+```
+osdsctl profile create '{"name": "default", "description": "default policy"}'
+```
+
+### Create a volume.
+```
+osdsctl volume create 1 --name=test-001
+```
+
+### List all volumes.
+```
+osdsctl volume list
+```
+
+### Delete the volume.
+```
+osdsctl volume delete <your_volume_id>
+```
+
+After this is done, just enjoy it!