Skip to content

Commit

Permalink
refactor documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: Bala.FA <[email protected]>
  • Loading branch information
@balamurugana
balamurugana committed Jun 23, 2023
1 parent 514fc98 commit ca068c1
Show file tree
Hide file tree
Showing 27 changed files with 1,250 additions and 1,079 deletions.
24 changes: 24 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# DirectPV
DirectPV is a CSI driver to provision local volumes to Pods using [Direct Attached Storage](https://en.wikipedia.org/wiki/Direct-attached_storage). It comes with two components.
1. `DirectPV plugin` - To be installed on local machine, to manage DirectPV CSI driver.
2. `DirectPV CSI driver` - To be installed on kubernetes cluster, to provision local volumes.

## For new users
Refer below documentation
* [Installation guide](./installation.md)
* [Drive management guide](./drive-management.md)
* [Volume provisioning guide](./volume-provisioning.md)
* [Volume management guide](./volume-management.md)
* [Command reference guide](./command-reference.md)
* [Monitoring guide](./monitoring.md)

## For existing users
Refer below documentation
* [Upgrade guide](./upgrade.md)
* [Node management guide](./node-management.md)

## Further references
* [Volume scheduling guide](./volume-scheduling.md)
* [Issue reporting](./issue-reporting.md)
* [DirectPV CSI driver specification](./specification.md)
* [Troubleshooting guide](./troubleshooting.md)
234 changes: 96 additions & 138 deletions docs/architecture.md
View file

Large diffs are not rendered by default.

219 changes: 139 additions & 80 deletions docs/cli.md → docs/command-reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,50 @@
### Install Kubectl plugin

The `directpv` kubectl plugin can be used to manage the lifecycle of volumes and drives in the kubernetes cluster

```sh
$ kubectl krew install directpv
# Command reference

## Prerequisites
* Working DirectPV plugin. To install the plugin, refer [installation guide](./installation.md#directpv-plugin-installation).
* Working DirectPV CSI driver in Kubernetes. To install the driver, refer [installation guide](./installation.md#directpv-csi-driver-installation).

## Note
DirectPV plugin command is referred as `kubectl directpv` in this document. For direct binary users, replace with `kubectl-directpv`.

## Command changes from DirectCSI
| DirectCSI command | DirectPV command |
|:---------------------------------|:----------------------------------------------------------|
| `kubectl directcsi drives list` | `kubectl directpv list drives` |
| `kubectl directcsi volumes list` | `kubectl directpv list volumes` |
| `kubectl directcsi format` | `kubectl directpv discover`, then `kubectl directpv init` |

## Global flags
Any plugin command has below global flags.

| Flag | Argument | Description |
|:---------------|:---------|:----------------------------------------------------|
| `--kubeconfig` | _string_ | Path to the kubeconfig file to use for CLI requests |
| `--quiet` | - | Suppress printing error messages |
| `-h`, `--help` | - | help for directpv |
| `--version` | - | version for directpv |
## Commands
List of subcommands are below

| Subcommand | Description |
|:------------|:----------------------------------------------------------------------------------|
| `install` | Install DirectPV in Kubernetes |
| `discover` | Discover new drives |
| `init` | Initialize the drives |
| `info` | Show information about DirectPV installation |
| `list` | List drives and volumes |
| `label` | Set labels to drives and volumes |
| `cordon` | Mark drives as unschedulable |
| `uncordon` | Mark drives as schedulable |
| `migrate` | Migrate drives and volumes from legacy DirectCSI |
| `move` | Move volumes excluding data from source drive to destination drive on a same node |
| `clean` | Cleanup stale volumes |
| `remove` | Remove unused drives from DirectPV |
| `uninstall` | Uninstall DirectPV in Kubernetes |

## `install` command
```

### Install DirectPV

Install DirectPV in your kubernetes cluster

```sh
$ kubectl directpv install --help
Install DirectPV in Kubernetes
USAGE:
Expand All @@ -22,13 +55,14 @@ FLAGS:
--tolerations strings Set toleration labels on the storage nodes (KEY[=VALUE]:EFFECT,..)
--registry string Name of container registry (default "quay.io")
--org string Organization name in the registry (default "minio")
--image string Name of the DirectPV image (default "directpv:0.0.0-dev")
--image string Name of the DirectPV image (default "directpv:v4.0.6")
--image-pull-secrets strings Image pull secrets for DirectPV images (SECRET1,..)
--apparmor-profile string Set path to Apparmor profile
--seccomp-profile string Set path to Seccomp profile
-o, --output string Generate installation manifest. One of: yaml|json
--kube-version string Select the kubernetes version for manifest generation (default "1.27.0")
--legacy Enable legacy mode (Used with '-o')
--openshift Use OpenShift specific installation
-h, --help help for install
GLOBAL FLAGS:
Expand Down Expand Up @@ -56,15 +90,10 @@ EXAMPLES:
7. Install DirectPV with seccomp profile
$ kubectl directpv install --seccomp-profile profiles/seccomp.json

```

### Discover drives

Discover the block devices present in the cluster

```sh
$ kubectl directpv discover --help
## `discover` command
```
Discover new drives
USAGE:
Expand Down Expand Up @@ -97,24 +126,18 @@ EXAMPLES:
5. Discover specific drives from specific nodes
$ kubectl directpv discover --nodes=node{1...4} --drives=sd{a...f}

```

### Initialize the available drives present in the cluster

Initializing the drives will format the selected drives with XFS filesystem and mount them to `/var/lib/directpv/mnt/<UUID>`. DirectPV can then use the initialized drives for provisioning Persistent Volumes in respones to PVC with the `directpv-min-io` storage class.

**Warning**: This command will completely and irreversibly erase the data (mkfs) in the selected disks by formatting them

```sh
$ kubectl directpv init --help
## `init` command
```
Initialize the drives
USAGE:
directpv init drives.yaml [flags]
FLAGS:
--timeout duration specify timeout for the initialization process (default 2m0s)
--dangerous Perform initialization of drives which will permanently erase existing data
-h, --help help for init
GLOBAL FLAGS:
Expand All @@ -124,13 +147,10 @@ GLOBAL FLAGS:
EXAMPLES:
1. Initialize the drives
$ kubectl directpv init drives.yaml

```

### Show overall information about the DirectPV installation in the cluster

```sh
$ kubectl directpv info --help
## `info` command
```
Show information about DirectPV installation
USAGE:
Expand All @@ -142,13 +162,35 @@ FLAGS:
GLOBAL FLAGS:
--kubeconfig string Path to the kubeconfig file to use for CLI requests
--quiet Suppress printing error messages
```

## `list` command
```
List drives and volumes
USAGE:
directpv list [command]
FLAGS:
-n, --nodes strings Filter output by nodes; supports ellipses pattern e.g. node{1...10}
-d, --drives strings Filter output by drive names; supports ellipses pattern e.g. sd{a...z}
-o, --output string Output format. One of: json|yaml|wide
--no-headers When using the default or custom-column output format, don't print headers (default print headers)
-h, --help help for list
GLOBAL FLAGS:
--kubeconfig string Path to the kubeconfig file to use for CLI requests
--quiet Suppress printing error messages
### List the drives initialized and managed by DirectPV
AVAILABLE COMMANDS:
drives List drives
volumes List volumes
```sh
$ kubectl directpv list drives --help
Use "directpv list [command] --help" for more information about this command.
```

### `drives` command
```
List drives
USAGE:
Expand Down Expand Up @@ -196,13 +238,10 @@ EXAMPLES:
8. List drives filtered by labels
$ kubectl directpv list drives --labels tier=hot
```

### List the volumes provisioned and managed by DirectPV
```sh
$ kubectl directpv list volumes --help
### `volumes` command
```
List volumes
USAGE:
Expand Down Expand Up @@ -260,13 +299,35 @@ EXAMPLES:
10. List volumes filtered by labels
$ kubectl directpv list volumes --labels tier=hot
```

## `label` command
```
Set labels to drives and volumes
USAGE:
directpv label [command]
FLAGS:
-n, --nodes strings If present, filter objects from given nodes; supports ellipses pattern e.g. node{1...10}
-d, --drives strings If present, filter objects by given drive names; supports ellipses pattern e.g. sd{a...z}
--all If present, select all objects
--dry-run Run in dry run mode
-h, --help help for label
### Set lables on the drives managed by DirectPV
GLOBAL FLAGS:
--kubeconfig string Path to the kubeconfig file to use for CLI requests
--quiet Suppress printing error messages
AVAILABLE COMMANDS:
drives Set labels to drives
volumes Set labels to volumes
Use "directpv label [command] --help" for more information about this command.
```

```sh
$ kubectl directpv label drives --help
### `drives` command
```
Set labels to drives
USAGE:
Expand Down Expand Up @@ -298,13 +359,10 @@ EXAMPLES:
3. Remove 'tier: hot' label from all drives in all nodes
$ kubectl directpv label drives tier- --all

```

### Set labels on the volumes managed by DirectPV
```sh
$ kubectl directpv label volumes --help
### `volumes` command
```
Set labels to volumes
USAGE:
Expand Down Expand Up @@ -339,13 +397,10 @@ EXAMPLES:
3. Remove 'tier: hot' label from all volumes in all nodes
$ kubectl directpv label volumes tier- --all

```

### Cordon the drives to make them unschedulable
```sh
$ kubectl directpv cordon --help
## `cordon` command
```
Mark drives as unschedulable
USAGE:
Expand Down Expand Up @@ -378,13 +433,10 @@ EXAMPLES:
5. Cordon drives which are in 'error' status
$ kubectl directpv cordon --status=error

```

### Uncordon the cordoned drives
```sh
$ kubectl directpv uncordon --help
## `uncordon` command
```
Mark drives as schedulable
USAGE:
Expand Down Expand Up @@ -420,13 +472,30 @@ EXAMPLES:
6. Uncordon drives which are in 'error' status
$ kubectl directpv uncordon --status=error
```

## `migrate` command
```
Migrate drives and volumes from legacy DirectCSI
USAGE:
directpv migrate [flags]
### Move volumes from one drive to another drive within a node (excluding data)
FLAGS:
--dry-run Run in dry run mode
-h, --help help for migrate
GLOBAL FLAGS:
--kubeconfig string Path to the kubeconfig file to use for CLI requests
--quiet Suppress printing error messages
```sh
$ kubectl directpv move --help
EXAMPLES:
1. Migrate drives and volumes from legacy DirectCSI
$ kubectl directpv migrate
```

## `move` command
```
Move volumes excluding data from source drive to destination drive on a same node
USAGE:
Expand All @@ -445,13 +514,10 @@ GLOBAL FLAGS:
EXAMPLES:
1. Move volumes from drive af3b8b4c-73b4-4a74-84b7-1ec30492a6f0 to drive 834e8f4c-14f4-49b9-9b77-e8ac854108d5
$ kubectl directpv drives move af3b8b4c-73b4-4a74-84b7-1ec30492a6f0 834e8f4c-14f4-49b9-9b77-e8ac854108d5

```

### Cleanup stale (released|deleted) volumes
```sh
$ kubectl directpv clean --help
## `clean` command
```
Cleanup stale volumes
USAGE:
Expand Down Expand Up @@ -492,13 +558,10 @@ EXAMPLES:
7. Clean volumes by pod namespace
$ kubectl directpv clean --pod-namespaces=tenant-{1...3}

```

### Remove unused drives from DirectPV
```sh
$ kubectl directpv remove --help
## `remove` command
```
Remove unused drives from DirectPV
USAGE:
Expand Down Expand Up @@ -531,13 +594,10 @@ EXAMPLES:
5. Remove drives are in 'error' status
$ kubectl directpv remove --status=error

```

### Uninstall DirectPV from the kubernetes cluster
```sh
$ kubectl directpv uninstall --help
## `uninstall` command
```
Uninstall DirectPV in Kubernetes
USAGE:
Expand All @@ -549,5 +609,4 @@ FLAGS:
GLOBAL FLAGS:
--kubeconfig string Path to the kubeconfig file to use for CLI requests
--quiet Suppress printing error messages

```
Loading

0 comments on commit ca068c1

Please sign in to comment.