From e29522d101715398924ced51c9d370fa395407e4 Mon Sep 17 00:00:00 2001 From: Robert Vasek Date: Thu, 22 Feb 2024 10:54:06 +0100 Subject: [PATCH] added docs --- docs/building-from-source.md | 23 +++++++++++++ docs/deploying.md | 64 ++++++++++++++++++++++++++++++++++++ docs/how-to-use.md | 3 ++ 3 files changed, 90 insertions(+) create mode 100644 docs/building-from-source.md create mode 100644 docs/deploying.md create mode 100644 docs/how-to-use.md diff --git a/docs/building-from-source.md b/docs/building-from-source.md new file mode 100644 index 0000000..aa58896 --- /dev/null +++ b/docs/building-from-source.md @@ -0,0 +1,23 @@ +# Building EOSxd CSI from source + +There are pre-built container images available from [eosxd-csi repository in CERN registry](https://registry.cern.ch/harbor/projects/2335/repositories/eosxd-csi/artifacts-tab) (`docker pull registry.cern.ch/kubernetes/eosxd-csi`). If however you need to build EOSxd CSI from source, you can follow this guide. + +EOSxd CSI is written in Go. Make sure you have Go compiler and other related build tools installed before continuing. + +Clone [github.com/cern-eos/eosxd-csi](https://github.com/cern-eos/eosxd-csi) repository: +```bash +git clone https://github.com/cern-eos/eosxd-csi.git +cd eosxd-csi +``` + +There are different build targets available in the provided Makefile. To build only the EOSxd CSI executables, run following command: +```bash +make +``` + +After building successfully, the resulting executable files can be found in `bin/-` (e.g. `bin/linux-amd64`). + +You can also build container images. By default, Docker is used for building. To build a container image using e.g. Podman, run following command: +```bash +TARGETS=linux/amd64 IMAGE_BUILD_TOOL=podman make image +``` diff --git a/docs/deploying.md b/docs/deploying.md new file mode 100644 index 0000000..86f1f17 --- /dev/null +++ b/docs/deploying.md @@ -0,0 +1,64 @@ +# Deploying EOSxd CSI driver in Kubernetes + +EOSxd CSI deployment consists of a DaemonSet node plugin that handles node local mount-unmount operations, and ConfigMaps storing EOSxd client configuration. + +Cluster administrators may deploy EOSxd CSI manually using the provided Kubernetes manifests, or by installing eosxd-csi Helm chart. + +After successful deployment, you can try examples in [../example/](../example/). + +## Deployment with Helm chart + +Helm chart can be installed from CERN registry: + +```bash +helm install eosxd-csi oci://registry.cern.ch/kubernetes/charts/eosxd-csi --version +``` + +Some chart values may need to be customized to suite your EOSxd environment. Please consult the documentation in [../deployments/helm/README.md](../deployments/helm/README.md) to see available values. + +## Verifying the deployment + +After successful deployment, you should see similar output from `kubectl get all -l app=eosxd-csi`: + +``` +$ kubectl -n eos get all -l app=eosxd-csi +NAME READY STATUS RESTARTS AGE +pod/eosxd-csi-controllerplugin-7dbdfd6569-79n77 2/2 Running 0 22s +pod/eosxd-csi-nodeplugin-94sbp 4/4 Running 0 22s + +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +daemonset.apps/eosxd-csi-nodeplugin 1 1 1 1 1 22s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/eosxd-csi-controllerplugin 1/1 1 1 23s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/eosxd-csi-controllerplugin-7dbdfd6569 1 1 1 23s +``` + +## csi-driver command line arguments + +EOSxd CSI driver executable accepts following set of command line arguments: + +|Name|Default value|Description| +|--|--|--| +|`--endpoint`|`unix:///var/lib/kubelet/plugins/eosxd.csi.cern.ch/csi.sock`|(string value) CSI endpoint. EOSxd CSI will create a UNIX socket at this location.| +|`--drivername`|`eosxd.csi.cern.ch`|(string value) Name of the driver that is used to link PersistentVolume objects to EOSxd CSI driver.| +|`--nodeid`|_none, required_|(string value) Unique identifier of the node on which the EOSxd CSI node plugin pod is running. Should be set to the value of `Pod.spec.nodeName`.| +|`--automount-startup-timeout`|_10_|number of seconds to wait for automount daemon to start up before exiting. `0` means no timeout.| +|`--role`|_none, required_|Enable driver service role (comma-separated list or repeated `--role` flags). Allowed values are: `identity`, `node`, `controller`.| +|`--version`|_false_|(boolean value) Print driver version and exit.| + +## automount-runner command line arguments + +|Name|Default value|Description| +|--|--|--| +|`--unmount-timeout`|_-1_|number of seconds of idle time after which an autofs-managed EOSxd mount will be unmounted. `0` means never unmount.| +|`--version`|_false_|(boolean value) Print driver version and exit.| + +## mount-reconciler command line arguments + +|Name|Default value|Description| +|--|--|--| +|`--frequency`|`30s`|(Golang [`time.Duration`](https://pkg.go.dev/time#Duration) value, see [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration) for accepted values) How often to check mounts in `/eos`| +|`--version`|_false_|(boolean value) Print driver version and exit.| diff --git a/docs/how-to-use.md b/docs/how-to-use.md new file mode 100644 index 0000000..ff458de --- /dev/null +++ b/docs/how-to-use.md @@ -0,0 +1,3 @@ +# How to use EOSxd CSI driver in Kubernetes + +(TODO)