Skip to content

Commit

Permalink
Adds README documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@vladimirvivien
vladimirvivien committed Jan 16, 2019
1 parent 8169bdc commit 57bcb23
Showing 1 changed file with 195 additions and 13 deletions.
208 changes: 195 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,198 @@
# Kubernetes Template Project

The Kubernetes Template Project is a template for starting new projects in the GitHub organizations owned by Kubernetes. All Kubernetes projects, at minimum, must have the following files:

- a `README.md` outlining the project goals, sponsoring sig, and community contact information
- an `OWNERS` with the project leads listed as approvers ([docs on `OWNERS` files][owners])
- a `CONTRIBUTING.md` outlining how to contribute to the project
- an unmodified copy of `code-of-conduct.md` from this repo, which outlines community behavior and the consequences of breaking the code
- a `LICENSE` which must be Apache 2.0 for code projects, or [Creative Commons 4.0] for documentation repositories, without any custom content
- a `SECURITY_CONTACTS` with the contact points for the Product Security Team
to reach out to for triaging and handling of incoming issues. They must agree to abide by the
[Embargo Policy](https://github.com/kubernetes/sig-release/blob/master/security-release-process-documentation/security-release-process.md#embargo-policy)
and will be removed and replaced if they violate that agreement.
# CSI Hostpath Driver

This repository hosts the CSI Hostpath driver and all of its build and dependent configuration files to deploy the driver.

## Pre-requisite
- Kubernetes cluster
- Running verrsion 1.13 or later
- Access to terminal with `kubectl` installed

## Deployment
The easiest way to test the Hostpath driver is to run `deploy/deploy-hostpath.sh` scrip as show:

```shell
$ sh deploy/deploy-hostpath.sh
```

Or, if you want to override the version

```shell
$ K8S_RELEASE=1.14 CSI_RELEASE=1.0.1 sh deploy/deploy-hostpath.sh
```

You should see an output similar to the following printed on the terminal showing the application of rbac rules and the result of deploying the hostpath driver, external privisioner and external attacher components:

```shell
customresourcedefinition.apiextensions.k8s.io/csidrivers.csi.storage.k8s.io created
customresourcedefinition.apiextensions.k8s.io/csinodeinfos.csi.storage.k8s.io created
serviceaccount/csi-provisioner created
clusterrole.rbac.authorization.k8s.io/external-provisioner-runner created
clusterrolebinding.rbac.authorization.k8s.io/csi-provisioner-role created
role.rbac.authorization.k8s.io/external-provisioner-cfg created
rolebinding.rbac.authorization.k8s.io/csi-provisioner-role-cfg created
serviceaccount/csi-attacher created
clusterrole.rbac.authorization.k8s.io/external-attacher-runner created
clusterrolebinding.rbac.authorization.k8s.io/csi-attacher-role created
role.rbac.authorization.k8s.io/external-attacher-cfg created
rolebinding.rbac.authorization.k8s.io/csi-attacher-role-cfg created
serviceaccount/csi-driver-registrar created
clusterrole.rbac.authorization.k8s.io/driver-registrar-runner created
clusterrolebinding.rbac.authorization.k8s.io/csi-driver-registrar-role created
service/csi-hostpath-attacher created
statefulset.apps/csi-hostpath-attacher created
daemonset.apps/csi-hostpathplugin created
service/csi-hostpath-provisioner created
statefulset.apps/csi-hostpath-provisioner created
serviceaccount/csi-node-sa created
clusterrole.rbac.authorization.k8s.io/csi-node-sa created
clusterrolebinding.rbac.authorization.k8s.io/csi-node-sa created
```

## Run example application and validate

Next, validate the deployment. First, ensure all expected pods are running properly including the external attacher, provisioner, and the actual hostpath driver plugin:

```shell
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
csi-hostpath-attacher-0 1/1 Running 0 5m47s
csi-hostpath-provisioner-0 1/1 Running 0 5m47s
csi-hostpathplugin-lzzlc 2/2 Running 0 5m45s
```

From the root directory, deploy the application pods including a storage class, a PVC, and a pod which mounts a volume using the Hostpath driver found in directory `./examples`:

```shell
$ kubectl create -f ./examples
pod/my-csi-app created
persistentvolumeclaim/csi-pvc created
storageclass.storage.k8s.io/csi-hostpath-sc created
```

Let's validate the components are deployed:

```shell
$> kubectl get pv
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE
pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1 1Gi RWO Delete Bound default/csi-pvc csi-hostpath-sc 80s

$> kubectl get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
csi-pvc Bound pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1 1Gi RWO csi-hostpath-sc 93s
```

Finally, inspect the application pod `my-csi-app` which mounts a Hostpath volume:

```shell
$> kubectl describe pods/my-csi-app
Name: my-csi-app
Namespace: default
Priority: 0
PriorityClassName: <none>
Node: 127.0.0.1/127.0.0.1
Start Time: Wed, 19 Dec 2018 18:25:29 -0500
Labels: <none>
Annotations: <none>
Status: Running
IP: 172.17.0.5
Containers:
my-frontend:
Container ID: docker://927dc537fd14704794e1167b75a5aa040eb86eff76e155672be65c5cf9bda798
Image: busybox
Image ID: docker-pullable://busybox@sha256:2a03a6059f21e150ae84b0973863609494aad70f0a80eaeb64bddd8d92465812
Port: <none>
Host Port: <none>
Command:
sleep
1000000
State: Running
Started: Wed, 19 Dec 2018 18:25:33 -0500
Ready: True
Restart Count: 0
Environment: <none>
Mounts:
/data from my-csi-volume (rw)
/var/run/secrets/kubernetes.io/serviceaccount from default-token-wm562 (ro)
Conditions:
Type Status
Initialized True
Ready True
ContainersReady True
PodScheduled True
Volumes:
my-csi-volume:
Type: PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
ClaimName: csi-pvc
ReadOnly: false
default-token-wm562:
Type: Secret (a volume populated by a Secret)
SecretName: default-token-wm562
Optional: false
QoS Class: BestEffort
Node-Selectors: <none>
Tolerations: node.kubernetes.io/not-ready:NoExecute for 300s
node.kubernetes.io/unreachable:NoExecute for 300s
Events: <none>
```

## Confirm Hostpath driver works
The Hostpath driver is configured to create new volumes under `/tmp` inside the hostpath container that is specified in the plugin DaemonSet found [here](./deploy/hostpath/csi-hostpath-plugin.yaml). This path persist as long as the DaemonSet pod is up and running.

A file written in a properly mounted Hostpath volume inside an application should show up inside the Hostpath container. The following steps confirms that Hostpath is working properly. First, create a file from the application pod as shown:

```shell
$ kubectl exec -it my-csi-app /bin/sh
/ # touch /data/hello-world
/ # exit
```

Next, ssh into the Hostpath container and verify that the file shows up there:
```shell
$ kubectl exec -it $(kubectl get pods --selector app=csi-hostpathplugin -o jsonpath='{.items[*].metadata.name}') -c hostpath /bin/sh

```
Then, use the following command to locate the file. If everything works OK you should get a result similar to the following:

```shell
/ # find / -name hello-world
/tmp/057485ab-c714-11e8-bb16-000c2967769a/hello-world
/ # exit
```

## Confirm the creation of the VolumeAttachment object
An additional way to ensure the driver is working properly is by inspecting the VolumeAttachment API object created that represents the attached volume:

```shell
$> kubectl describe volumeattachment
Name: csi-a7515d53b30a1193fd70b822b18181cff1d16422fd922692bce5ea234cb191e9
Namespace:
Labels: <none>
Annotations: <none>
API Version: storage.k8s.io/v1
Kind: VolumeAttachment
Metadata:
Creation Timestamp: 2018-12-19T23:25:29Z
Resource Version: 533
Self Link: /apis/storage.k8s.io/v1/volumeattachments/csi-a7515d53b30a1193fd70b822b18181cff1d16422fd922692bce5ea234cb191e9
UID: 5fb4874f-03e5-11e9-be51-000c29e88ff1
Spec:
Attacher: csi-hostpath
Node Name: 127.0.0.1
Source:
Persistent Volume Name: pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1
Status:
Attached: true
Events: <none>
```


## Building the binaries
If you want to build the driver yourself, you can do so with the following command from the root directory:

```shell
make hostpath
```


## Community, discussion, contribution, and support

Expand Down

0 comments on commit 57bcb23

Please sign in to comment.