### Install Longhorn Chart with Defaults

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Installs the Longhorn chart with default configurations into the 'longhorn-system' namespace, creating the namespace if it does not exist.

```bash
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace

```

--------------------------------

### Install Longhorn Chart

Source: https://github.com/longhorn/charts/blob/v1.12.x/charts/longhorn/README.md

Creates the 'longhorn-system' namespace and installs the Longhorn Helm chart within it. Ensure Helm 3 is used.

```bash
kubectl create namespace longhorn-system
helm install longhorn longhorn/longhorn --namespace longhorn-system
```

--------------------------------

### Install Longhorn Chart with Custom Values File

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Installs the Longhorn chart using a custom 'values.yaml' file for configuration.

```bash
helm install longhorn longhorn/longhorn -n longhorn-system -f values.yaml

```

--------------------------------

### Example PersistentVolumeClaim (PVC)

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

An example of a PersistentVolumeClaim requesting 10Gi of storage using the 'longhorn' StorageClass.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-data
spec:
  accessModes:
    - ReadWriteOnce          # Single node RWO
    # - ReadWriteMany        # Multi-node RWX (NFS)
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Longhorn Disk Configuration Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/overview.md

Shows an example of Longhorn disk configuration within a Kubernetes resource, specifying the path, scheduling allowance, and custom tags for a disk. This allows for managing multiple disks per node.

```yaml
spec:
  disks:
    disk-uuid:
      path: /var/lib/longhorn    # Mount point or block device
      allowScheduling: true       # Can schedule replicas here
      tags:
        - ssd
        - fast               # Custom tags for scheduling
```

--------------------------------

### Install Helm Chart with Custom Values via Arguments

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Shows how to install the Longhorn Helm chart using `--set` arguments to override specific configuration values.

```bash
helm install longhorn longhorn/longhorn \
  -n longhorn-system \
  --set global.imageRegistry=registry.example.com \
  --set persistence.defaultClassReplicaCount=3 \
  --set longhornUI.replicas=3 \
  --set 'defaultSettings.logLevel=Debug'
```

--------------------------------

### Kubernetes PersistentVolume (PV) Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/types.md

Example of a Kubernetes PersistentVolume automatically created by Longhorn for a volume. It specifies capacity, access modes, and CSI driver details.

```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-name
  labels:
    longhornvolume: volume-name
spec:
  capacity:
    storage: size
  accessModes:
    - ReadWriteOnce         # For RWO volumes
    # or
    - ReadWriteMany         # For RWX volumes
  persistentVolumeReclaimPolicy: Delete | Retain
  storageClassName: longhorn
  csi:
    driver: driver.longhorn.io
    volumeHandle: volume-name
```

--------------------------------

### Example API Call

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Demonstrates how to interact with the Longhorn Manager API using curl after port-forwarding.

```APIDOC
## Port-forward to Manager API

### Description
Establishes a connection to the Longhorn Manager API service for local access.

### Method
`kubectl port-forward -n longhorn-system svc/longhorn-manager 9500:9500 &`

### Endpoint
N/A (kubectl command)

## List Volumes via API

### Description
Lists all volumes using a curl command against the local Manager API endpoint.

### Method
`curl http://localhost:9500/v1/volumes`

### Endpoint
`http://localhost:9500/v1/volumes`

## Get Specific Volume via API

### Description
Retrieves details for a specific volume using a curl command against the local Manager API endpoint.

### Method
`curl http://localhost:9500/v1/volumes/my-volume`

### Endpoint
`http://localhost:9500/v1/volumes/my-volume`

### Parameters
#### Path Parameters
- **my-volume** (string) - Required - The name of the volume to retrieve.
```

--------------------------------

### Longhorn Manager API Volume Response Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Example JSON response from the Longhorn Manager API when retrieving volume details. This illustrates the structure and fields returned.

```json
{
  "type": "volume",
  "id": "my-volume",
  "name": "my-volume",
  "size": 10737418240,
  "state": "attached",
  "numberOfReplicas": 3,
  "currentImage": "longhornio/longhorn-engine:v1.12.0",
  "replicas": {
    "my-volume-r-xyz": {
      "name": "my-volume-r-xyz",
      "mode": "RW",
      "failedAt": "",
      "diskID": "disk-123",
      "nodeID": "node-1"
    }
  }
}
```

--------------------------------

### Install and Uninstall Longhorn Helm Chart

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Commands to add the Longhorn Helm repository, install the chart with default or custom values, and uninstall it.

```bash
# Add Longhorn Helm repository
helm repo add longhorn https://charts.longhorn.io
helm repo update

# Install with defaults
helm install longhorn longhorn/longhorn -n longhorn-system --create-namespace

