Hands-on Lab

Migrar MinIO a Garage paso a paso con rclone

21 de octubre de 2026 3 min 1

0 / 7

Chuleta

¿Te ha servido? No te pierdas el próximo lab

El vídeo tiene subtítulos y transcripción. Todo lo que se ve está escrito, paso a paso, más abajo. Chuleta con todos los comandos

0:00 / 0:00

Creamos un proyecto de Compose en /srv/minio con un MinIO de prueba: la imagen cgr.dev/chainguard/minio:latest, que es la única etiqueta del plan gratuito de Chainguard. Antes damos la carpeta data al usuario 65532 con chown, porque la imagen no corre como root, y generamos la contraseña con openssl dentro del contenedor.

mkdir -p /srv/minio/data && chown 65532:65532 /srv/minio/data && cd /srv/minio
printf 'MINIO_ROOT_USER=minioadmin\nMINIO_ROOT_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env
cat > docker-compose.yml <<'EOF'
services:
  minio:
    image: cgr.dev/chainguard/minio:latest
    command: ["server", "/data"]
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - "9000:9000"
    volumes:
      - ./data:/data
EOF
docker compose up -d --quiet-pull minio

Lo hice yo

Esperamos a que el endpoint /minio/health/live responda y comprobamos el resultado: HTTP 200. stat confirma que la carpeta data es del usuario 65532, el que usa la imagen de Chainguard.

for i in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9000/minio/health/live)" = 200 ] && break; sleep 2; done
echo "minio health: HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9000/minio/health/live)"
stat -c 'data owner uid: %u' /srv/minio/data

Qué demuestra

minio health: HTTP 200 el endpoint de salud de MinIO responde 200 Objetivo · tienes un origen en marcha del que copiar los datos
data owner uid: 65532 la carpeta de datos pertenece al usuario 65532 Objetivo · evitas el error file access denied de la imagen de Chainguard

Generamos 200 documentos JSON y 100 ficheros aleatorios de 4 a 32 KB, creamos el bucket app-data y los subimos con mc mirror desde la imagen cgr.dev/chainguard/minio-client. Después creamos el usuario appminio01, con un secreto de openssl, y le asignamos la política readwrite: hace el papel de las credenciales de tu aplicación.

mkdir -p /srv/seed/docs /srv/seed/bin
for i in $(seq 1 200); do printf '{"id":%d,"title":"doc %d"}\n' $i $i > /srv/seed/docs/doc-$i.json; done
for i in $(seq 1 100); do head -c $((4096 * (1 + i % 8))) /dev/urandom > /srv/seed/bin/blob-$i.bin; done
cd /srv/minio && set -a && . ./.env && set +a
printf 'APP_KEY=appminio01\nAPP_SECRET=%s\n' "$(openssl rand -hex 20)" > app.env && . ./app.env
mc() { docker run --rm --network minio_default -e MC_HOST_old="http://$MINIO_ROOT_USER:$MINIO_ROOT_PASSWORD@minio:9000" -v /srv/seed:/seed:ro cgr.dev/chainguard/minio-client:latest "$@"; }
docker pull -q cgr.dev/chainguard/minio-client:latest >/dev/null
mc mb old/app-data && mc mirror /seed old/app-data | tail -n 4
mc admin user add old "$APP_KEY" "$APP_SECRET" && mc admin policy attach old readwrite --user "$APP_KEY"

Lo hice yo

Contamos el bucket con mc du, conectando con la clave appminio01 en lugar de la del administrador: app-data tiene 300 objetos y la aplicación los ve.

cd /srv/minio && . ./app.env
docker run --rm --network minio_default -e MC_HOST_app="http://$APP_KEY:$APP_SECRET@minio:9000" cgr.dev/chainguard/minio-client:latest du app/app-data

Qué demuestra

300 objects mc du cuenta 300 objetos en app-data Objetivo · conoces la cifra exacta que tiene que llegar a Garage
la consulta se hizo con la clave appminio01, no con la del administrador Objetivo · sabes que esa clave funciona en MinIO antes de llevarla a Garage

