# GlusterFS

> Scalable network filesystem.

- Category: Storage & Backup
- Difficulty: advanced
- Components: glusterfs
- Tags: glusterfs, distributed, filesystem, scale
- Source: https://docker.recipes/storage/glusterfs

## Overview

GlusterFS is an open-source, distributed file system designed to scale to petabytes and handle thousands of clients. Originally developed by Gluster Inc. (later acquired by Red Hat), GlusterFS aggregates storage from multiple servers into a single global namespace, providing high availability and fault tolerance through replication and distribution mechanisms. Unlike traditional network-attached storage solutions, GlusterFS operates without metadata servers, using elastic hashing algorithms to locate files across the cluster. This Docker configuration establishes a two-node GlusterFS cluster using the official gluster-centos containers, each running as privileged containers to access low-level storage operations. The setup creates a replicated volume that maintains copies of data across both nodes, ensuring data redundancy and availability even if one node fails. The configuration isolates GlusterFS traffic on a dedicated Docker network while providing persistent storage for configuration files, logs, and the actual data being served. This stack is ideal for organizations requiring scalable, fault-tolerant storage that can grow horizontally by adding more nodes, making it particularly valuable for cloud-native applications, container orchestration platforms, and distributed computing environments where traditional shared storage becomes a bottleneck.

## Features

- Elastic hash algorithm eliminates metadata servers and single points of failure
- Replica 2 configuration ensures data redundancy across both GlusterFS nodes
- FUSE-based client mounting allows POSIX-compliant file system access
- Self-healing capabilities automatically recover corrupted or missing files
- Volume management through native GlusterFS CLI commands for creation and administration
- Brick-level storage abstraction enables flexible underlying storage configurations
- Online volume operations support adding and removing storage without downtime
- Distributed hash table architecture provides linear scalability by adding nodes

## Use cases

- Container persistent storage for Kubernetes and Docker Swarm clusters
- Distributed file sharing for development teams working across multiple servers
- Media streaming platforms requiring high-throughput distributed storage
- Backup storage systems with built-in replication across geographic locations
- Web content delivery networks needing synchronized file distribution
- Scientific computing clusters requiring shared datasets across compute nodes
- Home lab environments testing distributed storage before production deployment

## Prerequisites

- Docker host with privileged container support and sufficient storage space
- At least 4GB RAM per node for optimal GlusterFS performance
- Understanding of GlusterFS volume types (distribute, replica, stripe)
- Network connectivity between containers for brick synchronization
- Basic knowledge of FUSE filesystem mounting and troubleshooting
- Familiarity with GlusterFS CLI commands for volume management

## docker-compose.yml

```yaml
services:
  gluster1:
    image: gluster/gluster-centos:latest
    container_name: gluster1
    privileged: true
    hostname: gluster1
    volumes:
      - gluster1_data:/data
      - gluster1_etc:/etc/glusterfs
      - gluster1_lib:/var/lib/glusterd
      - gluster1_log:/var/log/glusterfs
    networks:
      - gluster

  gluster2:
    image: gluster/gluster-centos:latest
    container_name: gluster2
    privileged: true
    hostname: gluster2
    volumes:
      - gluster2_data:/data
      - gluster2_etc:/etc/glusterfs
      - gluster2_lib:/var/lib/glusterd
      - gluster2_log:/var/log/glusterfs
    networks:
      - gluster

volumes:
  gluster1_data:
  gluster1_etc:
  gluster1_lib:
  gluster1_log:
  gluster2_data:
  gluster2_etc:
  gluster2_lib:
  gluster2_log:

networks:
  gluster:
    driver: bridge
```

## .env

```bash
# Configure volume after containers start
```

## Usage notes

- Create volume: gluster volume create vol1 replica 2 gluster1:/data gluster2:/data
- Start volume: gluster volume start vol1
- Mount on client: mount -t glusterfs gluster1:/vol1 /mnt

## Troubleshooting

- Transport endpoint is not connected: Check if glusterd service is running and volumes are started with 'gluster volume status'
- Peer probe failed: Verify container hostnames resolve correctly and use 'gluster peer probe <hostname>' to establish connections
- Volume creation fails with brick path error: Ensure /data directory exists and has proper permissions within containers
- Split-brain condition detected: Use 'gluster volume heal <volume> info split-brain' to identify and resolve conflicting files
- Mount operation hangs: Verify glusterfs-fuse is installed on client and check network connectivity to GlusterFS nodes
- Performance degradation on writes: Check replica count and network latency between nodes, consider tuning performance options

