Unidad 4.2: Integración de Object Storage

Introducción

TaskBoard permite a los usuarios adjuntar archivos a tareas: capturas de pantalla, PDF, diseños de mockup, el ocasional video de varios gigabytes. No quiere que esos bytes fluyan a través de su API proceso. Consumen memoria, bloquean hilos de trabajo y convierten un API sin estado en un cuello de botella. La respuesta es IONOS Cloud Object Storage con URLs firmadas: el navegador se comunica con Object Storage directamente, y su API solo maneja registros de metadatos pequeños.

En esta unidad, usted conecta el API de TaskBoard a Object Storage a través del S3-compatible API utilizando boto3. La cosa más importante que debe internalizar desde el principio: Object Storage no utiliza su token de portador de IONOS Cloud. Se autentica con un par de clave de acceso y clave secreta separado, exactamente como AWS S3. Usted configurará el cliente, generará URLs de carga y descarga firmadas, manejará archivos grandes con carga multipartida y aplicará reglas de ciclo de vida para que las cargas abandonadas no acumulen costos para siempre.

1. Autenticación y Conexión con boto3

Object Storage expone una superficie v2 de S3 API de AWS, por lo que los SDK de AWS estándar funcionan con ella. Lo que cambia es el punto de conexión y las credenciales. Debe pasar un endpoint_url explícito (el SDK predeterminado es AWS, no IONOS) y un par de clave de acceso + clave secreta. Estas claves no son su token de portador de Cloud API ni un rol de IAM. Se generan por separado y autenticar cada solicitud de S3 a través de la firma de AWS.

Object Storage autentica a los usuarios con un par de claves: una clave de acceso y una clave secreta. Una clave debe generarse manualmente, ya sea en el DCD bajo credenciales y administración de Object Storage o a través de la administración de Object Storage API. La longitud actual de la clave de acceso es de 92 caracteres y la longitud de la clave secreta es de 64 caracteres, por lo que no suponga anchos de campo fijos de formatos anteriores de 20/40 caracteres. Cada usuario puede tener hasta 5 claves de acceso.

1.1 Construyendo el cliente de S3

Antes de escribir cualquier código de cliente, fije su versión de boto3: boto3 1.36.0 y posterior falla cada llamada de PutObject contra IONOS Object Storage con InvalidTrailer ("Nombres de encabezados de remolque no válidos en x-amz-trailer") porque IONOS no admite la extensión de suma de comprobación de AWS que boto3 envió 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 (carga presignada PUT, upload_file, upload_fileobj, multiparte) funcionará.

Elija el punto de conexión para la región donde se encuentra su cubo. El nombre de host del punto de conexión codifica la región, y el SDK deriva la región de firma de él, por lo que puede dejar el region_name mínimo y dejar que el punto de conexión conduzca la routificació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 en línea en el código fuente. Extraiga las credenciales de variables de entorno o un administrador de secretos. En TaskBoard, la clave de acceso y la clave secreta se obtienen 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 usted debe acceder 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 asigna centros de datos a sus regiones y puntos de acceso de S3:

Elija una región cercana a su aplicación y usuarios para reducir la latencia, y una región geográficamente separada para las copias de seguridad para que una interrupción local no afecte a sus datos principales. Tenga en cuenta los dos tipos de buckets: los buckets de propiedad de usuario se encuentran en de, eu-central-2, y eu-south-2, mientras que los buckets de propiedad de contrato se encuentran en eu-central-4, eu-central-3, y us-central-1. Los límites difieren según el tipo: un usuario puede tener hasta 500 buckets de propiedad de usuario y hasta 1000 buckets de propiedad de contrato. El límite de subida de una sola solicitud es de 4,65 GB para los buckets de propiedad de usuario y de 5 GB para los buckets de propiedad de contrato, lo que es el desencadenador práctico para la subida de varias partes que se cubre en la Sección 3.

