feat: Add --container-dns option to sam local invoke,start-api, and start-lambda commands by KandarpAjvalia · Pull Request #8878 · aws/aws-sam-cli · GitHub
Skip to content

feat: Add --container-dns option to sam local invoke,start-api, and start-lambda commands#8878

Merged
reedham-aws merged 18 commits into
aws:developfrom
KandarpAjvalia:feat/add-dns-option-clean
Apr 2, 2026
Merged

feat: Add --container-dns option to sam local invoke,start-api, and start-lambda commands#8878
reedham-aws merged 18 commits into
aws:developfrom
KandarpAjvalia:feat/add-dns-option-clean

Conversation

@KandarpAjvalia

Copy link
Copy Markdown
Contributor

This change adds support for custom DNS server configuration in Lambda containers when using the sam local start-lambda command. Users can now specify one or more DNS servers that will be configured in the Docker containers running their Lambda functions.

Usage:

sam local start-lambda --dns 8.8.8.8 --dns 1.1.1.1

The --dns parameter can be specified multiple times to configure multiple DNS servers. The DNS servers are passed to the Docker container and will be used for name resolution by Lambda functions.

Testing:

  • Integration tests: test_start_lambda_dns.py verifies containers are created with correct DNS configuration
  • Tests are NOT marked as tier1 per recommendation

Which issue(s) does this change fix?

No existing GitHub issue.

Our internal tooling invokes sam local start-lambda and requires custom DNS configuration for proper name resolution in our development environment. Currently, SAM CLI does not provide a way to pass custom DNS servers to the Lambda container, which blocks local testing scenarios that depend on internal DNS resolution.

Why is this change necessary?

When running Lambda functions locally via sam local start-lambda, the container uses the default Docker DNS configuration (typically the host's DNS or Docker's embedded DNS). This creates problems for development environments that require custom DNS servers for internal service discovery

How does it address the issue?

This PR adds a --dns option to the sam local start-lambda command that:

  1. Follows existing patterns: Implemented the same way as other Docker options like --docker-network and --add-host
  2. Scoped appropriately: Only added to start-lambda (not build/invoke/start-api)
  3. Supports multiple DNS servers: The option can be passed multiple times (--dns 8.8.8.8 --dns 1.1.1.1)

What side effects does this change have?

No side effects, it's a new optional parameter users can pass

Mandatory Checklist

PRs will only be reviewed after checklist is complete

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

Kandarp Ajvalia added 10 commits December 12, 2025 15:49
This change adds support for specifying custom DNS servers for Lambda
containers when running locally. The --dns option can be passed multiple
times to configure multiple DNS servers.

Example usage:
  sam local invoke --dns 8.8.8.8 --dns 1.1.1.1

The dns parameter is threaded through the invoke context, lambda runner,
runtime, and container layers to properly configure the Docker container
with the specified DNS servers.
This extends the --dns option support to the start-lambda command,
allowing users to specify custom DNS servers when running the local
Lambda service endpoint.

Example usage:
  sam local start-lambda --dns 8.8.8.8 --dns 1.1.1.1

The dns parameter is threaded through the start-lambda CLI to the
invoke context, consistent with the implementation in the invoke
command.
The --dns option is only needed for sam local start-lambda and not
for the invoke command. This removes the dns parameter from the
invoke CLI while keeping the underlying infrastructure support
for start-lambda.
- Add integration test (test_start_lambda_dns.py) to verify DNS option
  works correctly with sam local start-lambda
- Update unit tests to include dns parameter in test assertions
- Tests are not marked as tier1 to avoid running in all PR workflows

The integration test verifies that:
1. start-lambda service starts successfully with custom DNS servers
2. Lambda functions can be invoked when DNS is configured
3. Multiple invocations work correctly with DNS settings
- Add smoke test (test_invoke_function_with_custom_dns) that verifies
  DNS flag is accepted and functions invoke successfully
- Add container inspection test (test_dns_configured_in_container) that
  checks Docker container DNS config using container.attrs['HostConfig']['Dns']
- Container inspection follows pattern from test_start_lambda.py
- Note: Container inspection may have timing issues in some environments
  as containers exit quickly after execution

