Unidad 4.2: Integración de Object Storage

Introducción

TaskBoard permite a los usuarios adjuntar archivos a las tareas: capturas de pantalla, PDF, maquetas de diseño y, ocasionalmente, videos de varios gigabytes. No desea que esos bytes fluyan a través de su proceso de API. Consumen memoria, bloquean los hilos de trabajo y convierten una API sin estado en un cuello de botella. La solución es IONOS Cloud Object Storage con URLs prefirmadas: el navegador se comunica directamente con Object Storage, y su API solo maneja pequeños registros de metadatos.

En esta unidad, conectará la API de TaskBoard con Object Storage a través de la API compatible con S3 utilizando boto3. Lo más importante que debe comprender desde el principio es que Object Storage no utiliza su token de portador de IONOS CLOUD. Se autentica con un par separado de Access Key y Secret Key, exactamente como AWS S3. Configurará el cliente, generará URLs prefirmadas para carga y descarga, manejará archivos grandes con carga multipartita y aplicará reglas de ciclo de vida para que las cargas abandonadas no acumulen costos de forma indefinida.

1. Autenticación y conexión con boto3

Object Storage expone una superficie de API AWS S3 v2, por lo que los SDK estándar de AWS funcionan con él. Lo que cambia es el punto de acceso y las credenciales. Debe pasar un endpoint_url explícito (el SDK predeterminado es AWS, no IONOS CLOUD) y un par de Access Key y Secret Key. Estas claves no son su token de portador de la API de Cloud ni un rol de IAM. Se generan por separado y autentican cada solicitud S3 mediante AWS Signature.

Object Storage autentica a los usuarios con un par de claves: una Access Key y una Secret Key. Una clave debe generarse manualmente, ya sea en el DCD bajo Credenciales y gestión de Object Storage o a través de la API de gestión de Object Storage. La longitud actual de la Access Key es de 92 caracteres y la longitud de la Secret Key es de 64 caracteres, por lo que no debe codificar de forma fija suposiciones sobre el ancho de campo de los formatos anteriores de 20/40 caracteres. Cada usuario puede tener hasta 5 claves de acceso.

1.1 Creación del cliente S3

Antes de escribir cualquier código de cliente, fije su versión de boto3: boto3 1.36.0 y posteriores hacen que todas las llamadas a PutObject contra IONOS CLOUD Object Storage fallen con InvalidTrailer ("Invalid trailing header names in x-amz-trailer"), porque IONOS CLOUD no admite la extensión de sumas de verificación finales de AWS que boto3 incluyó a partir de la versión 1.36.0. Instale boto3<=1.35.99, o si necesita una versión más reciente de boto3, establezca las variables de entorno AWS_REQUEST_CHECKSUM_CALCULATION=when_required y AWS_RESPONSE_CHECKSUM_VALIDATION=when_required antes de cada ruta de carga en esta unidad (presigned PUT, upload_file, upload_fileobj, multipart) para que funcione.

Seleccione el punto de acceso para la región en la que se encuentra su bucket. El nombre de host del punto de acceso codifica la región, y el SDK deriva la región de firma a partir de él, por lo que puede mantener el region_name al mínimo y dejar que el punto de acceso dirija la enrutación.

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-1.ionoscloud.com",  # Frankfurt (de)
    aws_access_key_id="YOUR_ACCESS_KEY",       # 92-char Object Storage key
    aws_secret_access_key="YOUR_SECRET_KEY",   # 64-char Object Storage secret
    region_name="eu-central-1",
    config=Config(signature_version="s3v4"),
)

# Smoke test: list buckets you own
for b in s3.list_buckets()["Buckets"]:
    print(b["Name"], b["CreationDate"])

Nunca incluya credenciales de forma inline en el código fuente. Obténgalas de variables de entorno o de un gestor de secretos. En TaskBoard, la Access Key y la Secret Key provienen del estado de Terraform (el recurso ionoscloud_s3_key de la Unidad 2.4) y se inyectan como secretos de Kubernetes.

