Documentación / Integraciones / AWS CLI

Usar AWS CLI con OtterStorage

Instala, configura y opera tus buckets de OtterStorage desde la terminal con AWS CLI v2.

OtterStorage es compatible con la API S3, por lo que puedes administrar tus buckets y objetos con la herramienta oficial aws sin instalar nada propietario. Solo necesitas apuntar el cliente a nuestro endpoint y usar las claves de acceso de tu bucket. En esta guía configurarás un perfil dedicado y recorrerás los comandos más habituales con ejemplos reales.

Requisitos previos

Las credenciales de tu bucket: access key y secret key (se generan por bucket desde el panel).
El endpoint S3 de OtterStorage: https://s3.otterstorage.io
Una región. En los ejemplos usamos eu-mad.

Si aún no tienes claves, consulta la documentación para crear un bucket y emitir tus credenciales.

Instalar AWS CLI v2

Recomendamos AWS CLI versión 2, que incluye mejoras de rendimiento y soporte completo para transferencias multiparte. Instálala según tu sistema operativo:

Linux (x86_64):

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

macOS:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Windows: descarga e instala el paquete MSI oficial, o usa el gestor de paquetes winget:

winget install -e --id Amazon.AWSCLI

Verifica la instalación. Debe mostrar una versión que empiece por aws-cli/2:

aws --version

Configurar un perfil "otter"

En lugar de modificar tu perfil por defecto, crea un perfil con nombre llamado otter. Así puedes mantener tus credenciales de AWS y de OtterStorage en paralelo sin conflictos:

aws configure --profile otter

Responde a las preguntas con tus datos:

AWS Access Key ID [None]: TU_ACCESS_KEY
AWS Secret Access Key [None]: TU_SECRET_KEY
Default region name [None]: eu-mad
Default output format [None]: json

Esto escribe las claves en ~/.aws/credentials y la región en ~/.aws/config, ambos bajo la sección [profile otter].

Indicar el endpoint de OtterStorage

El cliente apunta por defecto a los servidores de AWS, así que debes redirigirlo a OtterStorage. Tienes dos formas de hacerlo.

Opción A: pasar --endpoint-url en cada comando

Útil para pruebas puntuales. Añade el flag a cualquier comando:

aws --profile otter --endpoint-url https://s3.otterstorage.io s3 ls

Opción B: fijar endpoint_url en ~/.aws/config (recomendado)

AWS CLI v2 admite definir el endpoint en el archivo de configuración, de modo que no tengas que repetir el flag. Edita ~/.aws/config y deja la sección del perfil así:

[profile otter]
region = eu-mad
output = json
endpoint_url = https://s3.otterstorage.io

A partir de ahora basta con indicar el perfil:

aws --profile otter s3 ls

Si prefieres no escribir --profile en cada llamada, exporta la variable de entorno en tu sesión:

export AWS_PROFILE=otter

En el resto de la guía asumimos que el endpoint ya está configurado en el perfil; añade --endpoint-url https://s3.otterstorage.io manualmente si usas la Opción A.

Comandos de alto nivel: aws s3

La interfaz aws s3 ofrece comandos cómodos para el día a día. Recuerda que en OtterStorage no cobramos por peticiones ni por borrados, así que puedes listar y limpiar objetos sin preocuparte por el coste de las operaciones.

Crear un bucket (mb)

aws --profile otter s3 mb s3://mi-primer-bucket

Listar buckets y objetos (ls)

# Listar todos tus buckets
aws --profile otter s3 ls

# Listar el contenido de un bucket
aws --profile otter s3 ls s3://mi-primer-bucket

# Listar recursivamente con tamaños
aws --profile otter s3 ls s3://mi-primer-bucket --recursive --human-readable --summarize

Subir y descargar objetos (cp)

# Subir un archivo
aws --profile otter s3 cp ./informe.pdf s3://mi-primer-bucket/docs/informe.pdf

# Descargar un archivo
aws --profile otter s3 cp s3://mi-primer-bucket/docs/informe.pdf ./informe.pdf

# Subir una carpeta completa
aws --profile otter s3 cp ./assets s3://mi-primer-bucket/assets --recursive

Sincronizar directorios (sync)

sync copia solo los archivos nuevos o modificados, ideal para backups y despliegues:

# Subir cambios locales al bucket
aws --profile otter s3 sync ./sitio s3://mi-primer-bucket/sitio

# Sincronizar borrando en destino lo que ya no existe en origen
aws --profile otter s3 sync ./sitio s3://mi-primer-bucket/sitio --delete

Como no facturamos las peticiones ni las eliminaciones, ejecutar sync --delete de forma periódica no añade coste por operación.

Operaciones de bajo nivel: aws s3api

Cuando necesitas control fino (metadatos, versionado, object-lock), usa aws s3api, que expone las llamadas de la API S3 una a una.