# Install with custom values
helm install longhorn longhorn/longhorn -n longhorn-system \
  --set persistence.defaultClassReplicaCount=3 \
  --set longhornUI.replicas=2 \
  --set ingress.enabled=true \
  --set ingress.host=longhorn.example.com

# Uninstall
helm uninstall longhorn -n longhorn-system
```

--------------------------------

### Tag a Node

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Example of tagging a Kubernetes node using `kubectl label`.

```bash
# Tag a node
kubectl label nodes node-1 high-performance=true zone=zone1
```

--------------------------------

### Render Helm Charts to Manifests

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Demonstrates how to render Helm charts to Kubernetes manifest files without immediate installation, allowing for review before applying.

```bash
# Render charts without installing
helm template longhorn longhorn/longhorn \
  -n longhorn-system \
  -f values.yaml > manifest.yaml

# Review before applying
kubectl apply -f manifest.yaml
```

--------------------------------

### Longhorn StorageClass with XFS and Custom mkfs Params

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

An example StorageClass demonstrating the use of the XFS filesystem type and custom mkfs parameters for volume creation.

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-fast
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  fstype: "xfs"
  mkfsParams: "-f"
```

--------------------------------

### Create Backup

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Initiates a backup process for a volume. This involves creating a snapshot first, after which the backup automatically starts if a backup target is configured.

```APIDOC
## Create Backup

### Description
Initiates a backup process for a volume. This involves creating a snapshot first, after which the backup automatically starts if a backup target is configured.

### Method
APPLY (after snapshot creation)

### Endpoint
N/A

### Request Body
```yaml
# snapshot.yaml (same as Create Snapshot)
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: my-snapshot
  namespace: default
spec:
  volumeSnapshotClassName: csi-snapshot-class
  source:
    persistentVolumeClaimName: my-data
```

### Request Example
```bash
# Ensure backup target is configured first
kubectl get backuptarget -n longhorn-system

# Create snapshot (backup starts automatically)
kubectl apply -f snapshot.yaml

# Monitor backup progress
kubectl get backup -n longhorn-system -w
```

### Response
#### Success Response (200)
Backup process initiated. Monitor `kubectl get backup` for status.

### See Also
- [List Backups](#list-backups)
- [Restore from Backup](#restore-from-backup)
```

--------------------------------

### Describe Longhorn Replica

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Use this command to get detailed information about a specific Longhorn replica.

```bash
kubectl describe replica my-volume-r-abc -n longhorn-system
```

--------------------------------

### Select Disks by Tags

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Configure `diskSelector` with semicolon-separated tags to schedule replicas on specific disks. This example selects disks tagged with both 'fast' and 'nvme'.

```yaml
parameters:
  diskSelector: "fast;nvme"
  # Selects disks tagged with both "fast" AND "nvme"
```

--------------------------------

### Kubernetes StorageClass Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/types.md

Example of a Kubernetes StorageClass created by the Longhorn chart, serving as the default provisioner. It includes replica count, stale replica timeout, and filesystem type.

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn
provisioner: driver.longhorn.io
allowVolumeExpansion: true
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fstype: "ext4"
  mkfsParams: ""
  dataLocality: "disabled"
reclaimPolicy: Delete
volumeBindingMode: Immediate
```

--------------------------------

### Describe Longhorn Engine

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Use this command to get detailed information about a specific Longhorn engine.

```bash
kubectl describe engine my-volume-e-xyz -n longhorn-system
```

--------------------------------

### Kubernetes PersistentVolumeClaim (PVC) Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/types.md

Example of a Kubernetes PersistentVolumeClaim used by applications to request storage. It specifies access modes, storage class, and requested storage size.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-name
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Install Longhorn Chart with Inline Value Overrides

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Installs the Longhorn chart, overriding specific configuration values directly on the command line.

```bash
helm install longhorn longhorn/longhorn \
  -n longhorn-system \
  --set persistence.defaultClassReplicaCount=3 \
  --set longhornUI.replicas=2 \
  --set ingress.enabled=true \
  --set ingress.host=longhorn.example.com

```

--------------------------------

### Create Volume via PVC

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Use `kubectl apply` to create a volume by applying a PersistentVolumeClaim (PVC) definition. Monitor the creation progress using `kubectl get volume`.

```bash
# Via PVC (preferred)
kubectl apply -f pvc.yaml

# Check creation progress
kubectl get volume <volume-name> -w
kubectl describe volume <volume-name>
```

--------------------------------

### Tag a Disk via Longhorn CR

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Example of tagging a Longhorn disk by patching the node's Custom Resource.

```bash
# Tag a disk (via Longhorn CR)
kubectl patch node node-1 --type merge -p '{"spec":{"disks":{"disk-uuid":{"tags":["fast","nvme"]}}}}'
```

--------------------------------

### List All Volumes

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Use `kubectl get volume` to list all volumes. Options include listing with details (`-o wide`), in a specific namespace (`-n`), or watching for changes (`-w`).

```bash
# List all volumes
kubectl get volume