2. Operaciones de cubeta y URLs firmadas

Con un cliente en mano, las operaciones diarias son estándar S3: crear una cubeta, listar objetos, establecer ACL, y generar URLs firmadas. Para TaskBoard, las URLs firmadas son el centro de atención. Permiten que el navegador cargue y descargue archivos directamente contra Object Storage, de modo que su API nunca transmite los bytes.

Por defecto, los objetos son privados y solo el propietario de la cubeta puede acceder a ellos. Una URL firmada otorga acceso limitado en el tiempo a un objeto único sin cambiar los permisos del objeto y sin compartir sus claves. El propietario firma la URL, se la entrega al cliente, y el cliente la utiliza hasta que caduca.

2.1 Crear cubetas y listar objetos

Los nombres de las cubetas son únicos en todo Object Storage, deben tener entre 3 y 63 caracteres, y seguir las reglas de nomenclatura de DNS. Las claves de los objetos 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 pagine las listas. Una sola cubeta puede contener hasta 200.000.000 de objetos en el caso no versionado, por lo que una lista no paginada se truncará silenciosamente en la primera página.

2.2 URLs de carga y descarga firmadas

Genere una URL firmada 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,
    )

Luego, el navegador carga con una solicitud HTTP simple a la URL firmada. El Content-Type debe coincidir con lo que se firmó, o la comprobación de la firma falla:

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

Las URLs firmadas son ideales para permitir que otros usuarios carguen objetos directamente en su cubeta sin entregarles nunca su clave de acceso y clave secreta. También son la herramienta adecuada para compartir un objeto privado con alguien que no tiene cuenta de IONOS: la URL funciona durante la ventana configurada y luego caduca. Se admiten tanto la firma v2 como la v4; utilice la v4.

3. Patrones de carga y descarga de archivos

Los archivos adjuntos pequeños son un solo put_object. Los archivos adjuntos grandes necesitan una carga de varias partes, tanto para superar el límite de tamaño de solicitud única como para cargar partes en paralelo para aumentar la velocidad. Un objeto individual puede tener un tamaño de hasta 5 TB (5,497,558,138,880 bytes).

3.1 Carga de varias partes para archivos grandes

El límite de carga de solicitud única es de 4,65 GB (de propiedad del usuario) o 5 GB (de propiedad del contrato). Más allá de eso, usted debe utilizar la carga de varias partes API. Los métodos de alto nivel boto3 y upload_file de upload_fileobj manejan automáticamente la carga de varias partes una vez que un archivo supera el umbral configurado, que es el camino 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 de varias partes divide un objeto grande en partes más pequeñas y las carga 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 DCD. Si se abandona una carga de varias partes, las partes cargadas permanecen y generan costos de almacenamiento hasta que usted las elimine, que es exactamente lo que la regla de ciclo de vida en la Sección 4 maneja.

3.2 Descargas de transmisión y Content-Type

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

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 explícitamente al cargar. Si lo omite, las descargas utilizan un tipo binario genérico y los navegadores ofrecerán una ventana de diálogo de descarga en lugar de renderizar el archivo en línea.

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

Object Storage cobra por lo que usted almacena, por lo que los objetos huérfanos y las subidas de varias partes abandonadas son una fuga de costes lenta. Las reglas de ciclo de vida le permiten expirar objetos automáticamente y limpiar subidas incompletas. Usted las configura a través de la S3 API.

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 subidas de varias partes incompletas. Usted puede configurar hasta 1000 reglas en una configuración. Cada regla se aplica a un prefijo de objeto diferente, y usted no puede configurar más de una regla para el mismo prefijo.

4.1 Expirar objetos y limpiar subidas de varias partes

Esta configuración expira subidas temporales después de 7 días y aborta subidas de varias partes 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 usted no puede utilizar reglas de ciclo de vida para transitar objetos a un nivel más frío. Las únicas acciones disponibles son expiración y limpieza. Si un bucket utiliza Object Lock, las versiones no actuales no pueden ser eliminadas antes de que se complete su período de retención.