Crear un bucket con create-bucket

aws --profile otter s3api create-bucket \
  --bucket mi-bucket-api \
  --create-bucket-configuration LocationConstraint=eu-mad

Subir un objeto con put-object

aws --profile otter s3api put-object \
  --bucket mi-bucket-api \
  --key docs/manual.pdf \
  --body ./manual.pdf \
  --content-type application/pdf

Listar objetos con list-objects-v2

# Listar por prefijo, limitando a 100 claves
aws --profile otter s3api list-objects-v2 \
  --bucket mi-bucket-api \
  --prefix docs/ \
  --max-keys 100

Subida multiparte

Para archivos grandes, AWS CLI divide la subida en partes y las transfiere en paralelo. Con los comandos de alto nivel (cp y sync) esto es automático: cuando el archivo supera el umbral configurado, el cliente realiza una subida multiparte sin que tengas que hacer nada.

Puedes ajustar el umbral y el tamaño de cada parte en tu configuración:

aws configure set s3.multipart_threshold 64MB --profile otter
aws configure set s3.multipart_chunksize 32MB --profile otter

Tras estos ajustes, una subida normal aprovechará el multiparte de forma transparente:

aws --profile otter s3 cp ./video-4k.mov s3://mi-primer-bucket/media/video-4k.mov

Si una subida multiparte se interrumpe, quedan partes incompletas almacenadas. Puedes listarlas y abortarlas con s3api; al no cobrar por peticiones ni borrados, esta limpieza no tiene coste de operaciones:

# Ver subidas multiparte pendientes
aws --profile otter s3api list-multipart-uploads --bucket mi-primer-bucket

# Abortar una subida concreta
aws --profile otter s3api abort-multipart-upload \
  --bucket mi-primer-bucket \
  --key media/video-4k.mov \
  --upload-id EL_UPLOAD_ID

URLs prefirmadas (presign)

Una URL prefirmada permite compartir un objeto privado durante un tiempo limitado sin exponer tus claves. Genérala con s3 presign:

# URL válida durante 3600 segundos (1 hora, valor por defecto)
aws --profile otter s3 presign s3://mi-primer-bucket/docs/informe.pdf

# URL válida durante 7 días (604800 segundos, máximo habitual)
aws --profile otter s3 presign s3://mi-primer-bucket/docs/informe.pdf --expires-in 604800

El comando devuelve una URL completa que cualquiera puede abrir en el navegador hasta que expire.

Versionado de objetos

El versionado conserva copias anteriores de cada objeto, lo que protege frente a sobrescrituras y borrados accidentales. Actívalo con s3api:

# Activar el versionado
aws --profile otter s3api put-bucket-versioning \
  --bucket mi-bucket-api \
  --versioning-configuration Status=Enabled

# Comprobar el estado
aws --profile otter s3api get-bucket-versioning --bucket mi-bucket-api

# Listar todas las versiones de los objetos
aws --profile otter s3api list-object-versions --bucket mi-bucket-api

Object Lock

Object Lock aplica un modelo de retención WORM (escribir una vez, leer muchas) que impide borrar o modificar un objeto antes de una fecha dada. El bucket debe crearse con Object Lock habilitado, lo que activa también el versionado:

# Crear el bucket con Object Lock habilitado
aws --profile otter s3api create-bucket \
  --bucket bucket-worm \
  --create-bucket-configuration LocationConstraint=eu-mad \
  --object-lock-enabled-for-bucket

Aplica una retención al subir o sobre un objeto existente. En modo COMPLIANCE ni siquiera el propietario puede eliminarlo antes de la fecha indicada:

aws --profile otter s3api put-object \
  --bucket bucket-worm \
  --key contratos/2026.pdf \
  --body ./2026.pdf \
  --object-lock-mode COMPLIANCE \
  --object-lock-retain-until-date 2027-06-11T00:00:00Z

Consulta la retención vigente de un objeto:

aws --profile otter s3api get-object-retention \
  --bucket bucket-worm \
  --key contratos/2026.pdf

Resumen

Instala AWS CLI v2 y crea un perfil otter con aws configure --profile otter.
Fija endpoint_url = https://s3.otterstorage.io en ~/.aws/config para no repetir --endpoint-url.
Usa aws s3 (mb, cp, sync, ls) para el día a día y aws s3api para control fino.
El multiparte es automático en archivos grandes; las URLs prefirmadas comparten objetos de forma temporal y segura.
Activa versionado y Object Lock vía s3api para proteger tus datos. Y recuerda: no cobramos por peticiones ni por borrados.

¿Necesitas más detalles sobre buckets, claves o regiones? Vuelve a la documentación.

¿Listo para probarlo?

Crea tu cuenta y obtén tus claves en minutos.

Hazte Founding Otter