import os

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["OBJSTORAGE_ENDPOINT"],
    aws_access_key_id=os.environ["OBJSTORAGE_ACCESS_KEY"],
    aws_secret_access_key=os.environ["OBJSTORAGE_SECRET_KEY"],
    region_name=os.environ.get("OBJSTORAGE_REGION", "eu-central-1"),
    config=Config(signature_version="s3v4"),
)

1.2 Selección del punto de acceso regional adecuado

El punto de acceso no es intercambiable. Un bucket existe en exactamente una región, y debe dirigirse a él a través del punto de acceso de esa región. Object Storage está disponible en Berlín, Fráncfort, Logroño y Lenexa. La siguiente tabla asocia los centros de datos con sus regiones y puntos de acceso S3:

Elija una región cercana a su aplicación y a sus usuarios para reducir la latencia, y una región geográficamente separada para las copias de seguridad, de modo que una interrupción local no afecte también a sus datos principales. Observe los dos tipos de bucket: los buckets de propiedad del usuario se encuentran en de, eu-central-2 y eu-south-2, mientras que los buckets de propiedad del contrato se encuentran en eu-central-4, eu-central-3 y us-central-1. Los límites varían según el tipo: un usuario puede tener hasta 500 buckets de propiedad del usuario y hasta 1000 buckets de propiedad del contrato. El límite de carga en una sola solicitud es de 4,65 GiB para los buckets de propiedad del usuario y de 5 GiB para los buckets de propiedad del contrato, lo cual constituye el disparador práctico para la carga multipartita descrita en la sección 3.

2. Operaciones de buckets y URLs prefirmadas

Con un cliente en mano, las operaciones diarias son las estándar de S3: crear un bucket, listar objetos, configurar ACLs y generar URLs prefirmadas. Para TaskBoard, las URLs prefirmadas son el elemento central. Permiten que el navegador cargue y descargue archivos adjuntos directamente contra Object Storage, de modo que su API nunca transmita los bytes.

De forma predeterminada, los objetos son privados y solo el propietario del bucket puede acceder a ellos. Una URL prefirmada otorga acceso limitado en el tiempo a un solo objeto, sin cambiar los permisos del objeto y sin compartir sus claves. El propietario firma la URL, la entrega al cliente y el cliente la utiliza hasta que expira.

2.1 Creación de buckets y listado de objetos

Los nombres de bucket son únicos a nivel global en todo Object Storage, deben tener entre 3 y 63 caracteres y seguir las reglas de nomenclatura de DNS. Las claves de objeto pueden tener hasta 1024 caracteres.

bucket = "taskboard-attachments-prod"

# Create the bucket (idempotent-ish: catch the "already owned" case)
try:
    s3.create_bucket(Bucket=bucket)
except s3.exceptions.BucketAlreadyOwnedByYou:
    pass

# List objects under a prefix, paginated (collections can be huge)
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket=bucket, Prefix="task-42/"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

Siempre use paginación para las listas. Un solo bucket puede contener hasta 200.000.000 de objetos en el caso sin versiones, por lo que una lista sin paginación se truncará silenciosamente en la primera página.

2.2 URLs prefirmadas para carga y descarga

Genere una URL prefirmada de PUT para que el navegador cargue el archivo directamente. Su API devuelve la URL y la clave del objeto; nunca ve el contenido del archivo.

def presign_upload(key: str, content_type: str, expires: int = 900) -> str:
    return s3.generate_presigned_url(
        "put_object",
        Params={"Bucket": bucket, "Key": key, "ContentType": content_type},
        ExpiresIn=expires,  # seconds; keep short for uploads
    )

def presign_download(key: str, expires: int = 300) -> str:
    return s3.generate_presigned_url(
        "get_object",
        Params={"Bucket": bucket, "Key": key},
        ExpiresIn=expires,
    )

El navegador luego realiza la carga mediante una solicitud HTTP simple a la URL firmada. El Content-Type debe coincidir con lo que se firmó; de lo contrario, la verificación de la firma fallará:

await fetch(presignedUrl, {
  method: "PUT",
  headers: { "Content-Type": file.type },
  body: file,
});

Las URLs prefirmadas son ideales para permitir que otros usuarios carguen objetos directamente en su bucket sin necesidad de proporcionarles su Access Key y Secret Key. También son la herramienta adecuada para compartir un objeto privado con alguien que no tiene una cuenta de IONOS CLOUD: la URL funciona durante la ventana configurada y luego expira. Se admiten tanto Signature v2 como v4; utilice v4.

3. Patrones de carga y descarga de archivos

Los adjuntos pequeños son una sola put_object. Los adjuntos grandes requieren carga multipartita, tanto para superar el límite de tamaño de una sola solicitud como para cargar las partes en paralelo y ganar velocidad. Un objeto individual puede tener hasta 5 TB (5.497.558.138.880 bytes).

3.1 Carga multipartita para archivos grandes

El límite de carga en una sola solicitud es de 4,65 GiB (propiedad del usuario) o 5 GiB (propiedad del contrato). Más allá de ese límite, debe utilizar la API de carga multipartita. La boto3 de alto nivel de upload_file y upload_fileobj maneja la carga multipartita de forma automática una vez que un archivo supera el umbral configurado, lo cual es la ruta de nivel de producción.

from boto3.s3.transfer import TransferConfig

# Switch to multipart above 100 MB, 8 MB parts, up to 4 parallel uploads
transfer_cfg = TransferConfig(
    multipart_threshold=100 * 1024 * 1024,
    multipart_chunksize=8 * 1024 * 1024,
    max_concurrency=4,
)

s3.upload_file(
    Filename="/tmp/build-artifact.zip",
    Bucket=bucket,
    Key="task-42/build-artifact.zip",
    Config=transfer_cfg,
    ExtraArgs={"ContentType": "application/zip"},
)

La carga multipartita divide un objeto de gran tamaño en partes más pequeñas y las sube en paralelo, maximizando el rendimiento. Está disponible a través de la API y los SDK, pero no a través de la interfaz web de DCD. Si se abandona una carga multipartita, las partes subidas permanecen y acumulan costos de almacenamiento hasta que se limpien, lo cual es exactamente lo que la regla de ciclo de vida de la Sección 4 gestiona.

3.2 Descargas en streaming y Content-Type

Para las descargas, transmita el cuerpo en streaming en lugar de cargar el objeto completo en memoria. El cuerpo de la respuesta es un flujo similar a un archivo que puede iterar en fragmentos.

resp = s3.get_object(Bucket=bucket, Key="task-42/report.pdf")
content_type = resp["ContentType"]  # set at upload time

with open("/tmp/report.pdf", "wb") as f:
    for chunk in resp["Body"].iter_chunks(chunk_size=1024 * 1024):
        f.write(chunk)

Establezca ContentType de forma explícita al subir el archivo. Si omite este paso, las descargas se asignarán de forma predeterminada a un tipo binario genérico y los navegadores mostrarán un cuadro de diálogo para descargar el archivo en lugar de renderizarlo en línea.

4. Políticas de ciclo de vida y control de costos

Object Storage cobra por lo que usted almacena, por lo que los objetos huérfanos y las cargas multipartidas abandonadas representan una fuga de costos progresiva. Las reglas de ciclo de vida le permiten expirar objetos automáticamente y limpiar cargas incompletas. Usted las configura a través de la API de S3.

Una configuración de ciclo de vida admite estas acciones: expirar versiones actuales, eliminar permanentemente versiones no actuales, eliminar marcadores de eliminación de objetos expirados y eliminar cargas multipartidas incompletas. Usted puede configurar hasta 1000 reglas en una configuración. Cada regla se aplica a un prefijo de objeto diferente, y no puede establecer más de una regla para el mismo prefijo.

4.1 Expiración de objetos y limpieza de cargas multipartidas

Esta configuración expira las cargas temporales después de 7 días e interrumpe las cargas multipartidas incompletas después de 1 día:

