Skip to content

Commit fa9bc64

Browse files
msau42msau42
committed
Update examples and documentation
1 parent ac5169f commit fa9bc64

File tree

8 files changed

+224
-137
lines changed

8 files changed

+224
-137
lines changed

‎README.md

+21-133
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ lifecycle of Google Compute Engine Persistent Disks.
1111

1212
## Project Status
1313
Status: Beta
14-
Latest stable image: `gcr.io/gke-release/gcp-compute-persistent-disk-csi-driver:v0.3.0-gke.0`
14+
15+
Latest stable image: `gcr.io/gke-release/gcp-compute-persistent-disk-csi-driver:v0.3.1-gke.0`
1516

1617
### Test Status
1718

@@ -25,7 +26,7 @@ This plugin is compatible with CSI versions [v1.0.0](https://github.com/containe
2526

2627
### Kubernetes Compatibility
2728

28-
| GCE PD CSI Driver\Kubernetes Version | 1.10.5 - 1.11 | 1.12 | 1.13+ |
29+
| GCE PD CSI Driver\Kubernetes Version | 1.10.5 - 1.11 | 1.12 | 1.13+ |
2930
|--------------------------------------|---------------|------|-------|
3031
| v0.1.0.alpha | yes | no | no |
3132
| v0.2.0 (alpha) | no | yes | no |
@@ -45,140 +46,27 @@ See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-di
4546
| "type" | pd-ssd OR pd-standard | pd-standard | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks |
4647
| "replication-type" | none OR regional-pd | none | Replication type allows you to choose between standard zonal Persistent Disks or highly available Regional Persistent Disks |
4748

48-
### Future Features
49-
50-
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
51-
5249
### Topology
5350

5451
This driver supports only one topology key:
5552
`topology.gke.io/zone`
5653
that represents availability by zone.
5754

58-
## Kubernetes User Guide
59-
60-
### Install Driver
61-
62-
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
63-
```
64-
$ PROJECT=your-project-here # GCP project
65-
$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
66-
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
67-
$ ./deploy/setup-project.sh
68-
```
69-
70-
2. Deploy driver to Kubernetes Cluster
71-
```
72-
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
73-
$ GCE_PD_DRIVER_VERSION=stable # Driver version to deploy
74-
$ ./deploy/kubernetes/deploy-driver.sh
75-
```
76-
77-
### Zonal Example
78-
79-
1. Create example Zonal Storage Class
80-
```
81-
$ kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
82-
```
83-
84-
2. Create example PVC and Pod
85-
```
86-
$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml
87-
```
88-
89-
3. Verify PV is created and bound to PVC
90-
```
91-
$ kubectl get pvc
92-
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
93-
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
94-
```
95-
96-
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
97-
```
98-
$ kubectl get pods
99-
NAME READY STATUS RESTARTS AGE
100-
web-server 1/1 Running 0 1m
101-
```
102-
103-
### Snapshot Example
104-
105-
Please note that VolumeSnapshot is currently alpha feature. In order to enable this feature, please install CSI driver with
106-
dev version by setting the environment variable "GCE_PD_DRIVER_VERSION=dev"
107-
1. Create example Default Snapshot Class
108-
```
109-
$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml
110-
```
111-
2. Create a snapshot of the PVC created in above example
112-
```
113-
$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml
114-
```
115-
3. Verify Snapshot is created and is ready to use
116-
```
117-
$ k get volumesnapshots demo-snapshot-podpvc -o yaml
118-
apiVersion: snapshot.storage.k8s.io/v1alpha1
119-
kind: VolumeSnapshot
120-
metadata:
121-
creationTimestamp: 2018-10-05T16:59:26Z
122-
generation: 1
123-
name: demo-snapshot-podpvc
124-
namespace: default
125-
126-
...
127-
128-
status:
129-
creationTime: 2018-10-05T16:59:27Z
130-
ready: true
131-
restoreSize: 6Gi
132-
133-
```
134-
4. Create a new volume from the snapshot
135-
```
136-
$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml
137-
```
138-
139-
## Kubernetes Development
140-
141-
### Manual
142-
143-
To build and install a development version of the driver:
144-
```
145-
$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to
146-
$ make push-container
147-
148-
# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image
149-
$ GCE_PD_DRIVER_VERSION=dev
150-
$ ./deploy/kubernetes/deploy-driver.sh
151-
```
152-
153-
To bring down driver:
154-
```
155-
$ ./deploy/kubernetes/delete-driver.sh
156-
```
157-
158-
## Testing
159-
160-
Running E2E Tests:
161-
```
162-
$ PROJECT=my-project # GCP Project to run tests in
163-
$ [email protected] # Existing IAM Account with GCE PD CSI Driver Permissions
164-
$ ./test/run-e2e-local.sh
165-
```
166-
167-
Running Sanity Tests:
168-
```
169-
$ ./test/run-sanity.sh
170-
```
171-
172-
Running Unit Tests:
173-
```
174-
$ ./test/run-unit.sh
175-
```
176-
177-
## Dependency Management
178-
179-
Use [dep](https://github.com/golang/dep)
180-
```
181-
$ dep ensure
182-
```
183-
184-
To modify dependencies or versions change `./Gopkg.toml`
55+
### Kubernetes Alpha Features
56+
57+
* Snapshots
58+
* Topology
59+
60+
### Future Features
61+
62+
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
63+
64+
## Further Documentation
65+
66+
[Local Development](docs/local-development.md)
67+
68+
### Kubernetes
69+
70+
[User Guides](docs/kubernetes/user-guides)
71+
72+
[Driver Development](docs/kubernetes/development.md)

‎docs/kubernetes/development.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Kubernetes Development
2+
3+
## Manual
4+
5+
To build and install a development version of the driver:
6+
```
7+
$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to
8+
$ make push-container
9+
10+
# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image
11+
$ GCE_PD_DRIVER_VERSION=dev
12+
$ ./deploy/kubernetes/deploy-driver.sh
13+
```
14+
15+
To bring down driver:
16+
```
17+
$ ./deploy/kubernetes/delete-driver.sh
18+
```
19+
20+
## TODO Testing
21+

‎docs/kubernetes/user-guides/basic.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Kubernetes Basic User Guide
2+
This guide gives a simple example on how to provision zonal and regional PDs in single-zone and regional clusters.
3+
4+
**Note:** Regional cluster support only available in beta starting with
5+
Kubernetes 1.14.
6+
7+
## Install Driver
8+
9+
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
10+
```
11+
$ PROJECT=your-project-here # GCP project
12+
$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
13+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
14+
$ ./deploy/setup-project.sh
15+
```
16+
17+
2. Deploy driver to Kubernetes Cluster
18+
```
19+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
20+
$ GCE_PD_DRIVER_VERSION=stable # Driver version to deploy
21+
$ ./deploy/kubernetes/deploy-driver.sh
22+
```
23+
24+
## Zonal PD example
25+
This example provisions a zonal PD in both single-zone and regional clusters.
26+
27+
1. Create example Zonal Storage Class
28+
```
29+
$ kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
30+
```
31+
32+
2. Create example PVC and Pod
33+
```
34+
$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml
35+
```
36+
37+
3. Verify PV is created and bound to PVC
38+
```
39+
$ kubectl get pvc
40+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
41+
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
42+
```
43+
44+
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
45+
```
46+
$ kubectl get pods
47+
NAME READY STATUS RESTARTS AGE
48+
web-server 1/1 Running 0 1m
49+
50+
## Regional PD example
51+
This example provisions a regional PD in regional clusters.
52+
53+
1. Create example Regional Storage Class. Choose between:
54+
55+
* Unrestricted zones
56+
```
57+
$ kubectl apply -f ./examples/kubernetes/demo-regional-sc.yaml
58+
```
59+
60+
* Restricted zones
61+
```
62+
$ kubectl apply -f ./examples/kubernetes/demo-regional-restricted-sc.yaml
63+
```
64+
65+
2. Create example PVC and Pod
66+
```
67+
$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml
68+
```
69+
70+
3. Verify PV is created and bound to PVC
71+
```
72+
$ kubectl get pvc
73+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
74+
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
75+
```
76+
77+
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
78+
```
79+
$ kubectl get pods
80+
NAME READY STATUS RESTARTS AGE
81+
web-server 1/1 Running 0 1m
82+
```

‎docs/kubernetes/user-guides/snapshots.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Kubernetes Snapshots User Guide (Alpha)
2+
3+
### Install Driver with alpha snapshot feature
4+
5+
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
6+
```
7+
$ PROJECT=your-project-here # GCP project
8+
$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
9+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
10+
$ ./deploy/setup-project.sh
11+
```
12+
13+
2. Deploy driver to Kubernetes Cluster
14+
```
15+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
16+
$ GCE_PD_DRIVER_VERSION=dev # Driver version to deploy
17+
$ ./deploy/kubernetes/deploy-driver.sh
18+
```
19+
20+
### Snapshot Example
21+
22+
1. Create example Default Snapshot Class
23+
```
24+
$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml
25+
```
26+
2. Create a snapshot of the PVC created in above example
27+
```
28+
$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml
29+
```
30+
3. Verify Snapshot is created and is ready to use
31+
```
32+
$ k get volumesnapshots demo-snapshot-podpvc -o yaml
33+
apiVersion: snapshot.storage.k8s.io/v1alpha1
34+
kind: VolumeSnapshot
35+
metadata:
36+
creationTimestamp: 2018-10-05T16:59:26Z
37+
generation: 1
38+
name: demo-snapshot-podpvc
39+
namespace: default
40+
41+
...
42+
43+
status:
44+
creationTime: 2018-10-05T16:59:27Z
45+
ready: true
46+
restoreSize: 6Gi
47+
48+
```
49+
4. Create a new volume from the snapshot
50+
```
51+
$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml

‎docs/local-development.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Local development
2+
This page contains information on how to develop and test the driver locally.
3+
4+
## Testing
5+
6+
Running E2E Tests:
7+
```
8+
$ PROJECT=my-project # GCP Project to run tests in
9+
$ [email protected] # Existing IAM Account with GCE PD CSI Driver Permissions
10+
$ ./test/run-e2e-local.sh
11+
```
12+
13+
Running Sanity Tests:
14+
```
15+
$ ./test/run-sanity.sh
16+
```
17+
18+
Running Unit Tests:
19+
```
20+
$ ./test/run-unit.sh
21+
```
22+
23+
## Dependency Management
24+
25+
Use [dep](https://github.com/golang/dep)
26+
```
27+
$ dep ensure
28+
```
29+
30+
To modify dependencies or versions change `./Gopkg.toml`

‎examples/kubernetes/demo-regional-restricted-sc.yaml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
apiVersion: storage.k8s.io/v1
2+
kind: StorageClass
3+
metadata:
4+
name: csi-gce-pd
5+
provisioner: pd.csi.storage.gke.io
6+
parameters:
7+
type: pd-standard
8+
replication-type: regional-pd
9+
volumeBindingMode: WaitForFirstConsumer
10+
allowedTopologies:
11+
- matchLabelExpressions:
12+
- key: topology.gke.io/zone
13+
values:
14+
- us-central1-a
15+
- us-central1-b

‎examples/kubernetes/demo-regional-sc.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
apiVersion: storage.k8s.io/v1beta1
1+
apiVersion: storage.k8s.io/v1
22
kind: StorageClass
33
metadata:
44
name: csi-gce-pd
55
provisioner: pd.csi.storage.gke.io
66
parameters:
77
type: pd-standard
88
replication-type: regional-pd
9-
volumeBindingMode: Immediate
9+
volumeBindingMode: WaitForFirstConsumer

0 commit comments

Comments
 (0)