5. S3 Compatibilidad: Qué es y qué no es compatible

Object Storage tiene uno de los niveles más altos de compatibilidad con S3 API, pero no es una paridad del 100% con AWS. Verifique una característica antes de depender de ella en lugar de asumir que se comporta exactamente como AWS S3. La siguiente tabla resume la compatibilidad de las características clave:

Algunas limitaciones para codificar alrededor. La copia de objeto no admite copias entre regiones, por lo que una operación "mover bucket a otra región" es una descarga y luego una carga, no una copia del lado del servidor. El bloqueo de objeto (modos GOVERNANCE y COMPLIANCE) solo se puede habilitar en el momento de la creación del bucket, nunca se puede agregar a un bucket existente. La política de bucket utiliza el estándar JSON con un Version de 2012-10-17. El cifrado en tránsito es TLS 1.2 o 1.3.

5.1 CORS para cargas en el navegador

Dado que las cargas en el navegador de TaskBoard se cargan directamente en Object Storage a través de URLs prefirmadas, el bucket necesita una configuración de CORS que permita PUT desde su origen web. Sin ella, el navegador bloquea la solicitud de origen cruzado 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 autorizada de S3 API se encuentra en https://api.ionos.com/docs/s3/v2/, y la gestión de claves/deposito de API está documentada en https://api.ionos.com/docs/s3-management/v1/. Cuando tenga dudas sobre una función, compruebe esas fuentes antes de escribir código que dependa de ella.

API Tarjeta de referencia rápida

Operaciones clave de S3 para Object Storage (a través de boto3 o firmado HTTP):

Punto de conexión: https://s3.<region>.ionoscloud.com (por ejemplo, s3.eu-central-1.ionoscloud.com) Autenticación: Firma de AWS v4 con clave de acceso + clave secreta (NO un token de portador)

Laboratorio de código

Objetivo: Subir y recuperar un archivo adjunto de TaskBoard a través de boto3 utilizando URLs con firma previa y carga multipartida, confirmando la autenticación con Clave de acceso + Clave secreta.

Requisitos previos:

• Cuenta de IONOS Cloud con una Object Storage Clave de acceso + Clave secreta generada
• Python 3.9+ con un boto3 compatible instalado (pip install "boto3<=1.35.99"); boto3 1.36.0 y versiones posteriores fallan en cada llamada a PutObject contra IONOS Object Storage con InvalidTrailer porque IONOS no admite la extensión de suma de comprobación de AWS introducida en ese lanzamiento, así que fije la versión o establezca AWS_REQUEST_CHECKSUM_CALCULATION=when_required y AWS_RESPONSE_CHECKSUM_VALIDATION=when_required si debe utilizar una versión más reciente de boto3
• Un punto de conexión de región elegido (este laboratorio utiliza 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"

No hay texto para traducir. Por favor, proporcione el texto técnico que desea traducir.

(no output; variables set)

Paso 2: Crear el cliente y un depósito

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)

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

created taskboard-lab-ct

Paso 3: Generar una URL de carga firmada previamente

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

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

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 firmada con anticipación con curl

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

No hay texto que traducir. Por favor, proporcione el texto técnico que necesita ser traducido al español.

(HTTP 200, empty body)

Paso 5: Carga de subida múltiple 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")

No hay texto que traducir. Por favor, proporcione el texto técnico que desea que traduzca.

uploaded large file

Paso 6: Descargar a través de 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())

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

hello taskboard

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

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

No hay texto para traducir. Por favor, proporcione el texto técnico que desea que traduzca.

lifecycle set

Lista de verificación de validación:

