complete the release-notes
[stor4nfv.git] / tutorials / flexvolume-plugin.md
1 ## Prerequisite ##\r
2 ### ubuntu\r
3 * Version information\r
4 \r
5         ```bash\r
6         root@proxy:~# cat /etc/issue\r
7         Ubuntu 16.04.2 LTS \n \l\r
8         ```\r
9 ### docker\r
10 * Version information\r
11 \r
12         ```bash\r
13         root@proxy:~# docker version\r
14         Client:\r
15          Version:      1.12.6\r
16          API version:  1.24\r
17          Go version:   go1.6.2\r
18          Git commit:   78d1802\r
19          Built:        Tue Jan 31 23:35:14 2017\r
20          OS/Arch:      linux/amd64\r
21         \r
22         Server:\r
23          Version:      1.12.6\r
24          API version:  1.24\r
25          Go version:   go1.6.2\r
26          Git commit:   78d1802\r
27          Built:        Tue Jan 31 23:35:14 2017\r
28          OS/Arch:      linux/amd64\r
29         ```\r
30 \r
31 ### [golang](https://redirector.gvt1.com/edgedl/go/go1.9.2.linux-amd64.tar.gz) \r
32 * Version information\r
33 \r
34         ```bash\r
35         root@proxy:~# go version\r
36         go version go1.9.2 linux/amd64\r
37         ```\r
38 \r
39 * You can install golang by executing commands blow:\r
40 \r
41         ```bash\r
42         wget https://storage.googleapis.com/golang/go1.9.2.linux-amd64.tar.gz\r
43         tar -C /usr/local -xzf go1.9.2.linux-amd64.tar.gz\r
44         export PATH=$PATH:/usr/local/go/bin\r
45         export GOPATH=$HOME/gopath\r
46         ```\r
47 \r
48 ### [kubernetes](https://github.com/kubernetes/kubernetes) local cluster\r
49 * Version information\r
50         ```bash\r
51         root@proxy:~# kubectl version\r
52         Client Version: version.Info{Major:"1", Minor:"9+", GitVersion:"v1.9.0-beta.0-dirty", GitCommit:"a0fb3baa71f1559fd42d1acd9cbdd8a55ab4dfff", GitTreeState:"dirty", BuildDate:"2017-12-13T09:22:09Z", GoVersion:"go1.9.2", Compiler:"gc", Platform:"linux/amd64"}\r
53         Server Version: version.Info{Major:"1", Minor:"9+", GitVersion:"v1.9.0-beta.0-dirty", GitCommit:"a0fb3baa71f1559fd42d1acd9cbdd8a55ab4dfff", GitTreeState:"dirty", BuildDate:"2017-12-13T09:22:09Z", GoVersion:"go1.9.2", Compiler:"gc", Platform:"linux/amd64"}\r
54         ```\r
55 * You can startup the k8s local cluster by executing commands blow:\r
56 \r
57         ```bash\r
58         cd $HOME\r
59         git clone https://github.com/kubernetes/kubernetes.git\r
60         cd $HOME/kubernetes\r
61         git checkout v1.9.0\r
62         make\r
63         echo alias kubectl='$HOME/kubernetes/cluster/kubectl.sh' >> /etc/profile\r
64         RUNTIME_CONFIG=settings.k8s.io/v1alpha1=true AUTHORIZATION_MODE=Node,RBAC hack/local-up-cluster.sh -O\r
65         ```\r
66 **NOTE**:   \r
67 <div> Due to opensds using etcd as the database which is same with kubernetes so you should startup kubernetes firstly.\r
68 </div>\r
69 \r
70 ### [opensds](https://github.com/opensds/opensds) local cluster\r
71 * For testing purposes you can deploy OpenSDS referring the [Local Cluster Installation with LVM](https://github.com/opensds/opensds/wiki/Local-Cluster-Installation-with-LVM) wiki.\r
72 \r
73 ## Testing steps ##\r
74 * Load some ENVs which is setted before.\r
75 \r
76     ```bash\r
77     source /etc/profile\r
78     ```\r
79 * Download nbp source code.\r
80 \r
81     using git clone  \r
82         ```bash\r
83         git clone https://github.com/opensds/nbp.git  $GOPATH/src/github.com/opensds/nbp\r
84         ```\r
85         \r
86         or using go get  \r
87         ```bash\r
88         go get -v  github.com/opensds/nbp/...\r
89         ```  \r
90 \r
91 * Build the FlexVolume.\r
92 \r
93         ```bash\r
94         cd $GOPATH/src/github.com/opensds/nbp/flexvolume\r
95         go build -o opensds ./cmd/flex-plugin/\r
96         ```\r
97         \r
98     FlexVolume plugin binary is on the current directory.  \r
99 \r
100 \r
101 * Copy the OpenSDS FlexVolume binary file to k8s kubelet `volume-plugin-dir`.  \r
102         if you don't specify the `volume-plugin-dir`, you can execute commands blow:\r
103 \r
104         ```bash\r
105         mkdir -p /usr/libexec/kubernetes/kubelet-plugins/volume/exec/opensds.io~opensds/\r
106         cp $GOPATH/src/github.com/opensds/nbp/flexvolume/opensds /usr/libexec/kubernetes/kubelet-plugins/volume/exec/opensds.io~opensds/\r
107         ```  \r
108         \r
109         **NOTE**: \r
110         <div>\r
111         OpenSDS FlexVolume will get the opensds api endpoint from the environment variable `OPENSDS_ENDPOINT`, if you don't specify it, the FlexVolume will use the default vaule: `http://127.0.0.1:50040`. if you want to specify the `OPENSDS_ENDPOINT` executing command `export OPENSDS_ENDPOINT=http://ip:50040` and restart the k8s local cluster.\r
112 </div>\r
113 \r
114 * Build the provisioner docker image.\r
115 \r
116         ```bash\r
117         cd $GOPATH/src/github.com/opensds/nbp/opensds-provisioner\r
118         make container\r
119         ```\r
120 \r
121 * Create service account, role and bind them.\r
122         ```bash\r
123         cd $GOPATH/src/github.com/opensds/nbp/opensds-provisioner/examples\r
124         kubectl create -f serviceaccount.yaml\r
125         kubectl create -f clusterrole.yaml\r
126         kubectl create -f clusterrolebinding.yaml\r
127         ```\r
128 \r
129 * Change the opensds endpoint IP in pod-provisioner.yaml   \r
130 The IP (192.168.56.106) should be replaced with the OpenSDS osdslet actual endpoint IP.\r
131     ```yaml\r
132     kind: Pod\r
133     apiVersion: v1\r
134     metadata:\r
135       name: opensds-provisioner\r
136     spec:\r
137       serviceAccount: opensds-provisioner\r
138       containers:\r
139         - name: opensds-provisioner\r
140           image: opensdsio/opensds-provisioner\r
141           securityContext:\r
142           args:\r
143             - "-endpoint=http://192.168.56.106:50040" # should be replaced\r
144           imagePullPolicy: "IfNotPresent"\r
145     ```\r
146 \r
147 * Create provisioner pod.\r
148         ```bash\r
149         kubectl create -f pod-provisioner.yaml\r
150         ```\r
151         \r
152     Execute `kubectl get pod` to check if the opensds-provisioner is ok.\r
153     ```bash\r
154     root@nbp:~/go/src/github.com/opensds/nbp/opensds-provisioner/examples# kubectl get pod\r
155     NAME                  READY     STATUS    RESTARTS   AGE\r
156     opensds-provisioner   1/1       Running   0          42m\r
157     ```\r
158 * You can use the following cammands to test the OpenSDS FlexVolume and Proversioner functions.\r
159 \r
160     Create storage class.\r
161         ```bash\r
162         kubectl create -f sc.yaml              # Create StorageClass\r
163         ```\r
164         Execute `kubectl get sc` to check if the storage class is ok. \r
165         ```bash\r
166         root@nbp:~/go/src/github.com/opensds/nbp/opensds-provisioner/examples# kubectl get sc\r
167     NAME                 PROVISIONER               AGE\r
168     opensds              opensds/nbp-provisioner   46m\r
169     standard (default)   kubernetes.io/host-path   49m\r
170         ```\r
171         Create PVC.\r
172         ```bash\r
173         kubectl create -f pvc.yaml             # Create PVC\r
174         ```\r
175         Execute `kubectl get pvc` to check if the pvc is ok. \r
176         ```bash\r
177         root@nbp:~/go/src/github.com/opensds/nbp/opensds-provisioner/examples# kubectl get pvc\r
178     NAME          STATUS    VOLUME                                 CAPACITY   ACCESS MODES   STORAGECLASS   AGE\r
179     opensds-pvc   Bound     731da41e-c9ee-4180-8fb3-d1f6c7f65378   1Gi        RWO            opensds        48m\r
180 \r
181         ```\r
182         Create busybox pod.\r
183         \r
184         ```bash\r
185         kubectl create -f pod-application.yaml # Create busybox pod and mount the block storage.\r
186         ```\r
187         Execute `kubectl get pod` to check if the busybox pod is ok. \r
188     ```bash\r
189     root@nbp:~/go/src/github.com/opensds/nbp/opensds-provisioner/examples# kubectl get pod\r
190     NAME                  READY     STATUS    RESTARTS   AGE\r
191     busy-pod              1/1       Running   0          49m\r
192     opensds-provisioner   1/1       Running   0          50m\r
193     ```\r
194         Execute the `findmnt|grep opensds` to confirm whether the volume has been provided.\r
195         If there is some thing that goes wrong, you can check the log files in directory `/var/log/opensds`.\r
196 \r
197 ## Clean up steps ##\r
198 \r
199 ```\r
200 kubectl delete -f pod-application.yaml\r
201 kubectl delete -f pvc.yaml\r
202 kubectl delete -f sc.yaml\r
203 \r
204 kubectl delete -f pod-provisioner.yaml\r
205 kubectl delete -f clusterrolebinding.yaml\r
206 kubectl delete -f clusterrole.yaml\r
207 kubectl delete -f serviceaccount.yaml\r
208 ```\r