add bucket policy doc

2026-10-13 17:48:29 +02:00 · 2026-02-25 13:35:44 -08:00
1 parent 62790fc245
commit 50f0754269
@@ -0,0 +1,283 @@
+# S3 Bucket Policies
+
+SeaweedFS supports AWS S3-compatible bucket policies for controlling access to buckets and objects at the bucket level.
+
+## Overview
+
+Bucket policies allow you to grant or deny permissions for S3 operations on a bucket and its objects. They are resource-based policies that complement user-level IAM policies.
+
+## AWS CLI Setup
+
+First, configure the AWS CLI to connect to your SeaweedFS S3 endpoint:
+
+```bash
+aws configure --profile seaweedfs
+```
+
+Enter your credentials and configure the endpoint:
+
+```bash
+AWS Access Key ID: your_access_key
+AWS Secret Access Key: your_secret_key
+Default region name: us-east-1
+Default output format: json
+```
+
+Then use this profile with an endpoint URL for all commands (or configure it in your AWS config file):
+
+```bash
+export AWS_PROFILE=seaweedfs
+alias s3="aws s3 --endpoint-url http://localhost:8333"
+alias s3api="aws s3api --endpoint-url http://localhost:8333"
+```
+
+## API Operations
+
+### Get Bucket Policy
+
+Retrieve the current bucket policy:
+
+```bash
+aws s3api get-bucket-policy \
+  --bucket my-bucket \
+  --endpoint-url http://localhost:8333
+```
+
+Output:
+```json
+{
+  "Policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"s3:GetObject\",\"Resource\":\"arn:aws:s3:::my-bucket/*\"}]}"
+}
+```
+
+To view the policy in readable format:
+
+```bash
+aws s3api get-bucket-policy \
+  --bucket my-bucket \
+  --endpoint-url http://localhost:8333 \
+  --output text | jq .Policy -r | jq .
+```
+
+### Put Bucket Policy
+
+Set or update a bucket policy from a file:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy file://policy.json \
+  --endpoint-url http://localhost:8333
+```
+
+Or inline:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Sid": "PublicRead",
+        "Effect": "Allow",
+        "Principal": "*",
+        "Action": "s3:GetObject",
+        "Resource": "arn:aws:s3:::my-bucket/*"
+      }
+    ]
+  }' \
+  --endpoint-url http://localhost:8333
+```
+
+### Delete Bucket Policy
+
+Remove the bucket policy:
+
+```bash
+aws s3api delete-bucket-policy \
+  --bucket my-bucket \
+  --endpoint-url http://localhost:8333
+```
+
+## Policy Document Format
+
+Bucket policies use the standard AWS S3 policy format with the following structure:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "OptionalStatementId",
+      "Effect": "Allow|Deny",
+      "Principal": "string or *",
+      "Action": ["s3:action1", "s3:action2"],
+      "Resource": ["arn:aws:s3:::bucket-name", "arn:aws:s3:::bucket-name/*"],
+      "Condition": {
+        "condition-operator": {
+          "condition-key": ["value"]
+        }
+      }
+    }
+  ]
+}
+```
+
+### Key Components
+
+- **Version**: Must be `"2012-10-17"` (AWS policy language version)
+- **Sid**: Optional statement identifier for documentation
+- **Effect**: `Allow` or `Deny` - the action's result
+- **Principal**: Who the policy applies to (`"*"` for public, or specific user/role ARNs)
+- **Action**: S3 operations (e.g., `s3:GetObject`, `s3:PutObject`)
+- **Resource**: Bucket or object paths
+  - `arn:aws:s3:::bucket-name` - for bucket operations
+  - `arn:aws:s3:::bucket-name/*` - for all objects in the bucket
+  - `arn:aws:s3:::bucket-name/path/to/object` - for specific objects
+  - Simplified formats: `bucket-name`, `bucket-name/*` are also accepted
+- **Condition**: Optional conditions for when the policy applies
+
+## Common Examples
+
+### Public Read Access
+
+Allow anyone to read objects in a bucket:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Principal": "*",
+        "Action": "s3:GetObject",
+        "Resource": "arn:aws:s3:::my-bucket/*"
+      }
+    ]
+  }' \
+  --endpoint-url http://localhost:8333
+```
+
+### Restrict by IP Address
+
+Allow reads only from specific IP addresses:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Principal": "*",
+        "Action": "s3:GetObject",
+        "Resource": "arn:aws:s3:::my-bucket/*",
+        "Condition": {
+          "IpAddress": {
+            "aws:SourceIp": ["192.168.1.0/24"]
+          }
+        }
+      }
+    ]
+  }' \
+  --endpoint-url http://localhost:8333
+```
+
+### Require HTTPS
+
+Allow access only over secure connections:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Principal": "*",
+        "Action": ["s3:GetObject", "s3:PutObject"],
+        "Resource": "arn:aws:s3:::my-bucket/*",
+        "Condition": {
+          "Bool": {
+            "aws:SecureTransport": "true"
+          }
+        }
+      }
+    ]
+  }' \
+  --endpoint-url http://localhost:8333
+```
+
+### Deny Unencrypted Uploads
+
+Require encryption for all uploads:
+
+```bash
+aws s3api put-bucket-policy \
+  --bucket my-bucket \
+  --policy '{
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Deny",
+        "Principal": "*",
+        "Action": "s3:PutObject",
+        "Resource": "arn:aws:s3:::my-bucket/*",
+        "Condition": {
+          "StringNotEquals": {
+            "s3:x-amz-server-side-encryption": "AES256"
+          }
+        }
+      }
+    ]
+  }' \
+  --endpoint-url http://localhost:8333
+```
+
+## Supported S3 Actions
+
+Common actions in bucket policies:
+
+- **Object Operations**: `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`
+- **Bucket Operations**: `s3:ListBucket`, `s3:CreateBucket`, `s3:DeleteBucket`
+- **ACL Operations**: `s3:PutObjectAcl`, `s3:GetObjectAcl`
+- **Multipart Operations**: `s3:CreateMultipartUpload`, `s3:UploadPart`, `s3:CompleteMultipartUpload`
+- **Object Tagging**: `s3:GetObjectTagging`, `s3:PutObjectTagging`
+- **Versioning**: `s3:GetObjectVersion`, `s3:PutObjectVersionAcl`
+
+## Policy Validation
+
+SeaweedFS validates bucket policies for:
+
+- Correct policy document version (`2012-10-17`)
+- Presence of at least one statement
+- Required Principal field
+- Resources matching the bucket name
+- S3 action prefixes
+- Valid effect values (Allow/Deny)
+
+## Integration with IAM
+
+Bucket policies work alongside IAM policies (defined at [[S3 Credentials]]) for comprehensive access control:
+
+- **Bucket Policies**: Resource-based, grant access across users
+- **IAM Policies**: User-based, define what users can do
+- **Evaluation**: Access is allowed only if both allow the operation (or if bucket policy explicitly allows and IAM doesn't deny)
+
+See [[Amazon IAM API]] for more on IAM integration.
+
+## Storage
+
+Bucket policies are stored as metadata in the filer alongside bucket configuration, ensuring they persist across server restarts.
+
+## See Also
+
+- [[Amazon S3 API]] - S3 API overview
+- [[S3 Credentials]] - S3 authentication
+- [[Amazon IAM API]] - User and role management
+- [[S3 API FAQ]] - Common S3 questions
@@ -93,6 +93,7 @@
 * [[S3 Credentials]] (`-s3.config`)
 * [[OIDC Integration]] (`-s3.iam.config`)
 * [[S3 Policy Variables]]
+* [[S3 Bucket Policies]]
 * [[Amazon IAM API]]
 * [[AWS IAM CLI]]