# List with details
kubectl get volume -o wide

# List in specific namespace
kubectl get volume -n longhorn-system

# Watch for changes
kubectl get volume -w
```

--------------------------------

### Describe Longhorn Volume

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Use this command to get detailed information about a specific Longhorn volume.

```bash
# Get details
kubectl describe volume my-volume -n longhorn-system
```

--------------------------------

### Longhorn API Version Example

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/types.md

This snippet shows the standard API version used for Longhorn resources, which is v1beta2 from the longhorn.io group.

```yaml
apiVersion: longhorn.io/v1beta2
kind: Volume
```

--------------------------------

### Create Backup from VolumeSnapshot

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Initiates a backup process by applying a VolumeSnapshot manifest. Ensure a backup target is configured in the longhorn-system namespace before proceeding. The backup starts automatically after the snapshot is created.

```bash
# Via Kubernetes VolumeSnapshot and target recovery
# First ensure backup target is configured:
kubectl get backuptarget -n longhorn-system

# Create snapshot (backup starts automatically)
kubectl apply -f snapshot.yaml

# Monitor backup
kubectl get backup -n longhorn-system -w
```

--------------------------------

### View Volume Details

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Get detailed information about a specific volume, which can be helpful for troubleshooting.

```bash
# View volume details
kubectl describe volume my-volume
```

--------------------------------

### List Replicas

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

List all replicas, filter replicas for a specific volume using a selector, or get detailed information for a specific replica in YAML format.

```bash
# List all replicas
kubectl get replica

# List replicas for a volume
kubectl get replica --selector=longhornvolume=<volume-name>

# Get details
kubectl get replica <replica-name> -o yaml
```

--------------------------------

### Basic RWO PersistentVolumeClaim

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Example of a PersistentVolumeClaim requesting a ReadWriteOnce volume with a specified storage size.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-claim
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Install Longhorn using Helm

Source: https://github.com/longhorn/charts/blob/v1.12.x/charts/longhorn/ocp-readme.md

Generate the Longhorn Kubernetes manifest using Helm and apply it to your OpenShift cluster. Ensure the namespace is created before applying the manifest.

```bash
# helm template ./chart/ --namespace longhorn-system --values ./chart/values.yaml --no-hooks > longhorn.yaml # Local Testing
helm template longhorn --namespace longhorn-system --values values.yaml --no-hooks  > longhorn.yaml
oc create namespace longhorn-system -o yaml --dry-run=client | oc apply -f -
oc apply -f longhorn.yaml -n longhorn-system
```

--------------------------------

### Select Nodes by Tags

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Use `nodeSelector` with semicolon-separated tags to schedule replicas on specific nodes. This example selects nodes tagged with both 'high-performance' and 'zone1'.

```yaml
parameters:
  nodeSelector: "high-performance;zone1"
  # Selects nodes tagged with both labels
```

--------------------------------

### Set Backup Execution Timeout

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Configures the timeout duration for backup execution in minutes. Setting this to 0 removes the limit. The example sets a 1-hour timeout.

```yaml
defaultSettings:
  backupExecutionTimeout: 60  # 1 hour timeout
```

--------------------------------

### Get Detailed Volume Metrics

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Obtain detailed metrics and status information for a specific volume using 'kubectl describe'. This command provides comprehensive insights into the volume's state.

```bash
kubectl describe volume <volume-name> | grep -A 20 "Status:"
```

--------------------------------

### Get Volume Details

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieve detailed information about a specific volume using `kubectl describe` or by outputting its YAML or JSON representation. You can also extract specific fields using `jsonpath`.

```bash
# Describe volume
kubectl describe volume <volume-name>

# Get as YAML
kubectl get volume <volume-name> -o yaml

# Get specific field
kubectl get volume <volume-name> -o jsonpath='{.status.state}'
```

--------------------------------

### List Volumes and Usage

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Monitor storage usage by listing all volumes and their associated usage statistics.

```bash
# List volumes and usage
kubectl get volume -o wide
```

--------------------------------

### Development Performance Tuning Configuration

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Configuration for development environments, prioritizing immediate volume binding and a single replica for faster iteration.

```yaml
persistence:
  defaultClassReplicaCount: 1
  volumeBindingMode: Immediate

defaultSettings:
  replicaSoftAntiAffinity: false
