Pulp Engine v0.22.0 — Release Notes

First-class S3 object storage for asset binaries

Asset binaries (uploaded images) can now be stored in an S3-compatible bucket instead of the local filesystem. This is configured independently of the template/metadata storage backend (STORAGE_MODE) via a new ASSET_BINARY_STORE environment variable.

What changed

New ASSET_BINARY_STORE configuration (default: filesystem)

• filesystem — existing behaviour; binaries written to ASSETS_DIR on disk. Zero change for existing deployments.
• s3 — binaries stored in an S3-compatible bucket. Eliminates the shared NFS volume requirement for multi-instance deployments.

Conditional static file serving

In ASSET_BINARY_STORE=filesystem mode the API continues to serve GET /assets/* directly (unchanged). In s3 mode the static route is not registered — assets are served from the bucket via S3_PUBLIC_URL, not proxied through the API.

Fail-fast startup probe

When ASSET_BINARY_STORE=s3, the API sends a HeadBucket request to verify the bucket is accessible before accepting traffic. An inaccessible bucket causes an immediate startup failure with a clear error message. This is surfaced at GET /health/ready (storage check).

New environment variables

Variable	Default	Notes
ASSET_BINARY_STORE	filesystem	filesystem or s3
S3_BUCKET	—	Required when s3
S3_REGION	—	Required when s3
S3_ACCESS_KEY_ID	—	Required when s3
S3_SECRET_ACCESS_KEY	—	Required when s3
S3_ENDPOINT	—	Optional; custom S3-compatible endpoint (MinIO, R2). When set, S3_PUBLIC_URL is required.
S3_PATH_STYLE	false	Set true for MinIO path-style. When true, S3_PUBLIC_URL is required.
S3_PUBLIC_URL	—	Base URL for public asset delivery. Required when S3_ENDPOINT is set or S3_PATH_STYLE=true. Optional for standard AWS S3 — auto-derived as https://{bucket}.s3.{region}.amazonaws.com.

All existing variables (ASSETS_DIR, ASSETS_BASE_URL) are unchanged in filesystem mode.

Supported providers

• AWS S3 — standard path-style or virtual-hosted-style
• MinIO (self-hosted) — set S3_ENDPOINT + S3_PATH_STYLE=true + S3_PUBLIC_URL
• Cloudflare R2 — set S3_ENDPOINT + S3_PUBLIC_URL
• Any S3-compatible provider that accepts PutObject, DeleteObject, HeadBucket

Required permissions

The credentials must have:

• Object-level: s3:PutObject, s3:DeleteObject on objects in the bucket.
• Bucket-level: access to perform HeadBucket (used for the startup availability probe). For AWS S3, this is documented in the HeadBucket API reference. For MinIO and other compatible providers, equivalent bucket-level access is required.

Public-bucket requirement

Objects must be publicly readable at S3_PUBLIC_URL. The API serves rendered PDFs that reference asset URLs; Puppeteer fetches those URLs without auth headers. Private buckets with presigned GET URLs are not supported in this release.

Deployment topologies after this change

Topology	STORAGE_MODE	ASSET_BINARY_STORE	NFS required?
Local dev / simple self-hosted	file	filesystem	No
Single-instance DB	postgres / sqlserver	filesystem	No
Multi-instance DB + NFS	postgres / sqlserver	filesystem	Yes (unchanged)
Multi-instance DB + S3	postgres / sqlserver	s3	No (new)

Migration note for existing deployments

Existing deployments are unaffected — ASSET_BINARY_STORE defaults to filesystem and all behaviour is unchanged.

Switching an existing deployment from filesystem to s3 does not automatically migrate binaries. Existing AssetRecord.url values still point to /assets/{filename} URLs. Without a manual migration, those URLs become inaccessible after the switch.

Options for existing deployments switching to S3:

1. Greenfield: If existing asset data is expendable, deploy fresh in S3 mode with an empty asset store.
2. Manual cutover: Copy binaries from ASSETS_DIR to the S3 bucket, update stored URL values in the database to the new S3 URLs, then switch ASSET_BINARY_STORE=s3. Requires a maintenance window.

No automated migration tool is provided in this release.

Upgrading

This is a backwards-compatible release. No database schema changes. No changes to the API surface.

1. Update to v0.22.0.
2. For S3 deployments: add ASSET_BINARY_STORE=s3 and the required S3 env vars. Verify the bucket is accessible.
3. For filesystem deployments: no action required. All defaults are preserved.

See docs/deployment-guide.md § Object Storage for full configuration reference and provider examples.