Escribimos el garage.toml de la guía: metadatos LMDB y datos en /var/lib/garage, replication_factor = 1 y s3_region = "us-east-1", la región que ya usan los clientes de MinIO. Los dos secretos salen de openssl al .env, y el servicio garage arranca con dxflrs/garage:v2.4.1 y --single-node, que crea la distribución del nodo sin pasos manuales.

mkdir -p /srv/minio/garage/meta /srv/minio/garage/data && cd /srv/minio
cat > garage.toml <<'EOF'
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "us-east-1"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
EOF
cat >> .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -base64 32)
EOF
cat >> docker-compose.yml <<'EOF'
  garage:
    image: dxflrs/garage:v2.4.1
    command: ["/garage", "server", "--single-node"]
    restart: unless-stopped
    environment:
      GARAGE_RPC_SECRET: ${GARAGE_RPC_SECRET}
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
    ports:
      - "3900:3900"
      - "3902:3902"
      - "127.0.0.1:3903:3903"
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./garage/meta:/var/lib/garage/meta
      - ./garage/data:/var/lib/garage/data
EOF
docker compose up -d --quiet-pull garage

Lo hice yo

Esperamos a que garage health informe de un clúster sano. El nodo único está en marcha y las 256 particiones tienen quórum, así que no hace falta asignar la distribución a mano con garage layout.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
for i in $(seq 1 60); do garage health 2>/dev/null | grep -qE 'Cluster health: +HEALTHY' && break; sleep 2; done
garage health

Qué demuestra

HEALTHY garage health informa de Cluster health: HEALTHY Objetivo · Garage acepta escrituras antes de copiar nada
Partitions with quorum: 256 las 256 particiones tienen quórum Objetivo · confirmas que --single-node ya creó la distribución del clúster

Garage no tiene usuario raíz: cada clave recibe permisos bucket a bucket. Creamos la clave migracion, guardamos su secreto en garage-key.txt sin mostrarlo, creamos el bucket app-data con el mismo nombre que en MinIO y le damos --read, --write y --owner.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage key create migracion > garage-key.txt && grep -E 'Key ID|Key name' garage-key.txt
garage bucket create app-data >/dev/null
garage bucket allow --read --write --owner app-data --key migracion >/dev/null

Lo hice yo

garage bucket info confirma el alias global app-data, 0 objetos todavía y la clave migracion con permisos RWO: lectura, escritura y propietario.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage bucket info app-data | grep -E 'Global alias|Objects|Permissions|RWO'

Qué demuestra

RWO la clave migracion tiene lectura, escritura y propietario en app-data Objetivo · rclone podrá escribir en el bucket con esa clave
app-data el bucket se llama app-data, igual que en MinIO Objetivo · las rutas de los objetos no cambian al migrar

rclone.conf declara minio con provider = Minio y garage con provider = Other, region = us-east-1 y force_path_style = true, rellenando las claves desde .env y garage-key.txt. rclone/rclone:1.75.1 se conecta a la red minio_default y sincroniza app-data; --metadata conserva las cabeceras y --fast-list reduce las llamadas de listado.

cd /srv/minio && set -a && . ./.env && set +a
cat > rclone.conf <<EOF
[minio]
type = s3
provider = Minio
access_key_id = $MINIO_ROOT_USER
secret_access_key = $MINIO_ROOT_PASSWORD
endpoint = http://minio:9000

[garage]
type = s3
provider = Other
access_key_id = $(awk '/Key ID/ {print $3}' garage-key.txt)
secret_access_key = $(awk '/Secret key/ {print $3}' garage-key.txt)
region = us-east-1
endpoint = http://garage:3900
force_path_style = true
EOF
docker pull -q rclone/rclone:1.75.1 >/dev/null
docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 sync minio:app-data garage:app-data --metadata --fast-list --transfers 8 --checkers 16 -v 2>&1 | grep -v 'Copied (new)'

Lo hice yo

rclone check con --download descarga cada objeto de MinIO y de Garage y compara el contenido, no solo el tamaño o el ETag. Termina con 0 diferencias y 300 ficheros coincidentes: la copia está completa.

cd /srv/minio && docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 check minio:app-data garage:app-data --download --fast-list --checkers 16

Qué demuestra

