configure-ebs.sh formats and mounts AWS EBS volumes for GitLab

configure-ebs.sh is a 234-line bash script, last touched in July 2024 and licensed Apache-2.0. Its main flow calls sudo, blkid, mkfs.xfs or mkfs.ext4, mount, and either systemctl or crontab. The code also references lsblk and jq in a volume-ID lookup function that the main flow does not call.

The script exists to solve a narrow, real problem: an EC2 instance running GitLab needs several dedicated EBS volumes mounted at specific paths — the registry, LFS objects, artifacts, uploads, Terraform state, CI secure files and backups. Doing that by hand means creating a filesystem, editing /etc/fstab without breaking it, mounting by UUID so reboots survive, and setting up periodic fstrim. This script automates all of it in one invocation.

What the flags do

Arguments are parsed into an associative array with defaults:

• --device — original device mapping, e.g. /dev/nvme1n1
• --volumeid — AWS volume ID (vol...)
• --label — a name for the volume
• --mount — target mount point (must be an absolute path)
• --fs — filesystem type, default xfs
• --fstrim — documented as enabling fstrim when set; the code actually enables it only when unset
• --size — documented in the README as capacity in GiB; the current script stores but does not use it

The parser accepts --help, -h or help to print usage; missing values and unknown non-long tokens exit with an error, while unrecognized long options are accepted but ignored.

How the work flows

Execution is a linear pipeline inside main(). After printing an ASCII banner, it parses arguments, then validates that at least one of --device or --volumeid, plus --label, --fs and --mount, is present, and that the mount path passes valid_path (must start with / and contain only alphanumerics, ., _, -, /). The main flow uses --device for creating the filesystem, looking up the UUID and mounting; a volume-ID lookup function exists but is never called, so passing --volumeid alone does not supply a usable device.

The filesystem step is simple: if the requested type starts with XFS it runs sudo mkfs.xfs, if it starts with EXT it runs sudo mkfs.ext4. The fstab work is careful — a timestamped backup is written to /root/fstab.YYYYMMDD_HHMM before anything changes, and patch_fstab first deletes any existing lines matching the volume's UUID or mount point, then appends:

UUID=<uuid> <mount> <fs> defaults,noatime,nofail 0 0

Mounting uses the device UUID from blkid, so it survives device-name changes across reboots. The script creates the mount directory and runs systemctl daemon-reload.

fstrim scheduling

When --fstrim is not set, the script installs a trim schedule for the new volume. On systems with systemd it writes two units — an fstrim-<label>.service that runs /sbin/fstrim <mount>, and a .timer on OnCalendar=daily with Persistent=true — then enables and starts the timer. Without systemd it falls back to appending 0 2 * * * /sbin/fstrim <mount> to crontab, only if that line is not already present.

One detail worth flagging: in the code the fstrim branch fires when the parameter is empty ([[ -z "${params[fstrim]}" ]]), so trimming is enabled by default rather than requiring --fstrim. The README describes --fstrim as "set to any value to enable," which reads the opposite way. Anyone relying on this should read the script's actual condition before assuming.

Getting started

A typical GitLab-oriented invocation (quoting the README's registry example) is:

./configure-ebs.sh --device "/dev/nvme1n1" \
                   --label "gitlab_registry" \
                   --mount "/var/opt/gitlab/gitlab-rails/shared/registry" \
                   --fs "xfs" \
                   --fstrim "on"

It uses sudo for several operations but calls mount UUID=... without sudo, so run it as root or as a user with the needed privileges. It is not idempotent in the sense of skipping already-configured volumes — rerunning on an existing mount point will remove the old fstab entry and replace it.

For anyone standing up GitLab (or any multi-volume EC2 workload) who wants boot-persistent mounts without hand-editing fstab, this is a compact manual option. It is one script, easy to audit line by line before running on production storage.