Skip to content

Commit 11cb039

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #214 from msau42/update-docs
Update examples and documentation
2 parents 50c6aa6 + ff59f6f commit 11cb039

File tree

8 files changed

+234
-139
lines changed

8 files changed

+234
-139
lines changed

‎README.md

+26-135
Original file line numberDiff line numberDiff line change
@@ -41,145 +41,36 @@ See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-di
4141

4242
### CreateVolume Parameters
4343

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 standard zonal Persistent Disks or highly available Regional Persistent Disks |
48-
49-
### Future Features
50-
51-
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 |
5248

5349
### Topology
5450

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

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

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

‎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=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-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)