15 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Configurar boto3 contra un endpoint regional de IONOS Cloud Object Storage con una Access Key y una Secret Key
  • Implementar URLs de carga y descarga prefirmadas para que los navegadores transfieran directamente los adjuntos de TaskBoard
  • Cargar archivos grandes mediante multipart upload y transmitir descargas con los tipos de contenido correctos
  • Automatizar reglas de ciclo de vida a través de la API de S3 para expirar objetos temporales y cargas abandonadas
  • Verificar la compatibilidad de las funciones de S3 antes de utilizar una API específica de AWS en su código

Unidad 4.2: Integración de Object Storage

Introducción

Los usuarios de TaskBoard desean adjuntar capturas de pantalla, registros y documentos a las tareas. Rutar esos bytes a través de los pods de la API consumiría memoria, ancho de banda y tiempo de solicitud. En su lugar, el navegador sube directamente a el bucket de la Unidad 2.4 mediante una URL presigned de corta duración, y la API almacena solo la clave del objeto en PostgreSQL.

IONOS Cloud Object Storage utiliza el protocolo S3, por lo que usted emplea SDKs estándar de S3. Sin embargo, no es AWS: usted configura el endpoint de forma explícita, se autentica con una Access Key y una Secret Key, y verifica qué funciones de S3 existen antes de llamarlas. En esta unidad, usted construye el servicio de adjuntos con boto3: configuración del cliente, URLs presigned, subidas multipart, descargas en streaming y reglas de ciclo de vida. El Code Lab ejecuta el flujo completo de subida y descarga.

1. El cliente boto3

import os
import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-3.ionoscloud.com",
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],       # terraform output uploads_access_key
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],   # terraform output uploads_secret_key
    region_name="eu-central-3",
    config=Config(signature_version="s3v4"),
)
print([b["Name"] for b in s3.list_buckets()["Buckets"]])

Sin endpoint_url, boto3 se comunica con AWS y sus claves fallan. Las credenciales son un par de Access Key y Secret Key: Object Storage no acepta el bearer token de la Cloud API, y los roles de IAM y el Security Token Service (STS) no están admitidos. Sus credenciales no están vinculadas a una región o bucket específicos, por lo que un par de claves funciona con cada endpoint.

1.1 Endpoints por región

El endpoint depende del tipo de bucket y de la región. La siguiente tabla enumera los endpoints para los buckets de propiedad contractual:

Centro de datos Región Endpoint Endpoint de sitio web estático
Frankfurt, Alemania eu-central-4 s3.eu-central-4.ionoscloud.com s3-website.eu-central-4.ionoscloud.com
Berlín, Alemania eu-central-3 s3.eu-central-3.ionoscloud.com s3-website.eu-central-3.ionoscloud.com
Lenexa, EE. UU. us-central-1 s3.us-central-1.ionoscloud.com s3-website.us-central-1.ionoscloud.com

Los buckets de propiedad del usuario utilizan otras regiones, por ejemplo s3.eu-central-2.ionoscloud.com para Berlín. El bucket de TaskBoard es de propiedad contractual en eu-central-3. Los endpoints responden en HTTP y HTTPS; utilice siempre https://. El cifrado en tránsito utiliza TLS 1.2 o 1.3.

1.2 El cambio de sumas de verificación en boto3 1.36

A partir de boto3 1.36.0, PutObject envía nuevas sumas de verificación de cola que Object Storage aún no admite. Las llamadas fallan entonces con InvalidTrailer: "Invalid trailing header names in x-amz-trailer". Fije boto3<=1.35.99 o establezca estas variables para su proceso:

export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required

Colóquelos en el ConfigMap de la API de la Unidad 3.2 para que cada pod los reciba.

2. Buckets, acceso y URLs prefirmadas

2.1 Operaciones de bucket

Terraform administra el bucket de larga duración de TaskBoard (Unidad 2.4). Las pruebas y las herramientas aún pueden crear y listar buckets en el código:

from botocore.exceptions import ClientError

try:
    s3.create_bucket(Bucket="taskboard-ci-4711",
                     CreateBucketConfiguration={"LocationConstraint": "eu-central-3"})
