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
boto3yrequests curly 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
PUTse 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:
-
InvalidTrailer en cada carga
- Problema:
put_objectyupload_filefallan 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_requiredyAWS_RESPONSE_CHECKSUM_VALIDATION=when_required, o fijeboto3<=1.35.99(Sección 1.2).
- Problema:
-
SignatureDoesNotMatch en cargas preautorizadas
- Problema: El
PUTdel navegador devuelve403conSignatureDoesNotMatch. - Por qué ocurre: El navegador envía un
Content-Typediferente 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.
- Problema: El
-
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 conTransitions, 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.
- Problema: El código que llama a
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-4ous-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: