Skip to content

Commit 5451925

Browse files
msau42msau42
committed
Update examples and documentation
1 parent 191be85 commit 5451925

File tree

9 files changed

+213
-133
lines changed

9 files changed

+213
-133
lines changed

‎README.md

+21-131
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ 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+
Latest stable image: `gcr.io/gke-release/gcp-compute-persistent-disk-csi-driver:v0.3.1-gke.0`
1515

1616
### Test Status
1717

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

2626
### Kubernetes Compatibility
2727

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

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

5450
This driver supports only one topology key:
5551
`topology.gke.io/zone`
5652
that represents availability by zone.
5753

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-
1. Create example Default Snapshot Class
106-
```
107-
$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml
108-
```
109-
2. Create a snapshot of the PVC created in above example
110-
```
111-
$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml
112-
```
113-
3. Verify Snapshot is created and is ready to use
114-
```
115-
$ k get volumesnapshots demo-snapshot-podpvc -o yaml
116-
apiVersion: snapshot.storage.k8s.io/v1alpha1
117-
kind: VolumeSnapshot
118-
metadata:
119-
creationTimestamp: 2018-10-05T16:59:26Z
120-
generation: 1
121-
name: demo-snapshot-podpvc
122-
namespace: default
123-
124-
...
125-
126-
status:
127-
creationTime: 2018-10-05T16:59:27Z
128-
ready: true
129-
restoreSize: 6Gi
130-
131-
```
132-
4. Create a new volume from the snapshot
133-
```
134-
$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml
135-
```
136-
137-
## Kubernetes Development
138-
139-
### Manual
140-
141-
To build and install a development version of the driver:
142-
```
143-
$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to
144-
$ make push-container
145-
146-
# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image
147-
$ GCE_PD_DRIVER_VERSION=dev
148-
$ ./deploy/kubernetes/deploy-driver.sh
149-
```
150-
151-
To bring down driver:
152-
```
153-
$ ./deploy/kubernetes/delete-driver.sh
154-
```
155-
156-
## Testing
157-
158-
Running E2E Tests:
159-
```
160-
$ PROJECT=my-project # GCP Project to run tests in
161-
$ [email protected] # Existing IAM Account with GCE PD CSI Driver Permissions
162-
$ ./test/run-e2e-local.sh
163-
```
164-
165-
Running Sanity Tests:
166-
```
167-
$ ./test/run-sanity.sh
168-
```
169-
170-
Running Unit Tests:
171-
```
172-
$ ./test/run-unit.sh
173-
```
174-
175-
## Dependency Management
176-
177-
Use [dep](https://github.com/golang/dep)
178-
```
179-
$ dep ensure
180-
```
181-
182-
To modify dependencies or versions change `./Gopkg.toml`
54+
### Kubernetes Alpha Features
55+
56+
* Snapshots
57+
* Topology
58+
59+
### Future Features
60+
61+
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
62+
63+
## Further Documentation
64+
65+
[Local Development](docs/local-development.md)
66+
67+
### Kubernetes
68+
69+
[User Guides](docs/kubernetes/user-guides)
70+
71+
[Driver Development](docs/kubernetes/development.md)
72+

‎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

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Kubernetes Basic User Guide
2+
This guide gives a simple example on how to provision PDs in single-zone clusters.
3+
4+
## Install Driver
5+
6+
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
7+
```
8+
$ PROJECT=your-project-here # GCP project
9+
$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
10+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
11+
$ ./deploy/setup-project.sh
12+
```
13+
14+
2. Deploy driver to Kubernetes Cluster
15+
```
16+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
17+
$ GCE_PD_DRIVER_VERSION=stable # Driver version to deploy
18+
$ ./deploy/kubernetes/deploy-driver.sh
19+
```
20+
21+
## Single zone example
22+
23+
1. Create example Zonal Storage Class
24+
```
25+
$ kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
26+
```
27+
28+
2. Create example PVC and Pod
29+
```
30+
$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml
31+
```
32+
33+
3. Verify PV is created and bound to PVC
34+
```
35+
$ kubectl get pvc
36+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
37+
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
38+
```
39+
40+
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
41+
```
42+
$ kubectl get pods
43+
NAME READY STATUS RESTARTS AGE
44+
web-server 1/1 Running 0 1m

‎docs/kubernetes/user-guides/regional-clusters.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Kubernetes Regional Clusters User Guide
2+
This guide documents how to provision PDs in multi-zone/regional clusters.
3+
4+
## TODO: Regional PD
5+
6+
7+
8+
## TODO: Topology-aware dynamic provisioning (alpha)
9+
This feature makes dynamic provisioning of PDs aware of pod scheduling
10+
constraints so that a PD is provisioned in an appropriate zone that can run the
11+
pod.
12+
13+
### Prerequisites
14+
This is only supported with Kubernetes alpha clusters with minimum version
15+
FIXME.
16+
17+
## FIXME: Install Driver with alpha features
18+
19+
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
20+
```
21+
$ PROJECT=your-project-here # GCP project
22+
$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
23+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
24+
$ ./deploy/setup-project.sh
25+
```
26+
27+
2. Deploy driver to Kubernetes Cluster
28+
```
29+
$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
30+
$ GCE_PD_DRIVER_VERSION=alpha # Driver version to deploy
31+
$ ./deploy/kubernetes/deploy-driver.sh
32+
```
33+
34+
### Example
35+
36+
TODO

‎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+
### FIXME: 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=alpha # 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-sc.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
apiVersion: storage.k8s.io/v1beta1
1+
apiVersion: storage.k8s.io/v1
22
kind: StorageClass
33
metadata:
44
name: csi-gce-pd

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
apiVersion: storage.k8s.io/v1beta1
1+
apiVersion: storage.k8s.io/v1
22
kind: StorageClass
33
metadata:
44
name: csi-gce-pd

‎examples/kubernetes/demo-zonal-topology-sc.yaml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
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+
volumeBindingMode: WaitForFirstConsumer

0 commit comments

Comments
 (0)