Updated unit tests to include dns parameter
Remove redundant comments and flaky markers from test methods.
The tests are stable and don't need reruns.
Change dns parameter type from Optional[list] to Optional[tuple]
to match the actual tuple type passed from CLI (Click multiple=True).
The conversion to list happens when passing to Docker SDK.

This follows the same pattern as other parameters where Click returns
tuple, which is then converted to the appropriate type for Docker.
This change adds support for custom DNS server configuration in Lambda
containers when using the 'sam local start-lambda' command. Users can now
specify one or more DNS servers that will be configured in the Docker
containers running their Lambda functions.

Usage:
  sam local start-lambda --dns 8.8.8.8 --dns 1.1.1.1

The --dns parameter can be specified multiple times to configure multiple
DNS servers. The DNS servers are passed to the Docker container and will
be used for name resolution by Lambda functions.

Testing:
- Integration tests: test_start_lambda_dns.py verifies containers are
  created with correct DNS configuration
- Tests are NOT marked as tier1 per recommendation
Moved --dns option from shared docker_click_options() to be a
command-specific option for sam local start-lambda. This avoids
the need to add tests for sam build, sam local invoke, and
sam local start-api commands.

Changes:
- Removed --dns from docker_click_options() in _utils/options.py
- Added --dns as a click.option decorator directly in start_lambda/cli.py
- Updated unit tests to include dns=None parameter in assertions
- Regenerated schema to reflect DNS only in start-lambda command
- Applied code formatting (black) to integration test and runtime.py

All 6,959 unit tests passing.
@KandarpAjvalia KandarpAjvalia requested a review from a team as a code owner March 30, 2026 22:15
@github-actions github-actions Bot added area/local/start-api sam local start-api command area/local/invoke sam local invoke command area/local/start-invoke area/schema JSON schema file pr/external stage/needs-triage Automatically applied to new issues and PRs, indicating they haven't been looked at. labels Mar 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes more sense to be called container-dns. I'm seeing other container- parameters and it sounds reasonable to keep that consistent.

Also, is this something that makes sense for local start-api and local invoke too? We have local_common_options for options to be passed to all 3 commands: https://github.com/aws/aws-sam-cli/blob/develop/samcli/commands/local/cli_common/options.py#L46 (You add it there as a click.option in that file instead of here). You still need to add it down below as parameters, and you would have to add it in the cli.py files for those other commands too.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, I agree with your feedback, I've addressed it in the follow up commits on this branch

I've also added integ tests for the three sam local commands

Kandarp Ajvalia added 8 commits March 31, 2026 16:14
…local commands

- Rename --dns option to --container-dns for consistency with other container options (--container-host, --container-host-interface)
- Move option from docker_click_options() to local_common_options() to make it available for all three local commands: invoke, start-api, and start-lambda
- Update all parameter names throughout codebase from dns to container_dns
- Update all unit and integration tests to reflect the new parameter name
- Add container_dns to CONTAINER_OPTION_NAMES in all three core/options.py files

This change provides consistent naming and makes DNS configuration available across all local invocation methods.
The invoke() method signature was missed during the initial rename.
This caused a TypeError when calling invoke with container_dns parameter.

Fixed by renaming:
- Parameter from dns to container_dns in invoke() signature
- Parameter in docstring
- Usage in create() and run() method calls
When using --warm-containers EAGER mode, containers are pre-created
during service startup in _initialize_all_functions_containers().
This initialization was missing the container_dns parameter, causing
DNS settings to not be applied to eagerly-created containers.

Fixed by adding container_dns=self._container_dns to the runtime.run()
call in the initialize_function_container() function.
Add integration tests for sam local invoke and sam local start-api to verify
--container-dns option is properly wired through and DNS configuration is
applied to containers.

- test_invoke_dns.py: Tests for sam local invoke with --container-dns
- test_start_api_dns.py: Tests for sam local start-api with --container-dns

Both tests verify that:
1. Commands accept the --container-dns option
2. Functions execute successfully with custom DNS servers
3. DNS configuration is actually applied to Docker containers
Add integration tests for sam local invoke and sam local start-api to verify
--container-dns option is properly wired through and DNS configuration is
applied to containers.

- test_invoke_dns.py: Tests for sam local invoke with --container-dns
  - Verifies command accepts multiple DNS servers
  - Polls for containers during 10-second sleep to inspect DNS config

