Expand a Baremetal Deployment

The following procedure adds a server pool to an existing AIStor deployment running on baremetal infrastructure. Each pool expands the total available storage capacity of the cluster while maintaining the overall availability of the cluster.

All commands provided below use example values. Replace these values with those appropriate for your deployment.

Review the Prerequisites before starting this procedure.

Complete any planned hardware expansion prior to decommissioning older hardware pools.

1) Install AIStor on each node in the new server pool

Follow the instructions to install the appropriate AIStor Object Store package for your architecture and operating system on each node of the new pool.

MinIO strongly recommends using the RPM or DEB installation routes. The RPM and DEB packages automatically install AIStor to the necessary system paths and create a minio service for systemctl.

2) Add TLS/SSL certificates

AIStor Server enables Transport Layer Security (TLS) 1.2+ automatically upon detecting a valid x.509 certificate (.crt) and private key (.key) in the MinIO ${HOME}/.minio/certs directory.

For systemd-managed deployments, use the $HOME directory for the user which runs the AIStor Server process. The provided minio.service file runs the process as minio-user. ? The previous step includes instructions for creating this user with a home directory /home/minio-user.

  • Place TLS certificates into /home/minio-user/.minio/certs on each host.
  • If any AIStor Server or client uses certificates signed by an unknown Certificate Authority (self-signed or internal CA), you must place the CA certs in the /home/minio-user/.minio/certs/CAs on all AIStor Server hosts in the deployment. AIStor Server rejects invalid certificates (untrusted, expired, or malformed).

If the minio.service file specifies a different user account, use the $HOME directory for that account. Alternatively, specify a custom certificate directory using the minio server --certs-dir commandline argument. Modify the MINIO_OPTS variable in /etc/default/minio to set this option. The systemd user which runs the AIStor Server process must have read and listing permissions for the specified directory.

For more specific guidance on configuring MinIO for TLS, including multi-domain support via Server Name Indication (SNI), see Network Encryption (TLS). You can optionally skip this step to deploy without TLS enabled. MinIO strongly recommends against non-TLS deployments outside of early development.

3) Create the systemd service file

The .deb or .rpm packages install the following systemd service file to /usr/lib/systemd/system/minio.service. For binary installations, create this file manually on all AIStor Server hosts.

File placement

systemd checks the /etc/systemd/... path before checking the /usr/lib/systemd/... path and uses the first file it finds. To avoid conflicting or unexpected configuration options, check that the file only exists at the /usr/lib/systemd/system/minio.service path.

Refer to the man page for systemd.unit for details on the file path search order.

[Unit]
Description=MinIO
Documentation=https://min.io/docs/minio/linux/index.html
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minio

[Service]
WorkingDirectory=/usr/local

User=minio-user
Group=minio-user
ProtectProc=invisible

EnvironmentFile=-/etc/default/minio
ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo \"Variable MINIO_VOLUMES not set in /etc/default/minio\"; exit 1; fi"
ExecStart=/usr/local/bin/Object Store $MINIO_OPTS $MINIO_VOLUMES

# AIStor Server supports Type=notify (https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=)
# This may improve systemctl setups where other services use `After=minio.server`
# Uncomment the following line to enable the functionality
# Type=notify

# Let systemd restart this service always
Restart=always

# Specifies the maximum file descriptor number that can be opened by this process
LimitNOFILE=65536

# Specifies the maximum number of threads this process can create
TasksMax=infinity

# Disable timeout logic and wait until process is stopped
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

# Built for ${project.name}-${project.version} (${project.name})

The minio.service file runs as the minio-user User and Group by default. You can create the user and group using the groupadd and useradd commands. The following example creates the user, group, and sets permissions to access the folder paths intended for use by AIStor Server. These commands typically require root (sudo) permissions.

groupadd -r minio-user
useradd -M -r -g minio-user minio-user
chown minio-user:minio-user /mnt/disk1 /mnt/disk2 /mnt/disk3 /mnt/disk4

