167 lines
5.3 KiB
Markdown
167 lines
5.3 KiB
Markdown
# Longhorn
|
|
|
|
Longhorn is a lightweight, reliable, and powerful distributed block storage system for Kubernetes.
|
|
|
|
## Table of Contents
|
|
|
|
- [Installation](#installation)
|
|
- [Resource Configuration](#resource-configuration)
|
|
- [OAuth2-Proxy Integration](#oauth2-proxy-integration)
|
|
- [References](#references)
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Kubernetes cluster with sufficient resources
|
|
- Storage class support
|
|
- Open-iSCSI installed on nodes
|
|
|
|
### Install Longhorn
|
|
|
|
```bash
|
|
just longhorn::install
|
|
```
|
|
|
|
This command will:
|
|
|
|
1. Add Longhorn Helm repository
|
|
2. Install Longhorn via Helm with custom values
|
|
3. Configure storage class with single replica
|
|
4. Apply resource limits to all Longhorn components (via `patch-resources` recipe)
|
|
|
|
### Verify Installation
|
|
|
|
```bash
|
|
# Check Longhorn pods
|
|
kubectl get pods -n longhorn
|
|
|
|
# Check storage class
|
|
kubectl get storageclass
|
|
```
|
|
|
|
## Resource Configuration
|
|
|
|
### Why We Use Kubernetes Patch Instead of Helm Values
|
|
|
|
Longhorn Helm chart **does not support** configuring resource requests/limits for most components through `values.yaml`.
|
|
|
|
**Known Issues:**
|
|
|
|
- The `resources: {}` field exists in `values.yaml` but is **not used** in chart templates
|
|
- GitHub Issue: [#1502 - Add resource requests/limits to default deployment/controller rollouts](https://github.com/longhorn/longhorn/issues/1502)
|
|
- Related Issues:
|
|
- [#3186 - Resources limits in chart values.yaml not work](https://github.com/longhorn/longhorn/issues/3186)
|
|
- [Discussion #4446 - Resources section in helm chart values file isn't used?](https://github.com/longhorn/longhorn/discussions/4446)
|
|
- [Discussion #8282 - How to adjust longhorn ui and other components minimum cpu and memory request with helm](https://github.com/longhorn/longhorn/discussions/8282)
|
|
|
|
**Pull Request Status:**
|
|
|
|
- PR [#10187 - Allow setting requests and limits for LonghornUI, LonghornDriver and LonghornManager](https://github.com/longhorn/longhorn/pull/10187) was opened in January 2025 but **closed without merging** in April 2025.
|
|
|
|
### Our Approach: Post-Install Patching
|
|
|
|
Since Helm values don't work, we apply resource configurations **after installation** using `kubectl patch`:
|
|
|
|
```bash
|
|
just longhorn::patch-resources
|
|
```
|
|
|
|
This recipe is automatically called by `just longhorn::install`.
|
|
|
|
### Resource Values
|
|
|
|
All resource values are based on **Goldilocks/VPA recommendations** and rounded to clean values following [resource management best practices](../docs/resource-management.md).
|
|
|
|
The `patch-resources` recipe configures resources for the following components:
|
|
|
|
- **CSI Components** (csi-attacher, csi-provisioner, csi-resizer, csi-snapshotter): Guaranteed QoS for stable CSI operations
|
|
- **Engine Image DaemonSet** (engine-image-ei-*): Guaranteed QoS
|
|
- **CSI Plugin DaemonSet** (longhorn-csi-plugin): 3 containers, Guaranteed QoS for critical CSI plugin
|
|
- **Driver Deployer** (longhorn-driver-deployer): Guaranteed QoS
|
|
- **Longhorn Manager DaemonSet** (longhorn-manager): Core component with Burstable QoS to allow CPU bursts during intensive storage operations. Includes 2 containers: main manager and pre-pull-share-manager-image
|
|
- **Longhorn UI** (longhorn-ui): Guaranteed QoS
|
|
|
|
For specific resource values, refer to the `patch-resources` recipe in [longhorn/justfile](justfile).
|
|
|
|
### Manual Resource Updates
|
|
|
|
If you need to update resource configurations:
|
|
|
|
1. **Edit the justfile:**
|
|
|
|
```bash
|
|
vim longhorn/justfile
|
|
# Modify the patch-resources recipe
|
|
```
|
|
|
|
2. **Apply changes:**
|
|
|
|
```bash
|
|
just longhorn::patch-resources
|
|
```
|
|
|
|
3. **Verify:**
|
|
|
|
```bash
|
|
kubectl get deployment <name> -n longhorn -o jsonpath='{.spec.template.spec.containers[0].resources}' | jq
|
|
```
|
|
|
|
### Future: When Helm Support is Added
|
|
|
|
If Longhorn adds Helm values support in future versions:
|
|
|
|
1. Move resource configurations from `patch-resources` recipe to `longhorn-values.yaml`
|
|
2. Remove or deprecate the `patch-resources` recipe
|
|
3. Update this documentation
|
|
|
|
Monitor these GitHub issues for updates:
|
|
|
|
- [#1502](https://github.com/longhorn/longhorn/issues/1502)
|
|
- [Discussion #8282](https://github.com/longhorn/longhorn/discussions/8282)
|
|
|
|
## OAuth2-Proxy Integration
|
|
|
|
Longhorn UI can be protected with OAuth2-Proxy for Keycloak authentication.
|
|
|
|
### Setup OAuth2-Proxy
|
|
|
|
```bash
|
|
just longhorn::oauth2-proxy-install
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Prompt for Longhorn hostname (FQDN)
|
|
2. Create Keycloak client
|
|
3. Deploy OAuth2-Proxy with IngressRoute
|
|
4. Apply resource limits to OAuth2-Proxy based on VPA recommendations
|
|
|
|
**Resource Configuration:**
|
|
|
|
OAuth2-Proxy resources are configured in the gomplate template ([oauth2-proxy/oauth2-proxy-deployment.gomplate.yaml](../oauth2-proxy/oauth2-proxy-deployment.gomplate.yaml)) with Guaranteed QoS based on Goldilocks/VPA recommendations.
|
|
|
|
### Access Longhorn UI
|
|
|
|
After setup, access the Longhorn UI at:
|
|
|
|
```text
|
|
https://<LONGHORN_HOST>
|
|
```
|
|
|
|
You'll be redirected to Keycloak for authentication.
|
|
|
|
### Remove OAuth2-Proxy
|
|
|
|
```bash
|
|
just longhorn::oauth2-proxy-uninstall
|
|
```
|
|
|
|
## References
|
|
|
|
- [Longhorn Documentation](https://longhorn.io/docs/)
|
|
- [Longhorn GitHub Repository](https://github.com/longhorn/longhorn)
|
|
- [Longhorn Helm Chart](https://github.com/longhorn/charts)
|
|
- [Resource Management Best Practices](../docs/resource-management.md)
|
|
- [GitHub Issue #1502 - Resource requests/limits support](https://github.com/longhorn/longhorn/issues/1502)
|