DOC-367: Recommend virtual-hosted-style S3 addressing with AWS_ENDPOINT_URL_S3

[HarshCasper]

Summary

This PR updates the S3 documentation to recommend virtual-hosted-style addressing as the default, following AWS best practices. The key changes address contradictions in the documentation where path-style addressing was enabled alongside virtual-hosted-style endpoints.

Changes Made

1. S3 Service Documentation (src/content/docs/aws/services/s3.mdx)

• Restructured the "Path-Style and Virtual Hosted-Style Requests" section (renamed to "Configuring S3 Endpoint")
• Added prominent guidance on using AWS_ENDPOINT_URL_S3 environment variable as the recommended approach
• Reframed virtual-hosted-style as the default and recommended method (aligned with AWS recommendations)
• Moved path-style to an explicit fallback section with clear use cases (non-DNS-compliant bucket names, older SDKs)
• Added detailed SDK-specific parameter names for both addressing styles

2. Terraform Documentation (src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx)

• Removed contradictory s3_use_path_style = true setting from all configuration examples that use s3.localhost.localstack.cloud endpoint
• Added new section recommending AWS_ENDPOINT_URL_S3 for Terraform provider-aws >= 5.x
• Updated all configuration examples (Manual Configuration, Final Configuration, Endpoint Configuration, Terragrunt)
• Added clear notes about when to use path-style addressing (as an opt-in only)

3. PHP SDK Documentation (src/content/docs/aws/connecting/aws-sdks/php.md)

• Removed contradictory use_path_style_endpoint => true from the default example
• Split example into two: recommended virtual-hosted-style (default) and optional path-style (with clear context)
• Added explanation of when path-style is needed

Audit Trail

Sources Accessed

• AWS S3 Documentation: Virtual Hosting of Buckets
• Linear Ticket: DOC-367 with detailed analysis and verified behavior
• Existing Documentation:
  • src/content/docs/aws/services/s3.mdx
  • src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx
  • src/content/docs/aws/connecting/aws-sdks/php.md

Coverage Files Parsed

• src/data/coverage/s3.json - Verified S3 API operations support

Confidence & Gaps Assessment

• High Confidence: The changes align with AWS recommendations (virtual-hosted-style as default since 2020)
• Verified Behavior: The ticket author verified that AWS_ENDPOINT_URL_S3 works end-to-end with boto3, AWS CLI v2, and Terraform provider-aws v5.100.0
• No Conflicts Found: All changes follow the guidance in agents.md and maintain consistency across the documentation
• Build Verified: npm run build completed successfully with all internal links valid

Technical Justification

1. AWS Regions Requirement: Opt-in AWS regions (launched after 2019) do not support path-style addressing at all
2. AWS Recommendation: AWS officially recommends virtual-hosted-style addressing since 2020
3. Code Portability: Using AWS_ENDPOINT_URL_S3 allows the same code/config to work against both LocalStack and real AWS
4. Contradiction Eliminated: The previous documentation incorrectly combined s3.localhost.localstack.cloud (virtual-hosted endpoint) with path-style flags, which is self-contradictory

Verification

• ✅ Build completed successfully (npm run build)
• ✅ All internal links validated
• ✅ No frontmatter errors
• ✅ Followed all guidance from agents.md
• ✅ Changes limited to src/content/docs/ as required
• ✅ No configuration files modified

Impact

This change improves documentation accuracy and helps users:

• Follow AWS best practices by default
• Avoid issues when their LocalStack configurations are reused against real AWS
• Understand when and why to use path-style addressing (as an explicit opt-in)
• Use modern SDK features (AWS_ENDPOINT_URL_S3) that work across tools without code changes

---

Important

An AI agent generated this pull request. Review all changes before you merge.

• Linear ticket: DOC-367
• Workflow run: https://github.com/localstack/localstack-docs/actions/runs/31018723809

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	2d729a6
Status:	✅  Deploy successful!
Preview URL:	https://5c6e77b8.localstack-docs.pages.dev
Branch Preview URL:	https://docs-agent-doc-367.localstack-docs.pages.dev

View logs

[quetzalliwrites]

FYI, it's marking Harsh as the creator of the PR but that is incorrect, it's the agent workflow bot. We need to fix this.

[bentsku]

I suppose this is going to remove questions from users about using path style, but in most cases where the stack is a little bit complicated network wise, virtual host style makes it much more complicated. At least there is still some visibility about path style I suppose.

If we see more reports from users we can consider adapting. I just have a few comments on the content itself

[bentsku]

uppercase letters are not supported in LocalStack, this was a very old feature of AWS that has been removed ages ago

[bentsku]

you can use the prefixed endpoint with path style, it's even better? Not sure why this is specified

[bentsku]

one of the big case we have in Docker compose: as you need to specify the service name, you cannot use wildcard DNS there, and it was one of the biggest source of incoming reports from users.