```

--------------------------------

### Get Volume Events

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

View events related to a specific Longhorn volume. This is crucial for troubleshooting issues.

```bash
kubectl describe volume <volume-name>
```

--------------------------------

### List All Volumes via API

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Use the Longhorn Manager API to list all available volumes. This is a fundamental operation for programmatic volume management.

```bash
curl http://localhost:9500/v1/volumes
```

--------------------------------

### Get PersistentVolumeClaim Status

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Command to check the status of a PersistentVolumeClaim. Wait for the status to be 'Bound' before creating a pod.

```bash
kubectl get pvc my-data
# Waits for "Bound" status before pod creation
```

--------------------------------

### RWX PersistentVolumeClaim

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Example of a PersistentVolumeClaim requesting a ReadWriteMany volume with a specified storage size, suitable for shared access.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shared-data
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: longhorn
  resources:
    requests:
      storage: 100Gi
```

--------------------------------

### Helm Template Helper for Labels

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Illustrates the usage of a Helm template helper to generate standard labels for resources.

```yaml
{{- include "longhorn.labels" . | nindent 4 }}

```

--------------------------------

### Configure V2 Data Engine

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/overview.md

Enable the experimental V2 Data Engine and configure memory and CPU mask settings. Requires additional CPU cores and hugepage memory.

```yaml
defaultSettings:
  v2DataEngine: true
  dataEngineMemorySize: "2048"        # MiB per instance manager
  dataEngineCPUMask: "0x3"            # CPU cores for SPDK
```

--------------------------------

### List Recurring Jobs

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Lists all configured recurring jobs, with options to watch for execution status or get detailed information.

```APIDOC
## List Recurring Jobs

### Description
Lists all configured recurring jobs, with options to watch for execution status or get detailed information.

### Method
GET

### Endpoint
- `/recurringjob`

### Request Example
```bash
# List all jobs
kubectl get recurringjob -n longhorn-system

# Watch job execution
kubectl get recurringjob -n longhorn-system -w

# Check job history
kubectl describe recurringjob daily-backup -n longhorn-system
```

### Response
#### Success Response (200)
A list of recurring job resources.

### See Also
- [Create Recurring Job](#create-recurring-job)
- [Edit Recurring Job](#edit-recurring-job)
- [Delete Recurring Job](#delete-recurring-job)
```

--------------------------------

### Verify Node Readiness

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Check the status of Kubernetes nodes to ensure they are ready to accept workloads.

```bash
# Verify node is ready
kubectl get nodes
kubectl describe node node-1
```

--------------------------------

### Check Current Helm Chart Version

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

List installed Helm charts in the longhorn-system namespace to check the current Longhorn version.

```bash
# Check current version
helm list -n longhorn-system
```

--------------------------------

### Create Custom Values File for Helm

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Demonstrates how to create a custom values file (custom-values.yaml) to override default Helm chart configurations for Longhorn.

```bash
# Create custom-values.yaml
cat > custom-values.yaml <<EOF
global:
  imageRegistry: registry.example.com
  imagePullSecrets:
    - name: regcred

persistence:
  defaultClassReplicaCount: 3
  defaultDataPath: /mnt/longhorn

longhornUI:
  replicas: 3

ingress:
  enabled: true
  host: longhorn.example.com
  tls: true
  tlsSecret: longhorn-tls

defaultSettings:
  defaultReplicaCount: '{"v1":"3"}'
  upgradeChecker: true
  logLevel: "Info"
EOF

# Install with custom values
helm install longhorn longhorn/longhorn \
  -n longhorn-system \
  -f custom-values.yaml
```

--------------------------------

### Get Replica States

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieve the states of all replicas associated with a specific volume. The '-o wide' flag provides more detailed output.

```bash
kubectl get replica --selector=longhornvolume=<volume-name> -o wide
```

--------------------------------

### Longhorn StorageClass with V2 Data Engine (Experimental)

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Configure the StorageClass to use the experimental V2 data engine, which is SPDK-based. Use with caution.

```yaml
parameters:
  dataEngine: "v2"
```

--------------------------------

### Get All Volume Status Conditions

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieve all status conditions for a given volume using kubectl. This helps in diagnosing volume health.

```bash
kubectl get volume <volume-name> -o jsonpath='{.status.conditions}'
```

--------------------------------

### Create Longhorn Snapshot

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Apply a snapshot definition to create a snapshot of a Longhorn volume.

```bash
# Snapshot
kubectl apply -f snapshot.yaml
```

--------------------------------

### WaitForFirstConsumer Volume Binding Mode

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Delays binding and scheduling until pod creation. Replicas are scheduled on the same nodes/zones as the pod, which is better for data locality and zone spreading, though it introduces a slight provisioning delay.

```yaml
volumeBindingMode: WaitForFirstConsumer
```

--------------------------------

### Longhorn StorageClass Performance Parameters

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Configure the data engine, disk selector, and node selector for performance tuning.

