Storage

Declare a named object store with the workload, and the platform provisions and binds the concrete bucket when that workload deploys. Application code resolves the logical name; it does not carry a provider bucket name or storage credential.

Declare a bucket

Storage requirements live in infra/requirements.json, next to database, event, and secret requirements:

{
  "$schema": "https://putnami.dev/schemas/putnami-infra.json",
  "protocolVersion": 2,
  "storage": [
    {
      "name": "uploads",
      "access": "readwrite"
    }
  ]
}

name is the stable identity application code resolves. Renaming it requests a different binding; it is not a rename of the existing provider bucket. Keep the logical name stable across releases.

Deploy and resolve

putnami deploy carries the requirement with the release. Before the workload serves, the platform:

  1. resolves the workspace's runtime project and environment;
  2. provisions or reuses the bucket recorded for the project and logical name;
  3. verifies that the binding is ready and current;
  4. makes the credential-free binding available through resolved configuration;
  5. starts the revision with the workload identity authorized for the declared access.

The resolved document identifies the logical name, backend, concrete bucket, workload identity mode, and whether signed URLs are enabled. Provider credentials, service-account keys, and operator overrides are never application configuration.

Change storage safely

Change Result
Deploy the same declaration again Reuses the recorded binding
Add a logical name Provisions and binds another bucket
Change application code only Keeps the existing bucket
Rename or remove a logical name Treat as a data migration or retirement; do not assume the old data moves

Bucket migration and retirement are controlled operations. A deployment does not infer that two different logical names contain the same data.

Current boundary

Managed GCS bindings are the supported Cloud path. The platform owns provisioning and workload access; application-level object layout, signed-URL policy, and data retention choices remain application concerns unless a workspace policy fixes them.

Next