0 differences found rclone no encontró ningún objeto distinto ni ausente entre MinIO y Garage Objetivo · puedes apagar MinIO sabiendo que Garage tiene los mismos datos
300 matching files los 300 objetos coinciden byte a byte Objetivo · la cifra cuadra con los 300 objetos que contamos en MinIO

Paramos MinIO con docker compose stop, sin borrar sus datos. Después, garage key import --yes acepta la clave appminio01 aunque no empiece por GK: cumple los mínimos de 8 caracteres de identificador y 16 de secreto. Por último, garage bucket allow le da lectura y escritura en app-data.

cd /srv/minio && . ./app.env && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
docker compose stop minio
garage key import --yes -n app-antigua "$APP_KEY" "$APP_SECRET" | grep -E 'Key ID|Key name'
garage bucket allow --read --write app-data --key app-antigua | grep app-antigua

Lo hice yo

docker compose ps confirma que MinIO está parado. Con la clave appminio01 apuntando a garage:3900, mc du cuenta los 300 objetos y mc cat lee un documento: una aplicación solo tiene que cambiar la dirección.

cd /srv/minio && . ./app.env
docker compose ps -a minio --format '{{.Service}}: {{.State}}'
mc() { docker run --rm --network minio_default -e MC_HOST_app="http://$APP_KEY:$APP_SECRET@garage:3900" cgr.dev/chainguard/minio-client:latest "$@"; }
mc du app/app-data && mc cat app/app-data/docs/doc-7.json

Qué demuestra

minio: exited el contenedor de MinIO está parado Objetivo · sabes que las lecturas siguientes no pueden venir de MinIO
300 objects la clave de MinIO ve los 300 objetos en Garage Objetivo · tus aplicaciones siguen funcionando el día del cambio sin tocar sus credenciales
"title":"doc 7" mc cat devuelve el contenido de doc-7.json desde Garage Objetivo · compruebas una lectura real, no solo un listado

Borramos el proyecto con docker compose down -v, que quita los contenedores de MinIO y Garage y la red minio_default. Después borramos /srv/minio y /srv/seed, con los datos, las claves y rclone.conf.

cd /srv/minio && docker compose down -v && cd / && rm -rf /srv/minio /srv/seed

Lo hice yo

Contamos lo que queda: 0 contenedores, 0 redes minio_default y 0 ficheros en /srv. La máquina queda como al empezar.

echo "containers left: $(docker ps -aq | wc -l)"; echo "networks left: $(docker network ls -q --filter name=minio_default | wc -l)"; ls -A /srv | wc -l | sed 's/^/files left in \/srv: /'

Qué demuestra

containers left: 0 no queda ningún contenedor Objetivo · dejas la máquina como estaba antes del lab

1 vista

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

Transcripción del vídeo

0:00 De MinIO a Garage, con 0 diferencias.
0:05 Levantamos el MinIO de partida con la imagen de Chainguard, porque minio/minio
0:10 ya no se descarga de Docker Hub.
0:12 La imagen de Chainguard ejecuta MinIO con el usuario 65532, así
0:19 que la carpeta de datos tiene que ser suya.
0:22 Pasamos un bucket de MinIO a Garage y demostramos que no falta ni un objeto.
0:28 Garage es un servidor S3 ligero, escrito en Rust, que sustituye a MinIO para
0:34 guardar ficheros y copias.
0:36 MinIO con datos, Garage al lado, copia con rclone, verificación y cambio de clave.
0:43 Lo comprobamos:
0:44 el endpoint de salud de MinIO responde 200 y la carpeta de datos pertenece al usuario
0:50 65532.
0:54 Cargamos 300 objetos en el bucket app-data con mc y creamos la clave que usaría una
0:59 aplicación.
1:01 Lo comprobamos con la clave de la aplicación:
1:04 el bucket app-data tiene 300 objetos en MinIO.
1:10 Con --single-node, Garage crea solo la distribución del clúster en el primer
1:14 arranque.
1:16 Añadimos Garage v2.4.1 al mismo proyecto de Compose, con un nodo único y la
1:21 región us-east-1.
1:24 Lo comprobamos con garage health:
1:26 el clúster está HEALTHY y las 256 particiones tienen quórum.
1:34 Creamos la clave migracion y el bucket app-data, y le damos permisos de lectura,
1:39 escritura y propietario.
1:42 Lo comprobamos:
1:43 app-data existe, está vacío y la clave migracion tiene permisos RWO.
1:52 rclone lee de MinIO y escribe en Garage por la red de Compose, sin pasar por el
1:57 disco local.
1:59 Escribimos rclone.conf con los dos extremos y copiamos con rclone sync:
2:05 300 de 300 transferidos.
2:08 Lo verificamos con rclone check descargando los dos lados:
2:11 0 diferencias y 300 ficheros coincidentes.
2:17 Paramos MinIO e importamos en Garage la clave de la aplicación, para que siga
2:22 funcionando sin cambiar sus credenciales.
2:26 Lo comprobamos:
2:27 con MinIO parado, la misma clave lee los 300 objetos desde Garage en el puerto
2:33 3900.
2:36 Limpiamos:
2:37 docker compose down borra los dos contenedores y la red, y quitamos las
2:42 carpetas del lab.
2:44 Lo comprobamos:
2:45 no quedan contenedores, ni la red, ni ficheros del lab.

