Skip to content

Commit 2198118

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

File tree

8 files changed

+232
-141
lines changed

8 files changed

+232
-141
lines changed

‎README.md

+28-137
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 |
@@ -40,145 +41,35 @@ See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-di
4041

4142
### CreateVolume Parameters
4243

43-
| Parameter | Values | Default | Description |
44-
|--------------------|----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------|
45-
| "type" | pd-ssd OR pd-standard | pd-standard | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks |
46-
| "replication-type" | none OR regional-pd | none | Replication type allows you to choose between standard zonal Persistent Disks or highly available Regional Persistent Disks |
47-
48-
### Future Features
49-
50-
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
44+
| Parameter | Values | Default | Description |
45+
|------------------|---------------------------|---------------|----------------------------------------------------------------------------------------------------|
46+
| type | `pd-ssd` OR `pd-standard` | `pd-standard` | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks |
47+
| replication-type | `none` OR `regional-pd` | `none` | Replication type allows you to choose between Zonal Persistent Disks or Regional Persistent Disks |
5148

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 Beta Features
56+
57+
* Topology
58+
59+
### Kubernetes Alpha Features
60+
61+
* Snapshots
62+
63+
### Future Features
64+
65+
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
66+
67+
## Further Documentation
68+
69+
[Local Development](docs/local-development.md)
70+
71+
### Kubernetes
72+
73+
[User Guides](docs/kubernetes/user-guides)
74+
75+
[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

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
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+
51+
## Regional PD example
52+
This example provisions a regional PD in regional clusters.
53+
54+
1. Create example Regional Storage Class. Choose between:
55+
56+
* Unrestricted zones
57+
```
58+
$ kubectl apply -f ./examples/kubernetes/demo-regional-sc.yaml
59+
```
60+
61+
* Restricted zones
62+
```
63+
$ kubectl apply -f ./examples/kubernetes/demo-regional-restricted-sc.yaml
64+
```
65+
66+
2. Create example PVC and Pod
67+
```
68+
$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml
69+
```
70+
71+
3. Verify PV is created and bound to PVC
72+
```
73+
$ kubectl get pvc
74+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
75+
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
76+
```
77+
78+
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
79+
```
80+
$ kubectl get pods
81+
NAME READY STATUS RESTARTS AGE
82+
web-server 1/1 Running 0 1m
83+
```

‎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

0 commit comments

Comments
 (0)