- test_start_api_dns.py: Tests for sam local start-api with --container-dns
  - Verifies API requests succeed with custom DNS
  - Inspects container DNS configuration after invocation

Both tests verify DNS settings are actually applied to Docker containers
by inspecting HostConfig.Dns in running containers.
- Remove unnecessary inline comments from test files
- Replace polling with fixed 7-second wait in invoke DNS test
- Update test_invoke_accepts_multiple_dns_servers to use HelloWorldServerlessFunction instead of TimeoutFunctionWithParameter
- Remove redundant comments that don't add value to code understanding
Merges all changes from feat/add-dns-option including:
- Rename --dns to --container-dns for consistency
- Add --container-dns support for all three local commands (invoke, start-api, start-lambda)
- Add comprehensive integration and unit tests
- Fix type annotations and parameter passing throughout the stack

@valerena valerena left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but let's update the title of the PR before merging so we get the right parameter name in the title.

@KandarpAjvalia KandarpAjvalia changed the title feat: Add --dns option to sam local start-lambda command feat: Add --dns option to sam local invoke,start-api, and start-lambda commands Apr 1, 2026
@KandarpAjvalia

Copy link
Copy Markdown
Contributor Author

LGTM, but let's update the title of the PR before merging so we get the right parameter name in the title.

updated 👍🏼

@KandarpAjvalia KandarpAjvalia changed the title feat: Add --dns option to sam local invoke,start-api, and start-lambda commands feat: Add --container-dns option to sam local invoke,start-api, and start-lambda commands Apr 1, 2026
@reedham-aws reedham-aws added this pull request to the merge queue Apr 2, 2026
Merged via the queue into aws:develop with commit 2f93a01 Apr 2, 2026
44 checks passed
@roger-zhangg

Copy link
Copy Markdown
Member

Hi @KandarpAjvalia there were 3 dns related integration test failing last night. Do you mind to take a look? Thanks
https://github.com/aws/aws-sam-cli/actions/runs/23933074527

tests/integration/local/start_api/test_start_api_dns.py::TestStartApiWithDNS::test_dns_configured_in_container
tests/integration/local/invoke/test_invoke_dns.py::TestInvokeWithDNS::test_invoke_accepts_multiple_dns_servers
tests/integration/local/start_lambda/test_start_lambda_dns.py::TestStartLambdaWithDNS::test_dns_configured_in_container

@KandarpAjvalia

Copy link
Copy Markdown
Contributor Author

KandarpAjvalia pushed a commit to KandarpAjvalia/aws-sam-cli that referenced this pull request Apr 3, 2026
The DNS container inspection tests were failing because Lambda containers
exit immediately after the handler completes, making inspection impossible.

Changes:
- test_invoke_dns.py: Use WriteToStdoutFunction instead of HelloWorldServerlessFunction
  to avoid KeyError when no_event=True is passed
- test_start_api_dns.py: Use threading with /sleepfortenseconds endpoint to keep
  container alive during inspection
- test_start_lambda_dns.py: Use threading with HelloWorldSleepFunction to keep
  container alive during inspection

All tests now use long-running functions (10+ seconds) with async threading
pattern, allowing enough time to inspect running containers before they exit.

Fixes tests that were failing after aws#8878 was merged.
github-merge-queue Bot pushed a commit that referenced this pull request Apr 3, 2026
…8889)

* fix: fix failing DNS integration tests by using long-running functions

The DNS container inspection tests were failing because Lambda containers
exit immediately after the handler completes, making inspection impossible.

Changes:
- test_invoke_dns.py: Use WriteToStdoutFunction instead of HelloWorldServerlessFunction
  to avoid KeyError when no_event=True is passed
- test_start_api_dns.py: Use threading with /sleepfortenseconds endpoint to keep
  container alive during inspection
- test_start_lambda_dns.py: Use threading with HelloWorldSleepFunction to keep
  container alive during inspection

All tests now use long-running functions (10+ seconds) with async threading
pattern, allowing enough time to inspect running containers before they exit.

Fixes tests that were failing after #8878 was merged.

* fix: black formatting

---------

Co-authored-by: Kandarp Ajvalia <ajvalia@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/local/invoke sam local invoke command area/local/start-api sam local start-api command area/local/start-invoke area/schema JSON schema file pr/external stage/needs-triage Automatically applied to new issues and PRs, indicating they haven't been looked at.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants