diff --git a/README.md b/README.md index 2d6230e49..1bcf18550 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,10 @@ See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-di ### CreateVolume Parameters -| Parameter | Values | Default | Description | -|--------------------|----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------| -| "type" | pd-ssd OR pd-standard | pd-standard | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks | -| "replication-type" | none OR regional-pd | none | Replication type allows you to choose between standard zonal Persistent Disks or highly available Regional Persistent Disks | - -### Future Features - -See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues) +| Parameter | Values | Default | Description | +|------------------|---------------------------|---------------|----------------------------------------------------------------------------------------------------| +| type | `pd-ssd` OR `pd-standard` | `pd-standard` | Type allows you to choose between standard Persistent Disks or Solid State Drive Persistent Disks | +| replication-type | `none` OR `regional-pd` | `none` | Replication type allows you to choose between Zonal Persistent Disks or Regional Persistent Disks | ### Topology @@ -56,130 +52,25 @@ This driver supports only one topology key: `topology.gke.io/zone` that represents availability by zone. -## Kubernetes User Guide - -### Install Driver - -1. [One-time per project] Create GCP service account for the CSI driver and set required roles -``` -$ PROJECT=your-project-here # GCP project -$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create -$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key -$ ./deploy/setup-project.sh -``` - -2. Deploy driver to Kubernetes Cluster -``` -$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key -$ GCE_PD_DRIVER_VERSION=stable # Driver version to deploy -$ ./deploy/kubernetes/deploy-driver.sh -``` - -### Zonal Example - -1. Create example Zonal Storage Class -``` -$ kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml -``` - -2. Create example PVC and Pod -``` -$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml -``` - -3. Verify PV is created and bound to PVC -``` -$ kubectl get pvc -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s -``` - -4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state) -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -web-server 1/1 Running 0 1m -``` - -### Snapshot Example - -Please note that VolumeSnapshot is currently alpha feature. In order to enable this feature, please install CSI driver with -dev version by setting the environment variable "GCE_PD_DRIVER_VERSION=dev" -1. Create example Default Snapshot Class -``` -$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml -``` -2. Create a snapshot of the PVC created in above example -``` -$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml -``` -3. Verify Snapshot is created and is ready to use -``` -$ k get volumesnapshots demo-snapshot-podpvc -o yaml -apiVersion: snapshot.storage.k8s.io/v1alpha1 -kind: VolumeSnapshot -metadata: - creationTimestamp: 2018-10-05T16:59:26Z - generation: 1 - name: demo-snapshot-podpvc - namespace: default - -... - -status: - creationTime: 2018-10-05T16:59:27Z - ready: true - restoreSize: 6Gi - -``` -4. Create a new volume from the snapshot -``` -$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml -``` - -## Kubernetes Development - -### Manual - -To build and install a development version of the driver: -``` -$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to -$ make push-container - -# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image -$ GCE_PD_DRIVER_VERSION=dev -$ ./deploy/kubernetes/deploy-driver.sh -``` - -To bring down driver: -``` -$ ./deploy/kubernetes/delete-driver.sh -``` - -## Testing - -Running E2E Tests: -``` -$ PROJECT=my-project # GCP Project to run tests in -$ IAM_NAME=my-iam@project.iam.gserviceaccount.com # Existing IAM Account with GCE PD CSI Driver Permissions -$ ./test/run-e2e-local.sh -``` - -Running Sanity Tests: -``` -$ ./test/run-sanity.sh -``` - -Running Unit Tests: -``` -$ ./test/run-unit.sh -``` - -## Dependency Management - -Use [dep](https://github.com/golang/dep) -``` -$ dep ensure -``` - -To modify dependencies or versions change `./Gopkg.toml` +### Kubernetes Beta Features + +* Topology: Requires K8s 1.14+ on Master and Nodes and PD driver v0.5.0+ + +### Kubernetes Alpha Features + +* Snapshots: Requires K8s 1.13+ on Master and PD driver v0.3.0+ with the alpha + overlay + +### Future Features + +See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues) + +## Further Documentation + +[Local Development](docs/local-development.md) + +### Kubernetes + +[User Guides](docs/kubernetes/user-guides) + +[Driver Development](docs/kubernetes/development.md) diff --git a/docs/kubernetes/development.md b/docs/kubernetes/development.md new file mode 100644 index 000000000..fb4bf93ab --- /dev/null +++ b/docs/kubernetes/development.md @@ -0,0 +1,21 @@ +# Kubernetes Development + +## Manual + +To build and install a development version of the driver: +``` +$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev # Location to push dev image to +$ make push-container + +# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image +$ GCE_PD_DRIVER_VERSION=dev +$ ./deploy/kubernetes/deploy-driver.sh +``` + +To bring down driver: +``` +$ ./deploy/kubernetes/delete-driver.sh +``` + +## TODO Testing + diff --git a/docs/kubernetes/user-guides/basic.md b/docs/kubernetes/user-guides/basic.md new file mode 100644 index 000000000..da3c9de70 --- /dev/null +++ b/docs/kubernetes/user-guides/basic.md @@ -0,0 +1,87 @@ +# Kubernetes Basic User Guide +This guide gives a simple example on how to provision zonal and regional PDs in single-zone and regional clusters. + +**Note:** Regional cluster support only available in beta starting with +Kubernetes 1.14. + +## Install Driver + +1. [One-time per project] Create GCP service account for the CSI driver and set required roles +``` +$ PROJECT=your-project-here # GCP project +$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create +$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key +$ ./deploy/setup-project.sh +``` + +2. Deploy driver to Kubernetes Cluster +``` +$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key +$ GCE_PD_DRIVER_VERSION=stable # Driver version to deploy +$ ./deploy/kubernetes/deploy-driver.sh +``` + +## Zonal PD example +This example provisions a zonal PD in both single-zone and regional clusters. + +1. Create example Zonal Storage Class +``` +$ kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml +``` + +2. Create example PVC and Pod +``` +$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml +``` + +3. Verify PV is created and bound to PVC +``` +$ kubectl get pvc +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s +``` + +4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state) +``` +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +web-server 1/1 Running 0 1m +``` + +## Regional PD example + +**Note:** Regional cluster support only available in beta starting with +Kubernetes 1.14. + +This example provisions a regional PD in regional clusters. + +1. Create example Regional Storage Class. Choose between: + + * Unrestricted zones + ``` + $ kubectl apply -f ./examples/kubernetes/demo-regional-sc.yaml + ``` + + * Restricted zones + ``` + $ kubectl apply -f ./examples/kubernetes/demo-regional-restricted-sc.yaml + ``` + +2. Create example PVC and Pod +``` +$ kubectl apply -f ./examples/kubernetes/demo-pod.yaml +``` + +3. Verify PV is created and bound to PVC +``` +$ kubectl get pvc +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd 9s +``` + +4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state) +``` +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +web-server 1/1 Running 0 1m +``` diff --git a/docs/kubernetes/user-guides/snapshots.md b/docs/kubernetes/user-guides/snapshots.md new file mode 100644 index 000000000..885b14b43 --- /dev/null +++ b/docs/kubernetes/user-guides/snapshots.md @@ -0,0 +1,51 @@ +# Kubernetes Snapshots User Guide (Alpha) + +### Install Driver with alpha snapshot feature + +1. [One-time per project] Create GCP service account for the CSI driver and set required roles +``` +$ PROJECT=your-project-here # GCP project +$ GCE_PD_SA_NAME=my-gce-pd-csi-sa # Name of the service account to create +$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to save the service account key +$ ./deploy/setup-project.sh +``` + +2. Deploy driver to Kubernetes Cluster +``` +$ GCE_PD_SA_DIR=/my/safe/credentials/directory # Directory to get the service account key +$ GCE_PD_DRIVER_VERSION=alpha # Driver version to deploy +$ ./deploy/kubernetes/deploy-driver.sh +``` + +### Snapshot Example + +1. Create example Default Snapshot Class +``` +$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml +``` +2. Create a snapshot of the PVC created in above example +``` +$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml +``` +3. Verify Snapshot is created and is ready to use +``` +$ k get volumesnapshots demo-snapshot-podpvc -o yaml +apiVersion: snapshot.storage.k8s.io/v1alpha1 +kind: VolumeSnapshot +metadata: + creationTimestamp: 2018-10-05T16:59:26Z + generation: 1 + name: demo-snapshot-podpvc + namespace: default + +... + +status: + creationTime: 2018-10-05T16:59:27Z + ready: true + restoreSize: 6Gi + +``` +4. Create a new volume from the snapshot +``` +$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml diff --git a/docs/local-development.md b/docs/local-development.md new file mode 100644 index 000000000..f9984e893 --- /dev/null +++ b/docs/local-development.md @@ -0,0 +1,30 @@ +# Local development +This page contains information on how to develop and test the driver locally. + +## Testing + +Running E2E Tests: +``` +$ PROJECT=my-project # GCP Project to run tests in +$ IAM_NAME=my-iam@project.iam.gserviceaccount.com # Existing IAM Account with GCE PD CSI Driver Permissions +$ ./test/run-e2e-local.sh +``` + +Running Sanity Tests: +``` +$ ./test/run-sanity.sh +``` + +Running Unit Tests: +``` +$ ./test/run-unit.sh +``` + +## Dependency Management + +Use [dep](https://github.com/golang/dep) +``` +$ dep ensure +``` + +To modify dependencies or versions change `./Gopkg.toml` diff --git a/examples/kubernetes/demo-regional-restricted-sc.yaml b/examples/kubernetes/demo-regional-restricted-sc.yaml new file mode 100644 index 000000000..9e1f97741 --- /dev/null +++ b/examples/kubernetes/demo-regional-restricted-sc.yaml @@ -0,0 +1,15 @@ +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: csi-gce-pd +provisioner: pd.csi.storage.gke.io +parameters: + type: pd-standard + replication-type: regional-pd +volumeBindingMode: WaitForFirstConsumer +allowedTopologies: +- matchLabelExpressions: + - key: topology.gke.io/zone + values: + - us-central1-a + - us-central1-b diff --git a/examples/kubernetes/demo-regional-sc.yaml b/examples/kubernetes/demo-regional-sc.yaml index 170b21d98..2b83aad2a 100644 --- a/examples/kubernetes/demo-regional-sc.yaml +++ b/examples/kubernetes/demo-regional-sc.yaml @@ -1,4 +1,4 @@ -apiVersion: storage.k8s.io/v1beta1 +apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-gce-pd @@ -6,4 +6,4 @@ provisioner: pd.csi.storage.gke.io parameters: type: pd-standard replication-type: regional-pd -volumeBindingMode: Immediate +volumeBindingMode: WaitForFirstConsumer diff --git a/examples/kubernetes/demo-zonal-sc.yaml b/examples/kubernetes/demo-zonal-sc.yaml index 63c670cc5..631d192f7 100644 --- a/examples/kubernetes/demo-zonal-sc.yaml +++ b/examples/kubernetes/demo-zonal-sc.yaml @@ -1,8 +1,8 @@ -apiVersion: storage.k8s.io/v1beta1 +apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-gce-pd provisioner: pd.csi.storage.gke.io parameters: type: pd-standard -volumeBindingMode: Immediate +volumeBindingMode: WaitForFirstConsumer