• [ ] Bucket creado y visible en s3.list_buckets()
• [ ] Archivo subido y descargado a través de URLs firmadas
• [ ] Subida de varios partes de un archivo grande tuvo éxito
• [ ] Regla de ciclo de vida aplicada 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 los desarrolladores que deben evitarse con la integración de Object Storage:

1. Intentar autenticar con su token de portador de Cloud API

   • Problema: Cada solicitud de S3 devuelve 403 SignatureDoesNotMatch o InvalidAccessKeyId.
   • Por qué sucede: Object Storage utiliza la firma de AWS con un par de clave de acceso + clave secreta, no el token de portador de IONOS Cloud utilizado por el REST del API y no los roles de IAM. Son sistemas de credenciales completamente separados.
   • Solución: Generar una clave dedicada de Object Storage (DCD o clave de administración de API) y pasarla como aws_access_key_id / aws_secret_access_key. Las claves actuales tienen 92 y 64 caracteres; rechazar suposiciones anteriores de 20/40 caracteres.

2. Omitir la dirección URL del extremo y golpear AWS en su lugar

   • Problema: Las solicitudes caducan, fallan DNS o aterrizan en AWS S3 real.
   • Por qué sucede: boto3 predetermina los extremos de AWS. Sin endpoint_url, el SDK nunca se comunica con IONOS.
   • Solución: Siempre pasar el extremo específico de la región, por ejemplo endpoint_url="https://s3.eu-central-1.ionoscloud.com", y coincidir region_name con la región de ese extremo.

3. Incompatibilidad de Content-Type que rompe las cargas firmadas previamente

   • Problema: El navegador PUT a una URL firmada previamente devuelve 403 SignatureDoesNotMatch.
   • Por qué sucede: El Content-Type se incluyó al firmar la URL, pero el cliente envió un encabezado Content-Type diferente (o ninguno). Los encabezados firmados deben coincidir exactamente.
   • Solución: Firmar con el tipo de contenido exacto y enviar el encabezado idéntico desde el cliente, o omitir ContentType de Params por completo para que no sea parte de la firma.

Resumen

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

Puntos clave:

• Object Storage autentica con una clave de acceso de 92 caracteres y una clave secreta de 64 caracteres a través de la firma AWS v4, nunca con el token de portador de Cloud API o los roles de IAM
• Siempre pase un endpoint_url explícito que coincida con la región del bucket; los nombres de los buckets son únicos a nivel global y tienen entre 3 y 63 caracteres
• Las URLs presignadas otorgan acceso limitado en el tiempo y sin credenciales, por lo que los clientes pueden cargar y descargar directamente en Object Storage
• Utilice la carga multipartida para archivos que superen el límite de solicitud única (4,65 GB de propiedad del usuario, 5 GB de propiedad del contrato); los objetos pueden alcanzar los 5 TB
• Object Storage tiene una alta compatibilidad con S3, pero no una paridad total: la copia entre regiones no es compatible, el bloqueo de objetos solo es compatible en el momento de la creación y solo existe la clase de almacenamiento STANDARD

Terminología importante:

• Clave de acceso / Clave secreta: El par de credenciales de S3 (92 y 64 caracteres) que autentica cada solicitud de Object Storage a través de la firma AWS.
• URL presignada: Una URL firmada y limitada en el tiempo que otorga acceso a un objeto único sin compartir claves o cambiar permisos; la base para las cargas y descargas directas del navegador.
• Carga multipartida: Dividir un objeto grande en partes que se cargan en paralelo; se requiere por encima del límite de tamaño de solicitud única y se limpia a través de reglas de ciclo de vida.
• Regla de ciclo de vida: Una configuración del bucket (hasta 1000 reglas) que caduca objetos y aborta cargas multipartidas incompletas de forma automática.
• Tipo de bucket: Buckets de propiedad del usuario versus buckets de propiedad del contrato, que difieren en la disponibilidad de la región, los límites de buckets por usuario y los techos de carga de solicitud única.

Próximos pasos

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

Temas relacionados:

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