Upload an S3 object with metadata

Part 14 of AWS from Zero. Today we upload one object with metadata.

S3 object metadata is information attached to the object. Some metadata is system-managed, like size and last modified time. You can also add custom metadata.

What we are learning

We will:

1. Create a bucket.
2. Upload one object.
3. Add custom metadata.
4. Inspect that metadata with head-object.
5. Clean everything up.

Before you run it

aws sts get-caller-identity
REGION="ap-south-1"
BUCKET="aws-zero-object-metadata-12345"

Create the bucket:

aws s3api create-bucket \
  --bucket "$BUCKET" \
  --region "$REGION" \
  --create-bucket-configuration LocationConstraint="$REGION"

Create a file:

echo "metadata demo" > notes.txt

Upload with metadata

Use put-object so the metadata is explicit:

aws s3api put-object \
  --bucket "$BUCKET" \
  --key notes.txt \
  --body notes.txt \
  --content-type "text/plain" \
  --metadata "lesson=aws-from-zero,track=s3"

This uploads the file and attaches two custom metadata values:

• lesson=aws-from-zero
• track=s3

Inspect the result

Use head-object:

aws s3api head-object \
  --bucket "$BUCKET" \
  --key notes.txt

Ask for only the fields we care about:

aws s3api head-object \
  --bucket "$BUCKET" \
  --key notes.txt \
  --query "{Size:ContentLength,Type:ContentType,Metadata:Metadata}" \
  --output table

The important part is that S3 returns metadata without sending the object body back.

One tiny variation

Upload another object under a folder-like prefix:

aws s3api put-object \
  --bucket "$BUCKET" \
  --key lessons/s3/notes.txt \
  --body notes.txt \
  --content-type "text/plain" \
  --metadata "lesson=aws-from-zero,track=s3,path=prefix-demo"

S3 does not have real folders in the normal filesystem sense. The key is just a string that contains slashes.

Common mistake

Metadata is not the same as tags.

• Metadata is stored with the object and returned by object metadata operations.
• Tags are separate key-value pairs used for lifecycle rules, cost allocation, permissions, and automation.

We will cover object tagging later because it deserves its own small lesson.

Cleanup

Remove both objects:

aws s3 rm "s3://$BUCKET/" --recursive

Delete the bucket:

aws s3api delete-bucket \
  --bucket "$BUCKET" \
  --region "$REGION"

Remove the local file:

rm notes.txt

Next, we will use head-object more deliberately to inspect objects without downloading them.