except ClientError as e:
    if e.response["Error"]["Code"] != "BucketAlreadyOwnedByYou":
        raise
print(s3.get_bucket_acl(Bucket="taskboard-ci-4711")["Grants"])

Los objetos son privados de forma predeterminada; solo el propietario del bucket puede acceder a ellos. Manténgalo así. Para un bucket propiedad de un contrato, una ACL comparte el acceso solo con los destinatarios de otros contratos; para otorgar acceso a los usuarios de su propio contrato, utilice una Bucket Policy. TaskBoard no necesita ninguno de los dos, porque las URLs prefirmadas otorgan acceso limitado en el tiempo a objetos individuales.

2.2 URLs de carga prefirmadas

import uuid

BUCKET = "taskboard-uploads-dev-7f3a"

def create_upload(task_id: int, filename: str, content_type: str) -> dict:
    key = f"tasks/{task_id}/{uuid.uuid4()}/{filename}"
    url = s3.generate_presigned_url(
        "put_object",
        Params={"Bucket": BUCKET, "Key": key, "ContentType": content_type},
        ExpiresIn=900,
    )
    return {"key": key, "url": url, "headers": {"Content-Type": content_type}}

Las URLs prefirmadas se generan localmente mediante un algoritmo de firma con sus credenciales; no se realiza ninguna llamada a la API. Se admiten los tipos de firma v2 y v4. A continuación, el navegador envía el archivo en sí:

const { key, url, headers } = await (await fetch(`/api/tasks/${id}/attachments`, { method: "POST",
  body: JSON.stringify({ filename: file.name, contentType: file.type }) })).json();
await fetch(url, { method: "PUT", headers, body: file });
await fetch(`/api/tasks/${id}/attachments/${encodeURIComponent(key)}/confirm`, { method: "POST" });

Dado que ContentType forma parte de la firma, el navegador debe enviar exactamente esa cabecera. La llamada de confirmación permite que la API verifique el objeto con head_object antes de escribir la clave en PostgreSQL.

Solo el propietario del bucket puede generar una URL presigned válida; en el caso de un bucket de propiedad de un contrato, un administrador también puede hacerlo. La clave que firma debe pertenecer a uno de ellos.

2.3 CORS para cargas desde el navegador

Un navegador en https://taskboard.example.com solo puede PUT al bucket si la configuración de CORS del bucket lo permite:

resource "ionoscloud_s3_bucket_cors_configuration" "uploads" {
  bucket = ionoscloud_s3_bucket.uploads.name
  cors_rule {
    allowed_methods = ["PUT", "GET"]
    allowed_origins = ["https://taskboard.example.com"]
    allowed_headers = ["Content-Type"]
    expose_headers  = ["ETag"]
    max_age_seconds = 3000
  }
}

allowed_methods acepta GET, PUT, HEAD, POST y DELETE.

3. Patrones de carga y descarga

3.1 Carga multipartita para archivos grandes

Una solicitud de carga individual está limitada a 5 GiB para los cubos de propiedad del contrato y a 4.65 GiB para los cubos de propiedad del usuario. Para tamaños superiores, utilice la carga multipartita, hasta el tamaño máximo de objeto de 5 TiB. La transferencia administrada de boto3 divide los archivos por usted:

from boto3.s3.transfer import TransferConfig

cfg = TransferConfig(multipart_threshold=64 * 1024**2,
                     multipart_chunksize=64 * 1024**2,
                     max_concurrency=4)
s3.upload_file("export.tar.gz", BUCKET, "exports/2026-11/export.tar.gz",
               ExtraArgs={"ContentType": "application/gzip"}, Config=cfg)

Las tareas del lado del servidor, como las exportaciones del worker, utilizan este patrón. Para cargas al navegador de varios gigabytes, la API llama a create_multipart_upload, presignifica una URL upload_part por parte y finaliza con complete_multipart_upload utilizando los ETags devueltos. Una carga multipartida abandonada conserva sus partes, las cuales la regla de ciclo de vida de la sección 4 elimina.

3.2 Descargas en streaming