Qué hace este laboratorio

Este lab reproduce en un entorno desechable la guía para migrar de MinIO a Garage con Docker. Partimos de un MinIO con el bucket app-data y 300 objetos, levantamos Garage v2.4.1 en el mismo proyecto de Compose, copiamos con rclone 1.75.1 y comprobamos el resultado con rclone check --download: 0 diferencias y 300 ficheros coincidentes.

El MinIO de partida usa cgr.dev/chainguard/minio, porque minio/minio ya no se descarga de Docker Hub. Si te has topado con ese error, la guía de pull access denied for minio/minio explica las alternativas. La imagen de Chainguard corre con el usuario 65532 y solo publica latest en su plan gratuito.

Cómo se configura Garage para la migración

El garage.toml del lab sigue la guía de inicio de Garage con dos cambios: la región us-east-1, que es la que ya usan los clientes de MinIO, y los datos en /var/lib/garage. Los secretos se generan con openssl en un .env, como en el lab de gestión de secretos en Docker. La opción --single-node crea la distribución del clúster en el primer arranque, así que garage health ya muestra el clúster sano.

Copia, verificación y cambio de clave

rclone copia de un servidor S3 a otro por la red de Compose, con la plantilla provider = Other de la documentación de clientes de Garage. La verificación con rclone check y --download compara el contenido de cada objeto, no solo su ETag. Al final paramos MinIO e importamos en Garage la clave de la aplicación con garage key import --yes: la misma clave lee los 300 objetos desde el puerto 3900.

Garage no tiene versionado, bloqueo de objetos ni políticas de bucket; la guía escrita detalla qué se pierde y cuándo no te conviene. Si prefieres conservar esas funciones, mira la migración de MinIO a RustFS. Y antes de cualquier migración, guarda una copia de los datos como en el lab de copias de seguridad de volúmenes Docker.

Preguntas frecuentes

¿Hace falta configurar la distribución del clúster en Garage v2.4.1?

No con un solo nodo. Desde la v2.3.0, garage server –single-node crea la distribución en el primer arranque y la conserva en los siguientes. En el lab, garage health muestra el clúster HEALTHY y las 256 particiones con quórum sin ejecutar garage layout.

¿Por qué usar rclone check con –download?

Porque sin –download rclone compara tamaño y suma MD5, y los objetos subidos por partes tienen un ETag que no es el MD5 del contenido. Con –download descarga los dos lados y compara los bytes; en el lab termina con 0 diferencias y 300 ficheros coincidentes.

¿Pueden mis aplicaciones seguir usando las claves de MinIO en Garage?

Sí, con garage key import –yes, siempre que el identificador tenga al menos 8 caracteres y el secreto al menos 16. Después concede permisos con garage bucket allow. Úsalo como puente para el día del cambio y rota esas claves más adelante.

¿Qué región S3 debo poner en Garage al migrar desde MinIO?

La que ya usan tus clientes. MinIO sin región configurada acepta casi cualquiera, pero Garage solo acepta la de s3_region. Este lab usa us-east-1 en garage.toml y en rclone.conf para que coincidan.

Chuleta

