Buckets, Keys and the Flat Namespace

What you'll learn

An S3 object is bytes plus metadata, stored under a key inside a bucket.
General purpose bucket names are global across all AWS accounts, so they must be unique — and they follow strict naming rules.
S3 has no folders: a key like sprites/grass/0252-treecko.png is one string, and the slashes only look like folders.

Section 01

Buckets and objects

S3 stores objects. An object is the data itself (a JSON card, a PNG, an 80 GiB video) plus metadata such as its content type and size.

Objects live in buckets. A bucket belongs to one AWS Region, and the data in it stays in that Region unless you copy or replicate it somewhere else.

An account can create up to 10,000 general purpose buckets by default (you can ask for more). Most applications need only a few: one per environment or data set, not one per user.

Section 02

Naming a bucket

A general purpose bucket name must be unique across every AWS account in the partition, not just yours. If someone anywhere already owns hoenn-pokedex, you can't have it.

3–63 characters: lowercase letters, numbers, hyphens (-) and dots (.).
Must begin and end with a letter or number. No uppercase, no underscores, no two dots in a row.
Can't look like an IP address, and can't use reserved prefixes (xn--, sthree-) or suffixes (-s3alias, --ol-s3).
Avoid dots unless you need them for static website hosting: they break virtual-hosted-style HTTPS certificates.

Add something that makes the name yours — a team name, the environment and a short random suffix, like hoenn-pokedex-prod-4821.

Section 03

Choosing the Region

Create the bucket in the Region closest to the users and services that read it. The Region is part of the bucket's identity: you can't move a bucket later, only copy its objects.

When your client sends a CreateBucket request to any Region other than us-east-1, S3 needs the Region repeated in CreateBucketConfiguration.LocationConstraint. Leave it out and you get IllegalLocationConstraintException.

Create a bucket in MumbaiJavaScript

import { S3Client } from "@aws-sdk/client-s3";

// One client per Region, created once and reused.
const client = new S3Client({ region: "ap-south-1" });
import { CreateBucketCommand } from "@aws-sdk/client-s3";

await client.send(
  new CreateBucketCommand({
    Bucket: "hoenn-pokedex-prod-4821",
    CreateBucketConfiguration: { LocationConstraint: "ap-south-1" },
  })
);

Section 04

Keys, not folders

Every object has a key — a UTF-8 string of up to 1,024 bytes that is unique within the bucket. The bucket is a flat map from keys to objects. The key sprites/grass/0252-treecko.png doesn't live “inside” a grass folder; the whole string is the name.

The console shows folders because it groups keys that share a prefix up to a delimiter (usually /). You'll use the same trick in code in Quest 4. Design keys so the prefixes match the way you'll list and secure data: cards/, sprites/<type>/, replays/<year>/.

Key	What it tells you
`cards/0252-treecko.json`	A Pokédex card; the number keeps cards sorted.
`sprites/grass/0252-treecko.png`	A sprite, grouped by type so you can list one type at a time.
`replays/2026/hoenn-league-final.mp4`	A replay, grouped by year for lifecycle rules later.

Keys are case-sensitive: Treecko.json and treecko.json are different objects.

Practice

Your turn

Create the bucket for the Hoenn Pokédex archive. Fix the name so it follows the naming rules — and remember that every bucket name in AWS is global, so the obvious names are already taken. Then tell S3 which Region the bucket belongs in.

A valid, unique Bucket name and CreateBucketConfiguration: { LocationConstraint: "ap-south-1" }.

// @ts-nocheck
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "ap-south-1" });
async function createArchive() {
  const command = new CreateBucketCommand({
    // ⬇️ Not a valid bucket name. Fix it (and make it unique).
    Bucket: "Hoenn_Pokedex",
    // ⬇️ The client talks to ap-south-1. Add CreateBucketConfiguration.
  });
  const response = await client.send(command);
  console.log("Bucket created at", response.Location);
}

// @ts-nocheck
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "ap-south-1" });

async function createArchive() {
  const command = new CreateBucketCommand({
    // ⬇️ Not a valid bucket name. Fix it (and make it unique).
    Bucket: "Hoenn_Pokedex",
    // ⬇️ The client talks to ap-south-1. Add CreateBucketConfiguration.

  });

  const response = await client.send(command);
  console.log("Bucket created at", response.Location);
}

Ctrl/⌘ Enter to run · simulated, no AWS callsSimulated — no AWS calls

Check

Check your understanding

Quick Quiz · one question, as many tries as you need.

A teammate creates a folder called sprites/ in the S3 console and uploads treecko.png into it. What did S3 actually store?

Choose one answer.