```yaml
parameters:
  dataEngine: "v1"              # or "v2" for SPDK
  diskSelector: "fast;nvme"     # Disk tags
  nodeSelector: "performance"   # Node tags
```

--------------------------------

### Use Backing Image as Base

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Specify a `backingImage` name to use it as the base for new volumes.

```yaml
parameters:
  backingImage: "ubuntu-20.04"
```

--------------------------------

### Get PVC Events

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

View events associated with a Persistent Volume Claim (PVC). This helps in understanding the lifecycle and potential issues related to the PVC.

```bash
kubectl describe pvc <pvc-name>
```

--------------------------------

### Check Chart Capabilities using Helm Templating

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Illustrates how to use Helm's `.Capabilities.APIVersions` object within templates to check for the presence of specific Kubernetes API versions, such as networking.k8s.io/v1 or gateway.networking.k8s.io/v1.

```go-template
# NetworkPolicy API version (v1 in K8s 1.25+)
{{ .Capabilities.APIVersions | has "networking.k8s.io/v1" }}

# Ingress API version (networking.k8s.io/v1 in K8s 1.19+)
{{ .Capabilities.APIVersions | has "networking.k8s.io/v1" }}

# Gateway API support
{{ .Capabilities.APIVersions | has "gateway.networking.k8s.io/v1" }}
```

--------------------------------

### Describe Failed Replica

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Get detailed information about a failed replica using 'kubectl describe'. This command provides status, events, and other relevant data for debugging.

```bash
kubectl describe replica <replica-name> -n longhorn-system
```

--------------------------------

### Helm Template Helper for Release Namespace

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Shows how to use a Helm template helper to retrieve the namespace of the current Helm release.

```yaml
{{- include "release_namespace" . }}

```

--------------------------------

### Get Volume Size and Usage

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Display the size and current usage of volumes using custom columns in kubectl. This provides a quick overview of storage consumption.

```bash
kubectl get volume -o custom-columns=NAME:.metadata.name,SIZE:.spec.size,USED:.status.currentSize,STATE:.status.state
```

--------------------------------

### Troubleshoot Snapshot/Backup Failures

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Address snapshot and backup failures by checking backup target configuration, credentials, recurring job status, and engine logs.

```bash
1. Check backup target configured: `kubectl get backuptarget`
2. Verify backup credentials: `kubectl get secret -n longhorn-system`
3. Check recurring job status: `kubectl get recurringjob -o wide`
4. Review engine logs: `kubectl logs -n longhorn-system <engine-pod-name>`
```

--------------------------------

### Get Volume Details

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieves detailed information about a specific Longhorn volume, including its status, configuration, and Kubernetes references. Output can be formatted as YAML or JSONPath.

```APIDOC
## Get Volume Details

### Description
Retrieves detailed information about a specific volume. You can get the full description, output in YAML format, or extract specific fields using JSONPath.

### Method
```bash
# Describe volume
kubectl describe volume <volume-name>

# Get as YAML
kubectl get volume <volume-name> -o yaml

# Get specific field
kubectl get volume <volume-name> -o jsonpath='{.status.state}'
```
```

--------------------------------

### Set Concurrent Restore Worker Limit

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Specifies the maximum number of worker threads allowed per restore operation. The default is 5. The example sets the limit to 3.

```yaml
defaultSettings:
  restoreConcurrentLimit: 3
```

--------------------------------

### Longhorn StorageClass Basic Parameters

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Configure the number of replicas and filesystem type for a Longhorn volume.

```yaml
parameters:
  numberOfReplicas: "3"
  fstype: "ext4"
```

--------------------------------

### Set Time-to-Live for Failed Backups

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Determines how long failed backups are retained in minutes. Setting this to 0 disables auto-deletion. The example retains failed backups for 24 hours.

```yaml
defaultSettings:
  failedBackupTTL: 1440  # Keep 24 hours
```

--------------------------------

### Set Backup Compression Method

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Configures the compression method used for backups. Options include `lz4` and `gzip`. `lz4` is the default if not set.

```yaml
defaultSettings:
  backupCompressionMethod: gzip
```

--------------------------------

### Check Instance Manager Logs

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Inspect the logs of the instance manager pods to diagnose issues related to volume attachment or other instance-level problems.

```bash
kubectl logs -n longhorn-system instance-manager-e-<node-name>
```

--------------------------------

### Get Specific Volume Details via API

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieve detailed information about a specific volume using its name via the Longhorn Manager API. This is useful for monitoring and management.

```bash
curl http://localhost:9500/v1/volumes/my-volume
```

--------------------------------

### List Replicas

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Lists all Longhorn replicas in the cluster or filters them by a specific volume. Details of individual replicas can be obtained using `kubectl get replica <replica-name> -o yaml`.

