Coder Legion - Recent posts tagged bucket

S3 Policies Explained: Bucket Policies vs IAM Policies vs ACLs

Tue, 21 Apr 2026 02:19:56 +0000

S3 has three overlapping access control systems — bucket policies, IAM policies, and ACLs — and the interaction between them confuses most people the first time. Here's how each one works, when to use which, and the JSON to copy for the most common scenarios.

The three access control layers

Every S3 request is evaluated against all applicable policies. If any of them explicitly deny the request, it's denied. Otherwise, at least one policy must explicitly allow it.

Mechanism	Attached to	Written by	Best for
Bucket policies	The S3 bucket	Bucket owner	Cross-account access, public access, IP restrictions
IAM policies	IAM users/roles/groups	Account admin	Controlling what your own users and services can do
ACLs	Buckets or objects	Object owner	Legacy use only — AWS recommends disabling these

The rule of thumb: Use IAM policies for your own users, bucket policies for external access or bucket-wide rules, and ignore ACLs unless you're dealing with legacy configurations.

Anatomy of an S3 policy

Every policy is a JSON document with these fields:

Version — always "2012-10-17" (the current policy language version)
Statement — an array of permission rules, each containing:
- Effect — "Allow" or "Deny"
- Principal — who the rule applies to ("*" for everyone, or a specific ARN)
- Action — which S3 operations (s3:GetObject, s3:PutObject, etc.)
- Resource — which bucket/objects (specified as an ARN)
- Condition (optional) — extra constraints like IP range, encryption type, or request origin

Common policies with working JSON

Public read-only access

Makes all objects in a bucket publicly readable. Use this for static website hosting or public assets:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

