Skip to main content

PROVISION AN S3 BUCKET FOR THE SWAMP DATASTORE

This guide shows you how to provision the S3 bucket and IAM managed policy that a Swamp repository needs before it can store its data in S3 with @swamp/s3-datastore.

Prerequisites

  • AWS credentials in the default credential chain that can create an S3 bucket and an IAM managed policy. See Authenticate to AWS with SSO if you use SSO.
  • An IAM identity (user or role) that will run Swamp against the datastore

Pull the extensions

Pull the bootstrap extension. It provides the @swamp/s3-datastore-bootstrap/provisioner behavior type and a bootstrap workflow:

swamp extension pull @swamp/s3-datastore-bootstrap --yes

The output looks like:

INF extension·pull: Pulling "@swamp/s3-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/s3-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/s3-datastore-bootstrap"@"2026.10.13.1"
INF extension·pull: Extracted 7 files:
INF extension·pull: Pulling dependency "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Pulling "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Extracted 13 files:

Then pull the datastore extension the repository will switch to:

swamp extension pull @swamp/s3-datastore --yes

The output looks like:

INF extension·pull: Pulling "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/s3-datastore"@"2026.10.13.1"
INF extension·pull: Extracted 13 files:

Define the provisioner

Create a behavior of type @swamp/s3-datastore-bootstrap/provisioner named swamp-s3-datastore-provisioner. Create and Run a Behavior shows how. Set its global arguments:

globalArguments:
  bucket_name: example-swamp-state
  region: us-east-1
  prefix: swamp

bucket_name and region are required. prefix is stored in the provisioner's state for the datastore setup step. If you do not set policy_name, the IAM managed policy is named swamp-s3-datastore-<bucket_name>.

Provision the bucket and policy

swamp behavior run swamp-s3-datastore-provisioner provision

This creates the bucket, or verifies it if it already exists, as a private bucket with versioning on, SSE-S3 encryption and public access blocked. It also creates an IAM managed policy that allows only s3:ListBucket, s3:GetObject, s3:PutObject and s3:DeleteObject on that bucket. The bucket and policy are written to the provisioner's resource state.

Attach the policy and switch the datastore

Attach the managed policy to the IAM identity that will run Swamp. Then switch the repository to the @swamp/s3-datastore type, with bucket, prefix and region set to the values used above. The Datastore Configuration reference lists every config key, including endpoint and forcePathStyle for S3-compatible services and the pullConcurrency, pushConcurrency and requestTimeoutMs tuning options.

The bootstrap extension also ships a workflow that runs the provisioner and the datastore switch in one run. See the @swamp/s3-datastore-bootstrap registry page for its inputs.

To share the new datastore between several repositories, see Set Up a Giga-Swamp.