s3.put_bucket_lifecycle_configuration(
    Bucket=bucket,
    LifecycleConfiguration={
        "Rules": [
            {
                "ID": "expire-temp-uploads",
                "Filter": {"Prefix": "tmp/"},
                "Status": "Enabled",
                "Expiration": {"Days": 7},
            },
            {
                "ID": "abort-incomplete-multipart",
                "Filter": {"Prefix": ""},
                "Status": "Enabled",
                "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 1},
            },
        ]
    },
)

Object Storage actualmente solo admite la clase de almacenamiento STANDARD, por lo que no puede utilizar reglas de ciclo de vida para transicionar objetos a un nivel más frío. Las únicas acciones disponibles son la expiración y la limpieza. Si un bucket utiliza Object Lock, las versiones no actuales no pueden eliminarse antes de que finalice su período de retención.

5. Compatibilidad con S3: lo que se admite y lo que no

Object Storage cuenta con uno de los niveles más altos de compatibilidad con la API de S3, pero no es una equivalencia del 100% con AWS. Verifique una función antes de depender de ella, en lugar de suponer que se comporta exactamente como AWS S3. La siguiente tabla resume el soporte de funciones clave:

Algunas restricciones a considerar al escribir el código. La copia de objetos no admite copias entre regiones, por lo que una operación de "mover un cubo a otra región" es una descarga y posterior carga, no una copia en el servidor. Object Lock (modos GOVERNANCE y COMPLIANCE) solo puede activarse en el momento de la creación del cubo, nunca puede agregarse a un cubo existente. La política del cubo utiliza JSON estándar con un Version de 2012-10-17. El cifrado en tránsito es TLS 1.2 o 1.3.

5.1 CORS para cargas desde el navegador

Dado que las cargas desde el navegador de TaskBoard se envían directamente a Object Storage mediante URLs prefirmadas, el cubo necesita una configuración de CORS que permita PUT desde su origen web. Sin ella, el navegador bloquea la solicitud entre orígenes antes de que llegue a Object Storage.

s3.put_bucket_cors(
    Bucket=bucket,
    CORSConfiguration={
        "CORSRules": [
            {
                "AllowedOrigins": ["https://app.taskboard.example"],
                "AllowedMethods": ["PUT", "GET"],
                "AllowedHeaders": ["*"],
                "MaxAgeSeconds": 3000,
            }
        ]
    },
)

La referencia autoritativa de la API de S3 se encuentra en https://api.ionos.com/docs/s3/v2/, y la API de gestión de claves y cubetas está documentada en https://api.ionos.com/docs/s3-management/v1/. Cuando tenga dudas sobre una función, consulte esas referencias antes de escribir código que dependa de ella.

Tarjeta rápida de referencia de API

Operaciones clave de S3 para Object Storage (mediante boto3 o HTTP firmado):

Punto de acceso: https://s3.<region>.ionoscloud.com (p. ej. s3.eu-central-1.ionoscloud.com) Autenticación: AWS Signature v4 con Access Key + Secret Key (no es un token de portador)

Laboratorio de código

Objetivo: Cargar y recuperar un adjunto de TaskBoard mediante boto3 usando URLs prefirmadas y carga multipartita, confirmando la autenticación con Access Key + Secret Key.

Requisitos previos:

• Cuenta de IONOS CLOUD con una Access Key + Secret Key de Object Storage generada
• Python 3.9 o superior con un boto3 compatible instalado (pip install "boto3<=1.35.99"); las versiones 1.36.0 y posteriores de boto3 hacen que todas las llamadas PutObject contra IONOS CLOUD Object Storage fallen con InvalidTrailer porque IONOS CLOUD no admite la extensión de checksum final de AWS introducida en esa versión, por lo que debe fijar la versión o establecer AWS_REQUEST_CHECKSUM_CALCULATION=when_required y AWS_RESPONSE_CHECKSUM_VALIDATION=when_required si debe usar una versión más reciente de boto3
• Un endpoint de región seleccionado (este laboratorio usa Frankfurt de / eu-central-1)

Paso 1: Exportar credenciales

