Skip to content

Commit 432526c

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #86 from davidz627/fix/docs
Revised documentation. Made versioning more clear. Made distinction between installation and examples more clear.
2 parents bd240a4 + af606d6 commit 432526c

19 files changed

+364
-52
lines changed

Diff for: ‎OWNERS

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@ reviewers:
66
- jingxu97
77
approvers:
88
- davidz627
9-
- saad-ali
9+
- saad-ali
10+
- msau42

Diff for: ‎README.md

+90-16
Original file line numberDiff line numberDiff line change
@@ -15,41 +15,115 @@ The GCP Compute Persistent Disk CSI Driver is a
1515
Specification compliant driver used by Container Orchestrators to manage the
1616
lifecycle of Google Compute Engine Persistent Disks.
1717

18-
## Installing
19-
### Kubernetes
20-
Templates and further information for installing this driver on Kubernetes are
21-
in [`./deploy/kubernetes/README.md`](deployREADME)
18+
## Project Status
19+
Status: Alpha
20+
Latest image: `gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha`
2221

23-
## Development
22+
### CSI Compatibility
23+
This plugin is compatible with CSI versions v0.2.0 and v0.3.0
2424

25-
###Manual
25+
### Kubernetes Compatibility
26+
This plugin can be used as-is beginning with Kubernetes v1.10.5
2627

27-
Setup [GCP service account first](deployREADME) (one time step)
28+
### Known Issues
29+
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
2830

29-
To bring up developed drivers:
31+
## Plugin Features
32+
### CreateVolume Parameters
33+
| Parameter | Values | Default | Description |
34+
|--------------------|----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------|
35+
| "type" | pd-ssd | pd-standard | pd-standard | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks |
36+
| "replication-type" | none | regional-pd | none | Replication type allows you to choose between standard zonal Persistent Disks or highly available Regional Persistent Disks |
37+
38+
### Future Features
39+
See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
40+
41+
### Topology
42+
This driver supports only one topology key:
43+
`com.google.topology/zone`
44+
that represents availability by zone.
45+
46+
## Kubernetes User Guide
47+
### Install Driver
48+
1. [One-time per project] Create GCP service account for the CSI driver and set required roles
49+
```
50+
PROJECT=your-project-here # GCP project
51+
GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create
52+
GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key
53+
./deploy/setup-project.sh
54+
```
55+
56+
2. Deploy driver to Kubernetes Cluster
57+
```
58+
GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key
59+
GCE_PD_DRIVER_VERSION=stable # Driver version to deploy
60+
./deploy/kubernetes/deploy-driver.sh
61+
```
62+
63+
### Zonal Example
64+
1. Create example Zonal Storage Class
65+
```
66+
kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
67+
```
68+
69+
2. Create example PVC and Pod
70+
```
71+
kubectl apply -f ./examples/kubernetes/demo-pod.yaml
72+
```
73+
74+
3. Verify PV is created and bound to PVC
75+
```
76+
$ kubectl get pvc
77+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
78+
podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s
3079
```
80+
81+
4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
82+
```
83+
NAME READY STATUS RESTARTS AGE
84+
web-server 1/1 Running 0 1m
85+
```
86+
87+
## Kubernetes Development
88+
89+
### Manual
90+
To build and install a development version of the driver:
91+
```
92+
$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to
3193
$ make push-container
94+
95+
# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image
96+
GCE_PD_DRIVER_VERSION=dev
3297
$ ./deploy/kubernetes/deploy-driver.sh
3398
```
3499

35-
To bring down drivers:
100+
To bring down driver:
36101
```
37102
$ ./deploy/kubernetes/delete-driver.sh
38103
```
39104

40105
## Testing
41-
Unit tests in `_test` files in the same package as the functions tested.
106+
Running E2E Tests:
107+
```
108+
PROJECT=my-project # GCP Project to run tests in
109+
[email protected] # Existing IAM Account with GCE PD CSI Driver Permissions
110+
./test/run-e2e-local.sh
111+
```
42112

43-
Sanity and E2E tests can be found in `./test/` and more detailed testing
44-
information is in [`./test/README.md`](testREADME)
113+
Running Sanity Tests:
114+
```
115+
./test/run-sanity.sh
116+
```
117+
118+
Running Unit Tests:
119+
```
120+
./test/run-unit.sh
121+
```
45122

46123
## Dependency Management
47124
Use [dep](https://github.com/golang/dep)
48125
```
49126
$ dep ensure
50127
```
51128

52-
To modify dependencies or versions change `./Gopkg.toml`
53-
54-
[deployREADME]: deploy/kubernetes/README.md
55-
[testREADME]: test/README.md
129+
To modify dependencies or versions change `./Gopkg.toml`

Diff for: ‎deploy/common.sh

+15-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1+
#!/bin/bash
2+
3+
# Common functions
4+
5+
function ensure_var(){
6+
if [[ -v "${1}" ]];
7+
then
8+
echo "${1} is ${!1}"
9+
else
10+
echo "${1} is unset"
11+
exit 1
12+
fi
13+
}
14+
115
function get_needed_roles()
216
{
317
echo "roles/compute.storageAdmin roles/iam.serviceAccountUser projects/${PROJECT}/roles/gcp_compute_persistent_disk_csi_driver_custom_role"
4-
}
18+
}

Diff for: ‎deploy/kubernetes/README.md

-18
This file was deleted.

Diff for: ‎deploy/kubernetes/delete-driver.sh

+8-3
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,21 @@
22

33
# This script will remove the GCP Compute Persistent Disk CSI Driver from the
44
# currently available Kubernetes cluster
5+
#
6+
# Args:
7+
# GCE_PD_DRIVER_VERSION: The version of the GCE PD CSI Driver to deploy. Can be one of {v0.1.0, latest}
58

69
set -o nounset
710
set -o errexit
811

912
readonly PKGDIR="${GOPATH}/src/sigs.k8s.io/gcp-compute-persistent-disk-csi-driver"
10-
readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes"
13+
source "${PKGDIR}/deploy/common.sh"
14+
15+
ensure_var GCE_PD_DRIVER_VERSION
16+
17+
readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes/${GCE_PD_DRIVER_VERSION}"
1118

1219
kubectl delete -f "${KUBEDEPLOY}/node.yaml" --ignore-not-found
1320
kubectl delete -f "${KUBEDEPLOY}/controller.yaml" --ignore-not-found
14-
kubectl delete -f "${KUBEDEPLOY}/zonal-sc.yaml" --ignore-not-found
15-
kubectl delete -f "${KUBEDEPLOY}/regional-sc.yaml" --ignore-not-found
1621
kubectl delete -f "${KUBEDEPLOY}/setup-cluster.yaml" --ignore-not-found
1722
kubectl delete secret cloud-sa --ignore-not-found

Diff for: ‎deploy/kubernetes/deploy-driver.sh

+6-3
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,18 @@
99

1010
# Args:
1111
# GCE_PD_SA_DIR: Directory the service account key has been saved in (generated by setup-project.sh)
12+
# GCE_PD_DRIVER_VERSION: The version of the GCE PD CSI Driver to deploy. Can be one of {stable, dev}
1213

1314
set -o nounset
1415
set -o errexit
1516

1617
readonly PKGDIR="${GOPATH}/src/sigs.k8s.io/gcp-compute-persistent-disk-csi-driver"
17-
readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes"
18+
source "${PKGDIR}/deploy/common.sh"
1819

19-
. $(dirname $0)/../common.sh
20+
ensure_var GCE_PD_SA_DIR
21+
ensure_var GCE_PD_DRIVER_VERSION
22+
23+
readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes/${GCE_PD_DRIVER_VERSION}"
2024