The specified drive paths are provided as an example. Change them to match the path to those drives intended for use by AIStor Server.

Alternatively, change the User and Group values to another user and group on the system host with the necessary access and permissions.

To update deployments managed using systemctl, see Update systemctl-Managed AIStor Deployments.

4) Create the service environment file

Create an environment file at /etc/default/minio. The AIStor Server uses this file as the source of all environment variables used by AIStor Server and the minio.service file.

The following examples assumes that:

  • The deployment has a single server pool consisting of four Object Store hosts with sequential hostnames.

    minio1.example.com   minio3.example.com
    minio2.example.com   minio4.example.com
    

    Each host has 4 locally attached drives with sequential mount points:

    /mnt/disk1/minio   /mnt/disk3/minio
    /mnt/disk2/minio   /mnt/disk4/minio
    
  • The new server pool consists of eight new MinIO hosts with sequential hostnames:

    minio5.example.com   minio9.example.com
    minio6.example.com   minio10.example.com
    minio7.example.com   minio11.example.com
    minio8.example.com   minio12.example.com
    
  • All hosts have eight locally-attached drives with sequential mount-points:

    /mnt/disk1/minio  /mnt/disk5/minio
    /mnt/disk2/minio  /mnt/disk6/minio
    /mnt/disk3/minio  /mnt/disk7/minio
    /mnt/disk4/minio  /mnt/disk8/minio
    
  • The deployment has a load balancer running at https://aistor.example.net that manages connections across all MinIO hosts. The load balancer should not be routing requests to the new hosts at this step, but should have the necessary configuration updates planned.

Modify the example to reflect your deployment topology:

# Set the hosts and volumes MinIO uses at startup
# The command uses MinIO expansion notation {x...y} to denote a
# sequential series.
#
# The following example starts the Object Store with two server pools.
#
# The space delimiter indicates a seperate server pool
#
# The second set of hostnames and volumes is the newly added pool.
# The pool has sufficient stripe size to meet the existing erasure code
# parity of the deployment (2 x EC:4)
#
# The command includes the port on which the MinIO servers listen for each
# server pool.

MINIO_VOLUMES="https://minio{1...4}.example.net:9000/mnt/disk{1...4}/minio https://minio{5...12}.example.net:9000/mnt/disk{1...8}/minio"

# Set all Object Store options
#
# The following explicitly sets the MinIO Console listen address to
# port 9001 on all network interfaces. The default behavior is dynamic
# port selection.

MINIO_OPTS="--console-address :9001"

# Set the root username. This user has unrestricted permissions to
# perform S3 and administrative API operations on any resource in the
# deployment.
#
# Defer to your organizations requirements for superadmin user name.

MINIO_ROOT_USER=minioadmin

# Set the root password
#
# Use a long, random, unique string that meets your organizations
# requirements for passwords.

MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME

You may specify other environment variables or server commandline options as required by your deployment. All AIStor nodes in the deployment should include the same environment variables with the matching values.

5) Restart the AIStor deployment with expanded configuration

Issue the following commands on each node simultaneously in the deployment to restart the AIStor service:

sudo systemctl restart minio.service

Use the following commands to confirm the service is online and functional:

sudo systemctl status minio.service
journalctl -f -u minio.service

AIStor may log an increased number of non-critical warnings while the server processes connect and synchronize. These warnings are typically transient and should resolve as the deployment comes online.

MinIO strongly recommends restarting all AIStor Server processes in a deployment simultaneously. AIStor Server operations are atomic and strictly consistent. As such the restart procedure is non-disruptive to applications and ongoing operations.

Do not perform “rolling” (that is, one node at a time) restarts.

Next steps

  • Update any load balancers, reverse proxies, or other network control planes to route client requests to the new hosts in the AIStor distributed deployment. While AIStor Server automatically manages routing internally, having the control planes handle initial connection management may reduce network hops and improve efficiency.
All rights reserved 2024-Present, MinIO, Inc.