export OBJSTORAGE_ENDPOINT="https://s3.eu-central-1.ionoscloud.com"
export OBJSTORAGE_ACCESS_KEY="<your-92-char-access-key>"
export OBJSTORAGE_SECRET_KEY="<your-64-char-secret-key>"
export OBJSTORAGE_REGION="eu-central-1"

Salida esperada:

(no output; variables set)

Paso 2: Crear el cliente y un bucket

import os, boto3
from botocore.config import Config

s3 = boto3.client("s3",
    endpoint_url=os.environ["OBJSTORAGE_ENDPOINT"],
    aws_access_key_id=os.environ["OBJSTORAGE_ACCESS_KEY"],
    aws_secret_access_key=os.environ["OBJSTORAGE_SECRET_KEY"],
    region_name=os.environ["OBJSTORAGE_REGION"],
    config=Config(signature_version="s3v4"))

bucket = "taskboard-lab-<your-initials>"
s3.create_bucket(Bucket=bucket)
print("created", bucket)

Salida esperada:

created taskboard-lab-ct

Paso 3: Generar una URL de carga preautorizada

url = s3.generate_presigned_url("put_object",
    Params={"Bucket": bucket, "Key": "task-1/note.txt", "ContentType": "text/plain"},
    ExpiresIn=900)
print(url)

Salida esperada:

https://s3.eu-central-1.ionoscloud.com/taskboard-lab-ct/task-1/note.txt?X-Amz-Algorithm=...

Paso 4: Cargar a través de la URL prefirmada con curl

echo "hello taskboard" > note.txt
curl -X PUT -H "Content-Type: text/plain" --upload-file note.txt "<PASTE_PRESIGNED_URL>"

Salida esperada:

(HTTP 200, empty body)

Paso 5: Carga multipartita de un archivo grande

from boto3.s3.transfer import TransferConfig
cfg = TransferConfig(multipart_threshold=5*1024*1024, multipart_chunksize=5*1024*1024)
s3.upload_file("bigfile.bin", bucket, "task-1/bigfile.bin", Config=cfg,
               ExtraArgs={"ContentType": "application/octet-stream"})
print("uploaded large file")

Salida esperada:

uploaded large file

Paso 6: Descarga mediante una URL GET prefirmada

get_url = s3.generate_presigned_url("get_object",
    Params={"Bucket": bucket, "Key": "task-1/note.txt"}, ExpiresIn=300)
import urllib.request
print(urllib.request.urlopen(get_url).read().decode())

Salida esperada:

hello taskboard

Paso 7: Agregar una regla de ciclo de vida para limpiar las cargas incompletas

