docs(ecs): document Podman as a Docker/Finch alternative by sAchin-680 · Pull Request #35933 · aws/aws-cdk

sAchin-680 · 2025-11-03T15:24:24Z

docs(aws-ecs): Document Podman as a Docker/Finch alternative

Add Podman configuration examples in aws-ecr-assets README
Document DOCKER_HOST requirement for both Finch and Podman
Update CONTRIBUTING.md with Podman setup instructions
Provide community-tested alternative guidance for Docker licensing concerns

Issue # (if applicable)

Reason for this change

Users are facing Docker licensing issues and seeking alternatives like Podman for CDK container builds. The current documentation only mentions Finch as a Docker alternative but lacks:

Podman configuration examples despite it being a popular, lightweight Docker alternative
Critical DOCKER_HOST environment variable requirements for both Finch and Podman
Clear guidance on community-tested alternatives for users with Docker licensing concerns

This creates a documentation gap that prevents users from successfully using Podman with CDK, even though it works with proper configuration.

Description of changes

1. Enhanced aws-ecr-assets README.md:

Added new "Docker Alternatives" section with structured examples
Documented exact Podman configuration: CDK_DOCKER=podman and DOCKER_HOST=$(podman machine inspect...)
Added missing DOCKER_HOST configuration for Finch
Included clear support level distinctions (AWS-supported vs community-tested)
Added explanatory note about DOCKER_HOST requirement for container daemon communication

2. Updated CONTRIBUTING.md:

Extended Docker replacement documentation to include Podman
Added DOCKER_HOST requirement explanation for both Finch and Podman
Provided specific configuration example for Podman setup

3. Design decisions:

Used the exact configuration validated by the issue reporter (@TrevorBurnham)
Maintained clear distinction between official AWS support (Finch) and community-tested alternatives (Podman)
Structured documentation to be copy-paste friendly for users
Positioned content logically after existing CDK_DOCKER explanation

4. Alternatives considered:

Could have only documented Podman without DOCKER_HOST - rejected because it's critical for functionality
Could have provided minimal examples - rejected in favor of complete, working configurations
Could have avoided mentioning support levels - rejected because transparency is important

Describe any new or updated permissions being added

No new or updated IAM permissions are being added. This is purely documentation enhancement.

Description of how you validated changes

Documentation validation:

Verified configuration examples match the working setup from issue (aws-ecs): Document Podman as a Docker/Finch alternative #35833
Confirmed both CONTRIBUTING.md and aws-ecr-assets README.md are updated consistently
Ensured documentation follows existing patterns and formatting
Cross-referenced with existing Finch documentation for consistency
Validated markdown formatting and code block syntax

Content validation:

Examples use the exact environment variables validated by the community
Support level messaging aligns with AWS policy (official support for Finch, community-tested for Podman)
Documentation addresses all points raised in the original issue

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

aws-cdk-automation

(This review is outdated)

sAchin-680 · 2025-11-12T12:50:42Z

Hi @pahud, @aws/aws-cdk-maintainers, and code owners

When you have a moment, could you please review this PR?

This update enhances the ECS documentation by adding Podman as a community-tested alternative to Docker/Finch, addressing configuration and setup gaps reported by users. It’s a documentation-only change aimed at improving developer experience when using CDK container builds without Docker licensing constraints.

Your feedback and review would be greatly appreciated.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

leonmk-aws

It looks like there a markdown linter has run on the docs, can you undo it to keep only the podman / finch etc.. changes ? Keeping the changes minimal allows for easier review. (And I suspect a whole section has been accidentally removed, see comments).

CONTRIBUTING.md

Pull request has been modified.

github-actions · 2025-12-05T16:38:50Z

	Tests	Passed ❌️	Skipped	Failed
Security Guardian Results	0 ran	0 passed	0 skipped	0 failed

Test	Result
No test annotations available

View Security Guardian Results

github-actions · 2025-12-05T16:38:52Z

	Tests	Passed ❌️	Skipped	Failed
Security Guardian Results with resolved templates	0 ran	0 passed	0 skipped	0 failed

Test	Result
No test annotations available

View Security Guardian Results with resolved templates

CONTRIBUTING.md

packages/aws-cdk-lib/aws-ecr-assets/README.md

Pull request has been modified.

leonmk-aws

There are still finch machine commands, one section that is deleted. Please also remove all the changes that are not related to the explanation added in this PR (blank lines being removed, * being converted to _ etc).

CONTRIBUTING.md

packages/aws-cdk-lib/aws-ecr-assets/README.md

