Buckets

The examples use a bucket named uploads in the storefront Project and the web Application that stores customer images in it.

What you can do

• Add a bucket in the Project config and link it to any number of Services.
• Read the same six Outputs on every target, so one codebase works on a Server and in a cloud.
• Allow web pages to upload straight from a browser.
• Give a bucket on a Server its own Domain, and rotate its key.
• Back up and restore a bucket on a Server.
• Use a bucket you already have in a cloud, as given.

Add a bucket

A bucket is created only by the Project config. The console has no add button for it.

1. Write it in the Project config

   Add an entry with kind: bucket, and link its Outputs under the Service that uses it:

   version: 1
   services:
     uploads:
       kind: bucket
     web:
       kind: web
       source:
         github: northwind/storefront
       env:
         - S3_BUCKET: uploads.name
         - AWS_REGION: uploads.region
         - S3_ENDPOINT: uploads.endpoint
         - S3_FORCE_PATH_STYLE: uploads.path_style
         - AWS_ACCESS_KEY_ID: uploads.access_key_id
         - AWS_SECRET_ACCESS_KEY: uploads.secret_access_key

2. Review and apply the Plan

   Save the config in Cloudgate, or push it to the Config branch. Each Environment shows a Plan that creates the bucket; press Apply.

3. Deploy the Service

   Deploy web. Each linked value reaches its container at the deploy and is never saved on the Service.

What each Output is

Output	On a Server	On AWS
name	the bucket’s real name, made by Cloudgate	the same
region	us-east-1	the Environment’s region
endpoint	the bucket’s Domain while it has one, else its internal URL	https://s3.<region>.amazonaws.com
access_key_id, secret_access_key	the bucket’s key	no value: the Service’s task role gives access
path_style	"true"	"false"

There is no url. On Google Cloud the bucket is a Cloud Storage bucket with its own key, shared by every Service that links it.

Open a bucket’s screen

A bucket has one screen, reached from its Environment’s Services tab. It shows its Real name, Region and Access, and these cards:

• Key: the one key every linking Service reads and writes with, and Rotate key.
• Browser uploads: the web origins trusted to upload straight from a browser.
• Domains: where a bucket on a Server answers S3 requests from the internet.
• Volume backups and Restore, on a Server.

cloudgate.octabyte.app/buckets/…

Let a browser upload to the bucket

On Browser uploads, press Add origin and enter the origin as a browser sends it, such as https://shop.northwind.example, with no path. Origins are set per Environment and start empty.

Give a bucket on a Server a Domain

A bucket on a Server is reached only from that Server until you press Add a domain on its Domains card. Presigned URLs and browser uploads need it: a browser cannot reach the internal URL.

Rotate a bucket’s key

Press Rotate key on the Key card. Cloudgate makes a new key, then deploys every Service that links the bucket again with it. If that fails, the Services are put back on the old key.

Where a bucket lives

Target	What Cloudgate makes
Server	its own Garage storage container and volume, S3-compatible
AWS	an S3 bucket, versioning off, Block Public Access on; no key
Google Cloud	a Cloud Storage bucket with its own service account and key

On AWS a presigned URL is signed with the task role’s short-lived credentials, so it stops working when they expire. Make one just before it is used.

Use a bucket you already have

When a Plan would create a bucket in a Cloud account, choose Use an existing bucket on that line and name it. Cloudgate never changes it. On Google Cloud you add one access grant yourself; the bucket’s Access card shows the exact command and checks it. Deleting the Service leaves the bucket and its files as they were.

Delete a bucket

Remove the entry from the Project config, or delete it from its screen with Delete bucket, confirming its name. A bucket that holds files is kept and named in the report unless you tick Also delete its files.

What you cannot do

• Create a bucket from a console button: use the Project config.
• Link a bucket in another place: a Service and its bucket must be on the same Server, or in the same Cloud account and region. The Plan refuses it and names the variable.
• Use a key on AWS: access is the Service’s own role.
• Change a bucket’s policy, CORS or versioning from a linked Service.
• Count on a presigned URL on AWS lasting more than about an hour.

Related pages

• The Project config and Plans.
• Wired variables.
• Volume backups and restore.
• Databases, linked the same way.
• Cloud accounts.

Questions

How do I create a bucket in the console?

You do not press a button for it: a bucket is created by the Project config. Add an entry with kind bucket and apply the Plan.

Why are the key variables empty on AWS?

On AWS a bucket has no key. Each Service reaches it with its own task role, so variables linked to access_key_id and secret_access_key are left unset and the AWS SDK finds its credentials by itself.

Does deleting a bucket delete its files?

Only if you tick Also delete its files. A bucket that still holds files is otherwise kept, and the Delete report names it.