This allows anyone to read objects but not list the bucket contents, upload, or delete. The /* in the Resource means all objects inside the bucket.

Deny uploads without encryption

Forces all uploaded objects to use server-side encryption. Note: this uses Deny + a StringNotEquals condition, not Allow:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyUnencryptedUploads",
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::my-bucket/*",
      "Condition": {
        "StringNotEquals": {
          "s3:x-amz-server-side-encryption": "AES256"
        }
      }
    }
  ]
}

This is the correct pattern. A common mistake is using Allow with a StringEquals condition — that permits encrypted uploads but doesn't block unencrypted ones if another policy allows s3:PutObject.

Scoped access for a specific IAM user

Grants a single user read and write access to a bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UserReadWrite",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/deploy-bot"
      },
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::my-bucket/*"
    },
    {
      "Sid": "UserListBucket",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/deploy-bot"
      },
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-bucket"
    }
  ]
}

Note the two statements: object-level actions use my-bucket/* (objects inside), while ListBucket uses my-bucket (the bucket itself). Mixing these up is a common source of "Access Denied" errors.

Restrict access by IP range

Allows access only from your office or VPN IP range:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RestrictToOfficeIP",
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::my-bucket",
        "arn:aws:s3:::my-bucket/*"
      ],
      "Condition": {
        "NotIpAddress": {
          "aws:SourceIp": "203.0.113.0/24"
        }
      }
    }
  ]
}

Bucket policy vs IAM policy: when to use which

Scenario	Use
Grant another AWS account access to your bucket	Bucket policy (cross-account)
Make a bucket publicly readable	Bucket policy (Principal: `*`)
Control what your CI/CD pipeline can do	IAM policy on the pipeline's IAM role
Restrict access by IP or VPN	Bucket policy with Condition
Give a Lambda function access to a bucket	IAM policy on the Lambda execution role
Deny all public access organization-wide	S3 Block Public Access (account-level setting)

In general: if the question is "who can access this bucket?", use a bucket policy. If the question is "what can this user/role do?", use an IAM policy.

Common mistakes

Forgetting S3 Block Public Access. Even if your bucket policy allows public reads, the account-level Block Public Access setting overrides it. Check this first when public access isn't working.
Resource ARN mismatch. s3:ListBucket needs the bucket ARN (arn:aws:s3:::my-bucket), while s3:GetObject needs the object ARN (arn:aws:s3:::my-bucket/*). This trips up almost everyone.
Using ACLs. AWS recommends disabling ACLs on new buckets (S3 Object Ownership: "Bucket owner enforced"). Bucket policies and IAM policies cover every use case that ACLs used to handle, with better auditability.
Overly broad wildcards. "Action": "s3:*" with "Resource": "*" is an admin-level policy. Scope both to the specific actions and bucket you need.

The AWS Policy Generator can help you build policies interactively if you're not sure about the syntax.

Deploy a Nanoc Static Site to S3 with GitHub Actions

Mon, 13 Apr 2026 22:47:12 +0000

Deploying a static site to S3 manually means running aws s3 sync from your laptop every time you make a change. That gets old fast. GitHub Actions can automate the entire flow: push to main, and the site builds and deploys itself.

This guide walks through the full setup for a Nanoc site, but the S3 + GitHub Actions pattern works for any static site generator.

Source code on GitHub

What you need before starting

An AWS account with an S3 bucket configured for static website hosting
An IAM user with scoped permissions (created in the steps below)
A GitHub repository containing your Nanoc source code

Step 1: Configure the S3 bucket policy

Your bucket needs a policy that allows public read access to its contents. Apply this to the bucket in the S3 console under Permissions > Bucket Policy:

{
  "Version": "2008-10-17",
  "Id": "PolicyForPublicWebsiteContent",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::docsite-github-action/*"
    }
  ]
}

Replace docsite-github-action with your actual bucket name.

Step 2: Create a scoped IAM user

Create a dedicated IAM user for GitHub Actions — don't use your root credentials. Attach this policy, which gives the minimum permissions needed for s3 sync:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessToGetBucketLocation",
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation"],
      "Resource": ["arn:aws:s3:::*"]
    },
    {
      "Sid": "AccessToWebsiteBuckets",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::docsite-github-action",
        "arn:aws:s3:::docsite-github-action/*"
      ]
    }
  ]
}

Step 3: Add AWS credentials to GitHub Secrets

In your GitHub repository, go to Settings > Secrets and variables > Actions and add two repository secrets:

AWS_ACCESS_KEY_ID — your IAM user's access key
AWS_SECRET_ACCESS_KEY — the corresponding secret key

These are injected into the workflow at runtime. They never appear in logs.

Step 4: Create the GitHub Actions workflow

Create .github/workflows/deploy.yml in your repository:

name: Nanoc Compile and Upload to S3

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2

      - name: Set up Ruby and Nanoc
        run: |
          sudo apt-get update
          sudo apt-get install -y ruby-full build-essential zlib1g-dev
          sudo gem install bundler
          sudo gem install nanoc
          sudo gem install adsf
          sudo gem install kramdown

      - name: Build Nanoc Website
        run: |
          ls
          cd tutorial && nanoc

      - name: Set AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ap-south-1

      - name: Push to S3
        run: aws s3 sync tutorial/output/ s3://docsite-github-action

The workflow triggers on every push to main. It installs Ruby and Nanoc, compiles the site, and syncs the output directory to your S3 bucket.

Alternatives to consider

This setup works well for simple static sites, but depending on your needs, other approaches might be a better fit:

Approach	When to use it
S3 + CloudFront	You need HTTPS and a CDN for global performance
Vercel / Netlify	You want zero-config deploys with preview URLs for every PR
GitHub Pages	You don't need AWS and want the simplest possible hosting
AWS Amplify	You want managed CI/CD with automatic branch deploys on AWS

S3 alone doesn't give you HTTPS — you'd need CloudFront in front of it for that. If HTTPS and preview deployments matter to you, Vercel or Netlify will save you time.

Common pitfalls

Forgetting to enable static website hosting on the S3 bucket — without it, S3 serves files as downloads instead of web pages.
Overly broad IAM permissions — scope the policy to your specific bucket, not s3:* on *.
Cache invalidation — s3 sync updates files but doesn't invalidate CloudFront caches. If you add CloudFront later, add aws cloudfront create-invalidation to the workflow.
Region mismatch — set aws-region in the workflow to match your bucket's region.

The complete workflow YAML and policies are in the repo.