```APIDOC
## List Replicas

### Description
Lists all Longhorn replicas. You can list all replicas across the cluster or filter them to show only those associated with a specific volume using a label selector. Detailed information for a single replica can be retrieved in YAML format.

### Method
```bash
# List all replicas
kubectl get replica

# List replicas for a volume
kubectl get replica --selector=longhornvolume=<volume-name>

# Get details
kubectl get replica <replica-name> -o yaml
```
```

--------------------------------

### Create Volume via PersistentVolumeClaim

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Recommended method for creating Longhorn volumes by defining a PersistentVolumeClaim (PVC) with the Longhorn StorageClass. This approach integrates seamlessly with Kubernetes volume management.

```APIDOC
## Create Volume via PersistentVolumeClaim

### Description
Recommended method for creating Longhorn volumes by defining a PersistentVolumeClaim (PVC) with the Longhorn StorageClass. This approach integrates seamlessly with Kubernetes volume management.

### Method
`kubectl apply`

### Endpoint
N/A (Kubernetes resource definition)

### Parameters
N/A (Defined within the PVC YAML)

### Request Example
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-data
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi
```

### Response
N/A (Kubernetes resource status)

### Status
- `kubectl get pvc my-data` (Waits for "Bound" status)
```

--------------------------------

### Configure Data Engine Versions

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Enable or disable data engine versions using `v1DataEngine` and `v2DataEngine`. `v1DataEngine` is stable and recommended, while `v2DataEngine` is experimental. These are boolean settings.

```yaml
defaultSettings:
  v1DataEngine: true      # Stable, recommended
  v2DataEngine: false     # Experimental, not production
```

--------------------------------

### Create Filesystem for Separate Longhorn Mount

Source: https://github.com/longhorn/charts/blob/v1.12.x/charts/longhorn/ocp-readme.md

Creates an ext4 filesystem with the label 'longhorn' on a specified drive, intended for use as a separate Longhorn storage directory. This command is executed within a debug shell on the node.

```bash
oc get nodes --no-headers | awk '{print $1}'

export NODE="worker-0"
oc debug node/${NODE} -t -- chroot /host bash

# Validate Target Drive is Present
lsblk

export DRIVE="sdb" #vdb
sudo mkfs.ext4 -L longhorn /dev/${DRIVE}
```

--------------------------------

### Create PersistentVolumeClaim

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Recommended method for creating Longhorn volumes using a Kubernetes PersistentVolumeClaim. Ensure the Longhorn StorageClass is configured.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-data
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce      # RWO (single node)
    # - ReadWriteMany    # RWX (multiple nodes, NFS)
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Set Storage Over-Provisioning Percentage

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Defines the percentage of disk capacity that can be allocated to volumes. For example, 200% allows allocating 200 GB on a 100 GB disk. This setting is an Integer percentage with a range of 0-1000.

```yaml
defaultSettings:
  storageOverProvisioningPercentage: 150  # Allow 150% allocation
```

--------------------------------

### Configure Data Engine Log Flags

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Set `dataEngineLogFlags` for the SPDK target daemon to specify which components should log detailed information. For example, `"-L RPC,BDEV"` enables logging for RPC and BDEV components.

```yaml
defaultSettings:
  dataEngineLogFlags: "-L RPC,BDEV"
```

--------------------------------

### Longhorn Data Flow Diagram

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/overview.md

Illustrates the data flow from an application pod requesting storage to the underlying Longhorn volume and replica management.

```text
Application Pod
  │
  └─> PersistentVolumeClaim
       │
       └─> StorageClass (longhorn)
            │
            └─> CSI Provisioner
                 │
                 └─> Longhorn Volume CR
                      │
                      ├─> Engine (runs volume logic)
                      │    └─> iSCSI/Block Endpoint
                      │
                      └─> Replicas (3x by default)
                           └─> Instance Managers
                                └─> Disks on Nodes
```

--------------------------------

### Repair Replica by Deletion

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

To repair an unhealthy replica, check its status using `kubectl describe replica`. If necessary, mark it for rebuild by deleting the failed replica; Longhorn will automatically create a new one and rebuild the data. Monitor the rebuild progress with `kubectl get replica -w`.

```bash
# Check replica status
kubectl describe replica <replica-name>

# Mark for rebuild by deleting failed replica
kubectl delete replica <replica-name>
# Longhorn automatically creates new replica and rebuilds

# Monitor rebuild progress
kubectl get replica -w
```

--------------------------------

### Apply and Verify VolumeSnapshot

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Applies the VolumeSnapshot manifest and then checks its creation status using kubectl commands.

```bash
kubectl apply -f snapshot.yaml