mkdir -p /srv/minio/data && chown 65532:65532 /srv/minio/data && cd /srv/minio
printf 'MINIO_ROOT_USER=minioadmin\nMINIO_ROOT_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env
cat > docker-compose.yml <<'EOF'
services:
  minio:
    image: cgr.dev/chainguard/minio:latest
    command: ["server", "/data"]
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - "9000:9000"
    volumes:
      - ./data:/data
EOF
docker compose up -d --quiet-pull minio

mkdir -p /srv/seed/docs /srv/seed/bin
for i in $(seq 1 200); do printf '{"id":%d,"title":"doc %d"}\n' $i $i > /srv/seed/docs/doc-$i.json; done
for i in $(seq 1 100); do head -c $((4096 * (1 + i % 8))) /dev/urandom > /srv/seed/bin/blob-$i.bin; done
cd /srv/minio && set -a && . ./.env && set +a
printf 'APP_KEY=appminio01\nAPP_SECRET=%s\n' "$(openssl rand -hex 20)" > app.env && . ./app.env
mc() { docker run --rm --network minio_default -e MC_HOST_old="http://$MINIO_ROOT_USER:$MINIO_ROOT_PASSWORD@minio:9000" -v /srv/seed:/seed:ro cgr.dev/chainguard/minio-client:latest "$@"; }
docker pull -q cgr.dev/chainguard/minio-client:latest >/dev/null
mc mb old/app-data && mc mirror /seed old/app-data | tail -n 4
mc admin user add old "$APP_KEY" "$APP_SECRET" && mc admin policy attach old readwrite --user "$APP_KEY"

mkdir -p /srv/minio/garage/meta /srv/minio/garage/data && cd /srv/minio
cat > garage.toml <<'EOF'
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "us-east-1"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
EOF
cat >> .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -base64 32)
EOF
cat >> docker-compose.yml <<'EOF'
  garage:
    image: dxflrs/garage:v2.4.1
    command: ["/garage", "server", "--single-node"]
    restart: unless-stopped
    environment:
      GARAGE_RPC_SECRET: ${GARAGE_RPC_SECRET}
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
    ports:
      - "3900:3900"
      - "3902:3902"
      - "127.0.0.1:3903:3903"
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./garage/meta:/var/lib/garage/meta
      - ./garage/data:/var/lib/garage/data
EOF
docker compose up -d --quiet-pull garage

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage key create migracion > garage-key.txt && grep -E 'Key ID|Key name' garage-key.txt
garage bucket create app-data >/dev/null
garage bucket allow --read --write --owner app-data --key migracion >/dev/null

cd /srv/minio && set -a && . ./.env && set +a
cat > rclone.conf <<EOF
[minio]
type = s3
provider = Minio
access_key_id = $MINIO_ROOT_USER
secret_access_key = $MINIO_ROOT_PASSWORD
endpoint = http://minio:9000

[garage]
type = s3
provider = Other
access_key_id = $(awk '/Key ID/ {print $3}' garage-key.txt)
secret_access_key = $(awk '/Secret key/ {print $3}' garage-key.txt)
region = us-east-1
endpoint = http://garage:3900
force_path_style = true
EOF
docker pull -q rclone/rclone:1.75.1 >/dev/null
docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 sync minio:app-data garage:app-data --metadata --fast-list --transfers 8 --checkers 16 -v 2>&1 | grep -v 'Copied (new)'

cd /srv/minio && . ./app.env && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
docker compose stop minio
garage key import --yes -n app-antigua "$APP_KEY" "$APP_SECRET" | grep -E 'Key ID|Key name'
garage bucket allow --read --write app-data --key app-antigua | grep app-antigua

cd /srv/minio && docker compose down -v && cd / && rm -rf /srv/minio /srv/seed

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

Qué hace este laboratorio

Cómo se configura Garage para la migración

Copia, verificación y cambio de clave

Preguntas frecuentes

¿Hace falta configurar la distribución del clúster en Garage v2.4.1?

¿Por qué usar rclone check con –download?

¿Pueden mis aplicaciones seguir usando las claves de MinIO en Garage?

¿Qué región S3 debo poner en Garage al migrar desde MinIO?

Chuleta