Para las descargas, la API suele devolver una redirección a una URL presignada GET. Cuando debe procesar el archivo por sí misma, debe transmitirlo en lugar de cargarlo en memoria:

from fastapi.responses import StreamingResponse

def download(key: str):
    obj = s3.get_object(Bucket=BUCKET, Key=key)
    return StreamingResponse(obj["Body"].iter_chunks(chunk_size=1024 * 1024),
                             media_type=obj["ContentType"])

Guarde el tipo de contenido en el momento de la carga; get_object lo devuelve. Los metadatos definidos por el usuario por objeto están limitados a 2 kB, y un nombre de objeto, incluido su ruta de carpeta, puede tener hasta 1024 caracteres.

3.3 Límites de velocidad en la enumeración y eliminación

En los cubos propiedad del contrato, el uso intensivo de recursos de List Objects y Delete Objects activa la limitación de velocidad, aplicada por contrato. La respuesta es 429 Too Many Requests con una cabecera Retry-After:

import time

def list_all(prefix: str):
    kwargs = {"Bucket": BUCKET, "Prefix": prefix}
    while True:
        try:
            page = s3.list_objects_v2(**kwargs)
        except ClientError as e:
            if e.response["ResponseMetadata"]["HTTPStatusCode"] != 429:
                raise
            time.sleep(int(e.response["ResponseMetadata"]["HTTPHeaders"].get("retry-after", "1")))
            continue
        yield from page.get("Contents", [])
        if not page.get("IsTruncated"):
            return
        kwargs["ContinuationToken"] = page["NextContinuationToken"]

No realice consultas a List Objects en un horario fijo; mantenga la lista de adjuntos en PostgreSQL.

4. Reglas de ciclo de vida mediante la API

Las reglas de ciclo de vida automatizan la eliminación de objetos y sus versiones. Aplíquelas con la API de S3:

s3.put_bucket_lifecycle_configuration(
    Bucket=BUCKET,
    LifecycleConfiguration={"Rules": [
        {"ID": "expire-tmp", "Status": "Enabled",
         "Filter": {"Prefix": "tmp/"}, "Expiration": {"Days": 7}},
        {"ID": "abort-multipart", "Status": "Enabled", "Filter": {},
         "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 5}},
    ]},
)
print(s3.get_bucket_lifecycle_configuration(Bucket=BUCKET)["Rules"])

Una regla admite cuatro acciones: expirar las versiones actuales, eliminar de forma permanente las versiones no actuales, eliminar los marcadores de eliminación de objetos expirados y eliminar las cargas multipart incompletas. Una configuración puede contener hasta 1000 reglas. Terraform gestiona la misma configuración con ionoscloud_s3_bucket_lifecycle_configuration.

No existen reglas de transición aquí. Solo está disponible la clase de almacenamiento STANDARD, por lo que las reglas de ciclo de vida no pueden mover objetos a otra clase de almacenamiento. La gestión de costes en IONOS Cloud Object Storage consiste en eliminar lo que ya no necesita.

5. Verificaciones de compatibilidad con S3

IONOS Cloud Object Storage es compatible con la mayoría de las APIs de S3, pero no con todas. La siguiente tabla muestra el nivel de soporte por función:

Función Compatible Notas
CRUD de buckets Sí
CRUD de objetos Sí
Copia de objetos Sí No se admite la copia entre regiones
Subidas multipart Sí
URLs prefirmadas Sí Se admiten los tipos de firma v2 y v4
ACL de buckets Sí
ACL de objetos Sí
Bloqueo de acceso público Sí Solo a través de la API
Políticas de bucket Sí
Políticas de objeto Sí
Configuración de CORS Sí
Versionado de buckets Sí
Replicación de buckets Sí Se admiten la replicación intrarregional y la replicación entre regiones
Etiquetado de buckets Sí Solo a través de la API
Etiquetado de objetos Sí Solo a través de la API
Ciclo de vida de buckets Sí
Registro de acceso a buckets Sí
Configuración de cifrado de buckets Sí El cifrado del lado del servidor se utiliza de forma predeterminada en la interfaz web. El cifrado con claves de cifrado gestionadas por el cliente está disponible a través de la API.
Cifrado de objetos Sí Solo a través de la API
Sitios web de buckets Sí
Inventario de buckets Sí Solo a través de la API
Bloqueo de objetos Sí
Retención legal Sí
Identity and Access Management (IAM) No
Security Token Service (STS) No
Autenticación multifactor No
Notificaciones de buckets No
Pago de solicitudes No
Métricas de buckets No
Analítica de buckets No
Bucket Accelerate No
S3 Select No

Como muestra la tabla, la ruta de datos es ampliamente compatible, mientras que las funciones de la cuenta de AWS no están disponibles. Esto tiene dos consecuencias para TaskBoard: sin Notificaciones de buckets, la llamada de confirmación de la API (sección 2.2) sustituye al evento "objeto creado", y sin STS, cada servicio obtiene su propio par de claves de larga duración. Los tipos de bucket también difieren: por ejemplo, el Registro de acceso a buckets no está disponible para los buckets de propiedad contractual. Verifique el tipo de bucket antes de depender de una función.

Tarjeta rápida de referencia de API

Principales operaciones de S3 detrás del código de esta unidad:

Método Endpoint Descripción
PUT /{Bucket}/{Key} Carga un objeto (el destino de una URL de carga preautorizada)
GET /{Bucket}/{Key} Descarga un objeto (el destino de una URL de descarga preautorizada)
GET /{Bucket}?list-type=2 Lista objetos (ListObjectsV2, con límite de velocidad en cubos propiedad del contrato)
POST /{Bucket}/{Key}?uploads Inicia una carga multipartita
PUT /{Bucket}?lifecycle Establece la configuración del ciclo de vida

URL base: https://s3.eu-central-3.ionoscloud.com (un endpoint por región) Autenticación: Firma de AWS (v4 o v2) con Access Key y Secret Key, no un token de portador

Laboratorio de código

Objetivo: Cargar y recuperar los archivos adjuntos de TaskBoard con boto3: una URL de carga preautorizada, una carga multipartita y una descarga preautorizada, todo autenticado con una Access Key y una Secret Key.

Requisitos previos:

  • El bucket y la access key de la Unidad 2.4, aplicados, además del recurso CORS de la Sección 2.3
  • Python 3.12 con boto3 y requests
  • curl y un archivo de prueba de 100 MB: head -c 100M /dev/urandom > big.bin

Paso 1: Configurar las credenciales

export S3_ACCESS_KEY=$(terraform output -raw uploads_access_key)
export S3_SECRET_KEY=$(terraform output -raw uploads_secret_key)
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required
python -c "import boto3; print(boto3.__version__)"

Salida esperada:

1.x.y

Paso 2: Demostrar el modelo de autenticación

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $IONOS_TOKEN" \
  https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev-7f3a

Salida esperada:

4xx status code (not 200)

El token de Cloud API no es una credencial de S3, por lo que la solicitud se rechaza. Ahora, enumere el bucket con el cliente de la Sección 1:

print(s3.list_objects_v2(Bucket=BUCKET).get("KeyCount"))

Salida esperada:

0

Paso 3: Crear una URL de carga preautorizada

up = create_upload(42, "screenshot.png", "image/png")
print(up["key"]); print(up["url"][:60], "...")

Salida esperada:

tasks/42/<uuid>/screenshot.png
https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev ...

Paso 4: Carga como el navegador

curl -s -o /dev/null -w "%{http_code}\n" -X PUT -H "Content-Type: image/png" \
  --upload-file screenshot.png "<url from Step 3>"

Salida esperada:

200

Paso 5: Carga de un archivo grande en partes

s3.upload_file("big.bin", BUCKET, "tmp/big.bin", Config=cfg)
print(s3.head_object(Bucket=BUCKET, Key="tmp/big.bin")["ETag"])

Salida esperada:

"<hash>-2"

El sufijo -2 muestra un objeto multipart de dos partes: 64 MB y los 36 MB restantes.

Paso 6: Descarga a través de una URL prefirmada

url = s3.generate_presigned_url("get_object", Params={"Bucket": BUCKET, "Key": up["key"]}, ExpiresIn=300)
import requests; r = requests.get(url); print(r.status_code, r.headers["Content-Type"])

Salida esperada:

200 image/png

Paso 7: Aplicar las reglas de ciclo de vida

Ejecute el código de la sección 4. Salida esperada:

[{'ID': 'expire-tmp', ...}, {'ID': 'abort-multipart', ...}]

Lista de verificación:

  • [ ] El token de portador se rechaza y el par de claves obtiene acceso
  • [ ] La carga presignada de PUT se realiza sin credenciales en la solicitud
  • [ ] El ETag de la parte finaliza con un recuento de partes
  • [ ] El objeto descargado tiene el tipo de contenido establecido en la carga

Limpieza:

for k in [up["key"], "tmp/big.bin"]:
    s3.delete_object(Bucket=BUCKET, Key=k)

Errores comunes

Errores de desarrollo a evitar con el tema de esta unidad:

  1. InvalidTrailer en cada carga

    • Problema: put_object y upload_file fallan tras una actualización de dependencias con "Invalid trailing header names in x-amz-trailer".
    • Por qué ocurre: boto3 1.36.0 y versiones posteriores envían tráileres de sumas de verificación que Object Storage aún no admite.
    • Solución: Establezca AWS_REQUEST_CHECKSUM_CALCULATION=when_required y AWS_RESPONSE_CHECKSUM_VALIDATION=when_required, o fije boto3<=1.35.99 (Sección 1.2).
  2. SignatureDoesNotMatch en cargas preautorizadas

    • Problema: El PUT del navegador devuelve 403 con SignatureDoesNotMatch.
    • Por qué ocurre: El navegador envía un Content-Type diferente al que se firmó, o la URL se firmó contra otro endpoint o región.
    • Solución: Devuelva las cabeceras firmadas junto con la URL y envíelas sin cambios; firme con el endpoint regional del bucket.
  3. Esperar una función de AWS que no existe

    • Problema: El código que llama a put_bucket_notification_configuration, o una regla de ciclo de vida con Transitions, falla.
    • Por qué ocurre: Las notificaciones de bucket no están admitidas, y solo existe la clase de almacenamiento STANDARD.
    • Solución: Consulte primero la tabla de compatibilidad (Sección 5); use una llamada de confirmación explícita en lugar de eventos, y expiración en lugar de transiciones.

Resumen

Ahora puede integrar IONOS Cloud Object Storage en TaskBoard de la forma S3, con las especificidades de IONOS CLOUD. El cliente boto3 recibe un endpoint regional explícito, así como una Access Key y una Secret Key. Los navegadores suben y descargan a través de URLs prefirmadas, por lo que la API nunca hace de proxy de los bytes, y los archivos grandes utilizan la carga multipart. Las reglas de ciclo de vida eliminan los archivos temporales y las cargas abandonadas, y usted debe consultar la tabla de compatibilidad antes de utilizar una función exclusiva de AWS.

Puntos clave:

  • Establezca siempre endpoint_url; autentíquese con una Access Key y una Secret Key, nunca con un token de portador
  • Establezca las dos variables de suma de verificación, o fije la versión de boto3 por debajo de 1.36.0
  • Las URLs prefirmadas se firman localmente; la clave de firma debe pertenecer al propietario del bucket o a un administrador
  • Utilice la carga multipart por encima del límite de una sola solicitud; añada una regla que interrumpa las cargas incompletas
  • Las reglas de ciclo de vida caducan y eliminan objetos; no existen reglas de transición

Terminología importante:

  • Access Key y Secret Key: El par de credenciales que firma cada solicitud S3; no está vinculado a una región ni a un bucket
  • URL prefirmada: Una URL que lleva una firma con límite de tiempo para una operación sobre un objeto
  • Bucket propiedad del contrato: Un bucket propiedad del propietario del contrato, en eu-central-3, eu-central-4 o us-central-1
  • Carga multipart: Una carga dividida en partes que se envían por separado y luego se combinan en un solo objeto
  • Regla de ciclo de vida: Una regla de bucket que caduca objetos, versiones no actuales o cargas incompletas tras un tiempo determinado

Próximos pasos

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

Temas relacionados: