Qué es un bucket y cómo organizar archivos en él

En cualquier servicio de object storage, los archivos viven en un bucket. Antes de subir la primera foto o el primer PDF, creas (o recibes) un bucket y pones todo dentro de él.

Entender el bucket evita tres errores comunes: tratarlo como una carpeta, elegir un nombre que el servicio rechaza y mezclar archivos públicos y privados en el mismo lugar. Los ejemplos usan Amazon S3 como referencia, porque muchos otros servicios siguen el mismo modelo.

¿Qué es un bucket?#

Un bucket es el contenedor de objetos de un object storage. Cada objeto vive dentro de exactamente un bucket y se identifica por el par bucket + clave.

El bucket cumple dos funciones:

• Namespace: le da la dirección al objeto. En S3, el objeto fotos/gato.jpg del bucket mi-bucket en la región us-west-2 queda en https://mi-bucket.s3.us-west-2.amazonaws.com/fotos/gato.jpg.
• Punto de configuración: las reglas de acceso, la expiración de objetos, CORS, el versionado, los logs y la replicación se definen en el bucket (o en una parte de él), no archivo por archivo.

¿Un bucket es una carpeta?#

No, y la diferencia importa. Una carpeta de un sistema de archivos puede contener otras carpetas, tener permisos propios y moverse. El bucket está en la cima, no se puede anidar y no tiene jerarquía por debajo: el espacio de nombres de los objetos es plano.

Lo que parece una carpeta en el panel es un prefijo, el comienzo de la clave. El prefijo puede tener cualquier longitud, dentro del límite de 1.024 bytes de la clave en S3. La documentación de AWS lo dice claramente: los prefijos se parecen a directorios, pero no lo son. Para navegar por niveles, el listado usa un delimitador (normalmente /) y agrupa las claves que comparten prefijo.

¿Qué nombre puedo darle al bucket?#

Cada servicio define sus reglas. En S3, para buckets de uso general:

• de 3 a 63 caracteres;
• solo letras minúsculas, números, puntos (.) y guiones (-);
• empieza y termina con letra o número;
• sin dos puntos seguidos y sin formato de dirección IP (como 192.168.5.4);
• único entre todas las cuentas de la misma partición de AWS, en el namespace global.

En la práctica, esto significa:

• El nombre no cambia. Una vez creado, el nombre y la región son fijos. Planifícalo antes.
• No pongas secretos en el nombre. Aparece en las URLs de los objetos.
• Evita los puntos. Con puntos en el nombre, el certificado de la dirección virtual-hosted no funciona por HTTPS. AWS recomienda evitarlos, salvo en buckets que solo sirven un sitio estático.
• Un nombre borrado puede no volver. Después de que borras un bucket, otra cuenta puede tomar el mismo nombre. Si quieres conservarlo, vacía el bucket en lugar de borrarlo.
• Los nombres predecibles chocan. Si tu aplicación crea buckets por su cuenta, agrega un sufijo aleatorio (un UUID, por ejemplo). AWS también ofrece el namespace regional de la cuenta, en el que solo tu cuenta puede usar el nombre.

¿Cómo organizar archivos dentro de un bucket?#

Define un patrón de clave y mantenlo. Este formato suele envejecer bien:

{tipo}/{año}/{mes}/{id}-{nombre}.{ext}
avatares/2026/10/8f3a-gato.jpg
exportaciones/2026/10/informe-q3.csv

Buenas prácticas:

• Prefijo por tipo de contenido. Facilita listar, aplicar reglas de expiración y dar permiso solo a una parte.
• ID en el nombre del archivo. Evita que dos usuarios que suben foto.jpg sobrescriban el archivo del otro. En la base de datos, guarda solo la clave.
• Separa por política, no por gusto. Si un conjunto de archivos es público y otro privado, o uno expira en 7 días y el otro nunca, sepáralos en prefijos, si el servicio aplica reglas por prefijo, o en buckets, si no. Mira archivos públicos y privados.
• Nada de datos sensibles en la clave. Las claves aparecen en logs y URLs.