Pull request has been modified.

- Add Podman DOCKER_HOST configuration guidance to CONTRIBUTING.md - Document Finch and Podman as Docker alternatives in ECR assets README - Clarify Finch requires OS-specific DOCKER_HOST path (no machine inspect command) - Note Podman is community-tested while Finch has official AWS support Addresses reviewer feedback - removed finch machine inspect command and all unrelated formatting changes. Fixes aws#35833 Signed-off-by: SACHIN <[email protected]>

leonmk-aws

Thank you for updating the, LGTM

mergify · 2026-01-13T12:28:36Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-01-13T12:29:09Z

mergify · 2026-01-13T12:32:59Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-01-14T09:02:32Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2026-01-14T09:02:45Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

github-actions bot added effort/small Small work item – less than a day of effort p2 beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK labels Nov 3, 2025

aws-cdk-automation requested a review from a team November 3, 2025 15:24

aws-cdk-automation previously requested changes Nov 3, 2025

View reviewed changes

sAchin-680 requested a review from aws-cdk-automation November 4, 2025 11:25

sAchin-680 changed the title ~~docs(aws-ecs): Document Podman as a Docker/Finch alternative~~ Docs(aws-ecs): Document Podman as a Docker/Finch alternative Nov 12, 2025

sAchin-680 changed the title ~~Docs(aws-ecs): Document Podman as a Docker/Finch alternative~~ docs(ecs): document Podman as a Docker/Finch alternative Nov 12, 2025

sAchin-680 force-pushed the docs/podman-docker-alternative branch from 07662b9 to 111249c Compare November 12, 2025 12:52

mazyu36 approved these changes Nov 12, 2025

View reviewed changes

pahud mentioned this pull request Nov 13, 2025

docs(contributing): add section explaining PR review process #36044

Open

1 task

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Nov 13, 2025

github-actions bot mentioned this pull request Dec 1, 2025

Monthly PR metrics report #36251

Open

leonmk-aws self-assigned this Dec 5, 2025

leonmk-aws previously requested changes Dec 5, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

sAchin-680 force-pushed the docs/podman-docker-alternative branch 2 times, most recently from e2c229a to 81caa10 Compare December 5, 2025 16:57

pahud mentioned this pull request Dec 5, 2025

CI Pending Approval - 27 PR(s) pahud/aws-cdk#11

Open

leonmk-aws previously requested changes Dec 22, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

packages/aws-cdk-lib/aws-ecr-assets/README.md Outdated Show resolved Hide resolved

packages/aws-cdk-lib/aws-ecr-assets/README.md Outdated Show resolved Hide resolved

sAchin-680 force-pushed the docs/podman-docker-alternative branch from f165e82 to fbb80e0 Compare December 25, 2025 13:21

sAchin-680 force-pushed the docs/podman-docker-alternative branch from fbb80e0 to aba1830 Compare January 5, 2026 08:36

leonmk-aws previously requested changes Jan 5, 2026

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

packages/aws-cdk-lib/aws-ecr-assets/README.md Show resolved Hide resolved

sAchin-680 force-pushed the docs/podman-docker-alternative branch from 856d27d to c0d0c38 Compare January 5, 2026 15:34

sAchin-680 force-pushed the docs/podman-docker-alternative branch from 30be8c7 to 7842766 Compare January 8, 2026 10:13

leonmk-aws approved these changes Jan 13, 2026

View reviewed changes

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Jan 13, 2026

mergify bot added 2 commits January 13, 2026 12:40

Merge branch 'main' into docs/podman-docker-alternative

fa5b64b

Merge branch 'main' into docs/podman-docker-alternative

6b64a69

mergify bot merged commit 3266504 into aws:main Jan 14, 2026
17 of 18 checks passed

github-actions bot locked as resolved and limited conversation to collaborators Jan 14, 2026

Conversation

sAchin-680 commented Nov 3, 2025

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sAchin-680 commented Nov 12, 2025

Uh oh!

leonmk-aws left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leonmk-aws left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leonmk-aws left a comment

Choose a reason for hiding this comment

Uh oh!

mergify bot commented Jan 13, 2026

Uh oh!

mergify bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

mergify bot commented Jan 13, 2026

Uh oh!

mergify bot commented Jan 14, 2026

Uh oh!

Uh oh!

github-actions bot commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aws-cdk-automation left a comment •

edited

Loading

github-actions bot commented Dec 5, 2025 •

edited

Loading

github-actions bot commented Dec 5, 2025 •

edited

Loading

mergify bot commented Jan 13, 2026 •

edited

Loading