# Check creation
kubectl get volumesnapshot
kubectl describe volumesnapshot my-snapshot
```

--------------------------------

### Expand Volume Size

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Expand a volume by patching the PVC's storage request or editing it directly. Monitor the expansion process using `kubectl get volume -w`. The expansion involves internal size increase and replica rebuilding, followed by a separate filesystem expansion within the pod.

```bash
# Edit PVC size
kubectl patch pvc <pvc-name> -p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'

# Or edit directly
kubectl edit pvc <pvc-name>

# Monitor expansion
kubectl get volume -w
```

--------------------------------

### Label and Annotate Storage Nodes

Source: https://github.com/longhorn/charts/blob/v1.12.x/charts/longhorn/ocp-readme.md

Use these commands to label and annotate OpenShift nodes for Longhorn's default disk configuration. Ensure the node variable is set correctly.

```bash
oc get nodes --no-headers | awk '{print $1}'
```

```bash
export NODE="worker-0"
oc annotate node ${NODE} --overwrite node.longhorn.io/default-disks-config='[{"path":"/var/mnt/longhorn","allowScheduling":true}]'
oc label node ${NODE} node.longhorn.io/create-default-disk=config
```

--------------------------------

### Verify Longhorn System Deployment

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Check the status of the Longhorn system deployment in the longhorn-system namespace.

```bash
kubectl get deployment -n longhorn-system
```

--------------------------------

### Helm Template Helper for Image Pull Policy

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Demonstrates using a Helm template helper to determine the image pull policy for container images.

```yaml
{{- include "longhorn.imagePullPolicy" . }}

```

--------------------------------

### View Longhorn Events

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Describe a Longhorn volume or PVC to view related Kubernetes events for troubleshooting.

```bash
# Events
kubectl describe volume my-volume
kubectl describe pvc my-data
```

--------------------------------

### Configure Guaranteed Instance Manager CPU

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Define the percentage of CPU cores guaranteed to the instance manager for V1 and V2 using `guaranteedInstanceManagerCPU`. This is a JSON string setting.

```yaml
defaultSettings:
  guaranteedInstanceManagerCPU: '{"v1":"12","v2":"12"}'
```

--------------------------------

### Longhorn CSI Driver Components

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/overview.md

Lists the CSI controller and node components implemented by Longhorn for Kubernetes dynamic volume provisioning. These components manage volume attachment, provisioning, resizing, snapshotting, and node-level operations.

```markdown
### CSI Driver Components

Longhorn implements the Kubernetes Container Storage Interface (CSI) for dynamic volume provisioning.

#### CSI Controller Components (Deployments)

| Component | Replicas | Image |
|-----------|----------|-------|
| csi-attacher | 3 (default) | `longhornio/csi-attacher:v4.12.0` |
| csi-provisioner | 3 (default) | `longhornio/csi-provisioner:v5.3.0` |
| csi-resizer | 3 (default) | `longhornio/csi-resizer:v2.1.0` |
| csi-snapshotter | 3 (default) | `longhornio/csi-snapshotter:v8.5.0` |
| csi-livenessprobe | 3 (default) | `longhornio/livenessprobe:v2.19.0` |

#### CSI Node Components (DaemonSets)

| Component | Image |
|-----------|-------|
| longhorn-csi-plugin | `longhornio/longhorn-manager:v1.12.0` |
| csi-node-driver-registrar | `longhornio/csi-node-driver-registrar:v2.17.0` |
```

--------------------------------

### Watch All Events

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Monitor all Kubernetes events in real-time across the cluster. The '-w' flag enables continuous watching.

```bash
kubectl get events -w
```

--------------------------------

### View Longhorn UI Logs

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Retrieve logs from the Longhorn UI pods for troubleshooting.

```bash
# UI logs
kubectl logs -n longhorn-system -l app=longhorn-ui
```

--------------------------------

### Generate Resource Labels with longhorn.labels

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Use the `longhorn.labels` helper to generate standard resource labels within your Helm templates. This ensures consistent labeling across all Kubernetes resources managed by the chart.

```go-template
{{- include "longhorn.labels" . | nindent 4 }}
```

--------------------------------

### List Snapshots

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Lists available snapshots, either through the Kubernetes VolumeSnapshot API or Longhorn's custom resource.

```APIDOC
## List Snapshots

### Description
Lists available snapshots, either through the Kubernetes VolumeSnapshot API or Longhorn's custom resource. You can also filter snapshots for a specific volume.

### Method
GET

### Endpoint
- `/` (for all VolumeSnapshots)
- `/snapshot` (for Longhorn CRs)

### Parameters
#### Query Parameters
- `longhornvolume` (string) - Optional - Filter snapshots by the associated Longhorn volume name.

### Request Example
```bash
# Via Kubernetes VolumeSnapshot
kubectl get volumesnapshot

# Via Longhorn CR
kubectl get snapshot -n longhorn-system

# For specific volume
kubectl get snapshot --selector=longhornvolume=<volume-name>
```