¿Cómo crear un bucket y listar archivos por prefijo?#

El ejemplo usa boto3, el SDK de AWS para Python (pip install boto3). El endpoint, la región y las credenciales vienen de variables de entorno.

import os
import boto3

region = os.environ.get("S3_REGION", "us-east-1")  # en AWS, la región del bucket

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ.get("S3_ENDPOINT"),  # omítelo para usar AWS
    region_name=region,
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
)

bucket = os.environ["S3_BUCKET"]

if os.environ.get("CREATE_BUCKET"):
    extra = {} if region == "us-east-1" else {  # us-east-1 no acepta LocationConstraint
        "CreateBucketConfiguration": {"LocationConstraint": region}
    }
    s3.create_bucket(Bucket=bucket, **extra)

for key in ["fotos/2026/gato.jpg", "fotos/2026/perro.jpg", "docs/contrato.pdf"]:
    s3.put_object(Bucket=bucket, Key=key, Body=b"contenido de ejemplo")

resp = s3.list_objects_v2(Bucket=bucket, Delimiter="/")  # solo el nivel raíz
for p in resp.get("CommonPrefixes", []):
    print("carpeta:", p["Prefix"])  # fotos/ y docs/

resp = s3.list_objects_v2(Bucket=bucket, Prefix="fotos/2026/")  # solo ese prefijo
for obj in resp.get("Contents", []):
    print(obj["Key"], obj["Size"])

Cada llamada de listado devuelve hasta 1.000 claves; para buckets grandes, usa get_paginator("list_objects_v2"). El create_bucket depende de una variable porque muchos servicios crean el bucket desde el panel y te entregan el nombre listo.

¿Cuándo crear más de un bucket?#

Un bucket es la frontera de las reglas. Crea otro cuando necesites:

• Visibilidad distinta: imágenes públicas por un lado, exportaciones privadas por el otro.
• Región distinta: por latencia o por exigencia legal. En S3, los objetos de un bucket no salen de su región a menos que los transfieras.
• Ciclos de vida distintos: logs que expiran en 30 días y archivos de clientes que se quedan para siempre.
• Entornos separados: desarrollo, staging y producción sin riesgo de borrar el dato equivocado.

Para el resto, los prefijos bastan. Evita crear y borrar buckets en el camino crítico de la aplicación: AWS recomienda hacerlo en una rutina de inicialización, no en cada petición.

¿Qué términos aparecen junto a bucket?#

• Objeto: el archivo más sus metadatos.
• Clave: el nombre único del objeto dentro del bucket.
• Prefijo: el comienzo de la clave, usado para simular carpetas.
• Región: dónde está físicamente el bucket.
• Política de bucket: la regla de quién puede hacer qué.
• Ciclo de vida: reglas de expiración, descritas en reglas de ciclo de vida de objetos.

Cómo hacerlo en Square Cloud#

El Blob Storage de Square Cloud es un object storage con API compatible con S3, así que aws-cli, rclone, boto3 y los SDKs de AWS funcionan apuntando a https://s3-blob.squarecloud.app (región auto) con las claves S3 de la pestaña "Acceso S3" del panel, como en el código de arriba. También puedes usar la API REST o el panel web.

En Blob, cada cuenta tiene tres buckets fijos: public, private y legacy (este último de solo lectura). No se crean buckets con nombre, así que deja CREATE_BUCKET sin valor en el ejemplo y usa uno de ellos.

La organización por prefijo funciona igual: las carpetas son prefijos de clave, y defines reglas por carpeta como visibilidad, expiración, caché, tamaño máximo, extensiones permitidas y limpieza automática. En cada objeto, controlas la expiración, el Cache-Control y si el archivo se descarga o se abre inline.

Cada archivo puede pesar hasta 10 GB, y el multipart solo es obligatorio por encima de 100 MB. Los archivos públicos salen por una CDN global en el edge. El Blob no cobra tarifa de salida ni de entrada, y todos los planes incluyen una cuota de 5 GB a 250 GB.

Conoce Blob Storage