s3.put_bucket_lifecycle_configuration(Bucket=bucket,
    LifecycleConfiguration={"Rules": [{
        "ID": "abort-mpu", "Filter": {"Prefix": ""}, "Status": "Enabled",
        "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 1}}]})
print("lifecycle set")

Salida esperada:

lifecycle set

Lista de verificación de validación:

• [ ] Cubo creado y visible en s3.list_buckets()
• [ ] Archivo subido y descargado mediante URLs prefirmadas
• [ ] La carga multipartita de un archivo de gran tamaño fue exitosa
• [ ] La regla de ciclo de vida se aplicó sin errores

Limpieza:

for obj in s3.list_objects_v2(Bucket=bucket).get("Contents", []):
    s3.delete_object(Bucket=bucket, Key=obj["Key"])
s3.delete_bucket(Bucket=bucket)
print("cleaned up")

Errores comunes

Errores de desarrollo a evitar con la integración de Object Storage:

1. Intentar autenticarse con el token bearer de la API de Cloud

   • Problema: Cada solicitud S3 devuelve 403 SignatureDoesNotMatch o InvalidAccessKeyId.
   • Por qué ocurre: Object Storage utiliza AWS Signature con un par de Access Key + Secret Key, no el token bearer de IONOS CLOUD utilizado por el resto de la API, ni roles IAM. Son sistemas de credenciales completamente independientes.
   • Solución: Genere una clave de Object Storage dedicada (DCD o Management API) y pásela como aws_access_key_id / aws_secret_access_key. Las claves actuales tienen 92 y 64 caracteres; rechace las suposiciones antiguas de 20/40 caracteres.

2. Omitir endpoint_url y conectar con AWS en su lugar

   • Problema: Las solicitudes agotan el tiempo de espera, fallan en DNS o llegan a AWS S3 real.
   • Por qué ocurre: boto3 utiliza por defecto los endpoints de AWS. Sin endpoint_url, el SDK nunca se comunica con IONOS CLOUD.
   • Solución: Siempre pase el endpoint específico de la región, por ejemplo endpoint_url="https://s3.eu-central-1.ionoscloud.com", y haga coincidir region_name con la región de ese endpoint.

3. Incompatibilidad de Content-Type que rompe las cargas preautorizadas

   • Problema: El PUT del navegador a una URL preautorizada devuelve 403 SignatureDoesNotMatch.
   • Por qué ocurre: El Content-Type se incluyó al firmar la URL, pero el cliente envió un Content-Type de cabecera diferente (o ninguno). Las cabeceras firmadas deben coincidir exactamente.
   • Solución: Firme con el tipo de contenido exacto y envíe la cabecera idéntica desde el cliente, u omita ContentType por completo de Params para que no forme parte de la firma.

Resumen

Ahora puede integrar IONOS Cloud Object Storage en el código de aplicaciones a través de su API compatible con S3. Configura un cliente boto3 con el endpoint regional correcto y autenticación con Access Key + Secret Key, mueve los bytes de archivos fuera de la ruta de su API mediante URLs de carga y descarga preautorizadas, gestiona archivos grandes con carga multipart, realiza descargas en streaming y aplica reglas de ciclo de vida para mantener el costo del almacenamiento bajo control. El flujo de adjuntos de TaskBoard ahora permite que los navegadores carguen directamente en Object Storage, mientras que la API solo registra metadatos.

Puntos clave:

• Object Storage se autentica con una Access Key de 92 caracteres y una Secret Key de 64 caracteres mediante AWS Signature v4, nunca con el token bearer de la Cloud API ni con roles de IAM
• Siempre pase un endpoint_url explícito que coincida con la región del bucket; los nombres de bucket son únicos a nivel global y tienen de 3 a 63 caracteres
• Las URLs preautorizadas otorgan acceso limitado en el tiempo y sin credenciales, de modo que los clientes cargan y descargan directamente en Object Storage
• Use carga multipart para archivos que superan el límite de una sola solicitud (4,65 GiB para buckets de usuario, 5 GiB para buckets de contrato); los objetos pueden alcanzar 5 TB
• Object Storage tiene una alta compatibilidad con S3, pero no una paridad completa: la copia entre regiones no está soportada, Object Lock solo se aplica en el momento de la creación, y solo existe la clase de almacenamiento STANDARD

Terminología importante:

• Access Key / Secret Key: El par de credenciales S3 (92 y 64 caracteres) que autentica cada solicitud de Object Storage mediante AWS Signature.
• URL preautorizada: Una URL firmada con límite de tiempo que otorga acceso a un solo objeto sin compartir claves ni cambiar permisos; es la base para cargas y descargas directas desde el navegador.
• Carga multipart: Dividir un objeto grande en partes que se cargan en paralelo; es obligatorio por encima del límite de tamaño de una sola solicitud y se limpia mediante reglas de ciclo de vida.
• Regla de ciclo de vida: Una configuración de bucket (hasta 1000 reglas) que expira objetos y aborta cargas multipart incompletas automáticamente.
• Tipo de bucket: Buckets de usuario frente a buckets de contrato, que difieren en disponibilidad regional, límites de buckets por usuario y límites de carga por solicitud.

Próximos pasos

Continuar aprendiendo: Unidad 4.3: Integración de streaming de eventos

Temas relacionados:

• Unidad 2.4: Aprovisionamiento de almacenamiento como código
• Unidad 4.1: Integración de base de datos y caché