2125
function check_service_account()
2226
{
@@ -57,6 +61,5 @@ then
5761
fi
5862

5963
kubectl apply -f "${KUBEDEPLOY}/setup-cluster.yaml"
60-
kubectl apply -f "${KUBEDEPLOY}/zonal-sc.yaml"
6164
kubectl apply -f "${KUBEDEPLOY}/node.yaml"
6265
kubectl apply -f "${KUBEDEPLOY}/controller.yaml"

Diff for: ‎deploy/kubernetes/dev/WARNING.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
WARNING: DO NOT USE THE STAGING-LATEST VERSION OF THE DRIVER FOR PRODUCTION
2+
DISCLAIMER: THE LATEST IMAGE IS CONSTANTLY CHANGING WITH DEVELOPMENT AND CAN BE
3+
BROKEN AT ANY TIME
4+
5+
This is the absolute cutting edge development Driver, it is intended for testing
6+
and development only and can have vast differences in
7+
functionality/behavior/configuration. Use only to try the newest features that
8+
are not guaranteed to work yet.
9+
10+
APPROXIMATE CHANGELOG in latest:
11+
* Topology
12+
* RePD
13+
* Volume ID Format Changed
14+
* Node ID Format Changed
15+
* Parameter "zone" Removed

Diff for: ‎deploy/kubernetes/controller.yaml renamed to ‎deploy/kubernetes/dev/controller.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ spec:
4242
mountPath: /csi
4343
- name: gce-pd-driver
4444
imagePullPolicy: Always
45-
image: gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha
45+
image: gcr.io/dyzz-csi-staging/csi/gce-pd-driver:latest
4646
args:
4747
- "--v=5"
4848
- "--endpoint=$(CSI_ENDPOINT)"
@@ -62,4 +62,4 @@ spec:
6262
emptyDir: {}
6363
- name: cloud-sa-volume
6464
secret:
65-
secretName: cloud-sa
65+
secretName: cloud-sa

Diff for: ‎deploy/kubernetes/node.yaml renamed to ‎deploy/kubernetes/dev/node.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ spec:
3636
securityContext:
3737
privileged: true
3838
imagePullPolicy: Always
39-
image: gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha
39+
image: gcr.io/dyzz-csi-staging/csi/gce-pd-driver:latest
4040
args:
4141
- "--v=5"
4242
- "--endpoint=$(CSI_ENDPOINT)"
@@ -68,4 +68,4 @@ spec:
6868
- name: device-dir
6969
hostPath:
7070
path: /dev
71-
type: Directory
71+
type: Directory

Diff for: ‎deploy/kubernetes/setup-cluster.yaml renamed to ‎deploy/kubernetes/dev/setup-cluster.yaml

File renamed without changes.

Diff for: ‎deploy/kubernetes/stable/controller.yaml

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
kind: StatefulSet
2+
apiVersion: apps/v1beta1
3+
metadata:
4+
name: csi-gce-pd-controller
5+
spec:
6+
serviceName: "csi-gce-pd"
7+
replicas: 1
8+
selector:
9+
matchLabels:
10+
app: csi-gce-pd-driver
11+
template:
12+
metadata:
13+
labels:
14+
app: csi-gce-pd-driver
15+
spec:
16+
serviceAccount: csi-controller-sa
17+
containers:
18+
- name: csi-provisioner
19+
imagePullPolicy: Always
20+
image: quay.io/k8scsi/csi-provisioner:v0.2.0
21+
args:
22+
- "--v=5"
23+
- "--provisioner=csi-gce-pd"
24+
- "--csi-address=$(ADDRESS)"
25+
env:
26+
- name: ADDRESS
27+
value: /csi/csi.sock
28+
volumeMounts:
29+
- name: socket-dir
30+
mountPath: /csi
31+
- name: csi-attacher
32+
imagePullPolicy: Always
33+
image: quay.io/k8scsi/csi-attacher:v0.2.0
34+
args:
35+
- "--v=5"
36+
- "--csi-address=$(ADDRESS)"
37+
env:
38+
- name: ADDRESS
39+
value: /csi/csi.sock
40+
volumeMounts:
41+
- name: socket-dir
42+
mountPath: /csi
43+
- name: gce-pd-driver
44+
imagePullPolicy: Always
45+
image: gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha
46+
args:
47+
- "--v=5"
48+
- "--endpoint=$(CSI_ENDPOINT)"
49+
- "--nodeid=$(KUBE_NODE_NAME)"
50+
env:
51+
- name: CSI_ENDPOINT
52+
value: unix:/csi/csi.sock
53+
- name: KUBE_NODE_NAME
54+
valueFrom:
55+
fieldRef:
56+
fieldPath: spec.nodeName
57+
- name: GOOGLE_APPLICATION_CREDENTIALS
58+
value: "/etc/cloud-sa/cloud-sa.json"
59+
volumeMounts:
60+
- name: socket-dir
61+
mountPath: /csi
62+
- name: cloud-sa-volume
63+
readOnly: true
64+
mountPath: "/etc/cloud-sa"
65+
volumes:
66+
- name: socket-dir
67+
emptyDir: {}
68+
- name: cloud-sa-volume
69+
secret:
70+
secretName: cloud-sa

0 commit comments

Comments
 (0)