### Response
#### Success Response (200)
A list of snapshot resources.

### See Also
- [Create Snapshot](#create-snapshot)
- [Delete Snapshot](#delete-snapshot)
```

--------------------------------

### Volume Management Hierarchy Diagram

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/types.md

Illustrates the hierarchical relationships between Longhorn volume components, including Engine, Replica instances, Snapshot tree, BackingImage, and RecurringJob.

```text
Volume (spec)
  ├── Engine (runs volume logic)
  │   └── Replica instances (managed by InstanceManager)
  ├── Replica (data copy)
  ├── Snapshot (point-in-time copy)
  │   └── Snapshot tree (parent/child relationships)
  ├── BackingImage (optional base image)
  └── RecurringJob (scheduled operations)
```

--------------------------------

### Multi-version Kubernetes API Version Selection

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/helm-chart-api.md

Shows how to dynamically select the appropriate Kubernetes API version for a resource based on cluster capabilities.

```yaml
apiVersion: networking.k8s.io/{{ .Capabilities.APIVersions | has "networking.k8s.io/v1" | ternary "v1" "v1beta1" }}
kind: NetworkPolicy

```

--------------------------------

### Production Performance Tuning Configuration

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/quick-reference.md

Configuration for production environments, emphasizing data redundancy and availability with multiple replicas and anti-affinity rules.

```yaml
persistence:
  defaultClassReplicaCount: 3
  volumeBindingMode: WaitForFirstConsumer

defaultSettings:
  replicaSoftAntiAffinity: true
  replicaZoneSoftAntiAffinity: true
  dataLocality: best-effort
  replicaAutoBalance: best-effort
```

--------------------------------

### Troubleshoot Volume Stuck in Pending

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/storage-class-reference.md

Steps to diagnose why a volume is stuck in a pending state, including checking PVC status, StorageClass existence, node disk space, and Longhorn Manager logs.

```bash
1. Check PVC status: `kubectl describe pvc <name>`
2. Check StorageClass exists: `kubectl get storageclass`
3. Check disk space on nodes: `kubectl get node -o custom-columns=NAME:.metadata.name,DISK:.status.allocatable.ephemeralStorage`
4. Review Longhorn Manager logs: `kubectl logs -n longhorn-system -l app=longhorn-manager`
```

--------------------------------

### Error Handling

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Troubleshoot common Longhorn issues such as volumes stuck in 'Attaching' or replicas in a 'Failed' state.

```APIDOC
## Volume Stuck in "Attaching"

### Description
Troubleshoot volumes stuck in the 'Attaching' state by checking engine and instance manager pod logs.

### Method
`kubectl logs -n longhorn-system engine-<volume>-e-xyz` or `kubectl logs -n longhorn-system instance-manager-e-<node-name>`

### Endpoint
N/A (kubectl command)

## Replica in Failed State

### Description
Troubleshoot replicas in a 'Failed' state by checking replica logs, describing the replica, or deleting it to trigger a rebuild.

### Method
`kubectl logs -n longhorn-system replica-<volume>-r-xyz` or `kubectl describe replica <replica-name> -n longhorn-system` or `kubectl delete replica <replica-name> -n longhorn-system`

### Endpoint
N/A (kubectl command)

## Volume Unable to Rebuild

### Description
Troubleshoot volumes that are unable to rebuild by checking disk space, manager logs, node status, and volume selectors.

### Method
`kubectl describe node <node-name>` or `kubectl logs -n longhorn-system -l app=longhorn-manager` or `kubectl get volume <volume-name> -o yaml | grep -i selector`

### Endpoint
N/A (kubectl command)
```

--------------------------------

### Enable Default Disk Creation on Labeled Nodes

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

When enabled, default disks are only created on nodes with the label `node.longhorn.io/create-default-disk=true`. When disabled, default disks are created on all nodes.

```yaml
defaultSettings:
  createDefaultDiskLabeledNodes: true
```

--------------------------------

### Configure Engine Image Pod Liveness Probe Timeout

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/default-settings-reference.md

Set the timeout in seconds for liveness probes of engine image pods. Default is 4 seconds.

```yaml
defaultSettings:
  engineImagePodLivenessProbeTimeout: 5
```

--------------------------------

### List Longhorn Backups

Source: https://github.com/longhorn/charts/blob/v1.12.x/_autodocs/volume-api-reference.md

Retrieves a list of Longhorn backup resources from the longhorn-system namespace. Use '-o wide' for a detailed view or a selector to filter by volume.

```bash
# List all backups
kubectl get backup -n longhorn-system

# Detailed view
kubectl get backup -n longhorn-system -o wide

# For specific volume
kubectl get backup --selector=longhornvolume=<volume-name>
```