Add --image and --entrypoint params to containerapp debug command

[khkh-ms]

Allow customers to specify a custom container image and entrypoint for the debug ephemeral container via az containerapp debug.

• Add --image and --entrypoint optional parameters
• Append customDebugImageName and customDebugImageEntrypointCommand query params to the debug URL when provided
• Client-side validation in validate_debug: --entrypoint requires --image; --image/--entrypoint require --command (interactive custom-image debug not yet supported server-side)
• Add help examples for the new parameters
• Bump containerapp extension VERSION to 1.3.0b5 + HISTORY.rst entry

Testing

Unit tests — src/containerapp/azext_containerapp/tests/latest/test_containerapp_debug_unit.py (12 tests, all pass):

Suite	Coverage
TestDebugCommandUrlBuilding (4)	URL with neither / image-only / image+entrypoint / special-character URL-encoding
TestDebugCommandValidation (4)	Decorator getter methods + happy-path execution with/without custom params
TestValidateDebugCustomImageRequiresCommand (4)	validate_debug: image without command raises, entrypoint without command raises, image+command passes, entrypoint without image raises (new)

Run locally:

cd src/containerapp
PYTHONPATH=$PWD python -m unittest azext_containerapp.tests.latest.test_containerapp_debug_unit -v

Result: Ran 12 tests in 0.008s — OK.

End-to-end (live) — verified against a real Container App (ca-debug-test-app in ca-debug-test-rg, eastus, sub 2819c8c8-...):

1. Built the dev extension wheel from this branch and ran:

   az containerapp debug -g ca-debug-test-rg -n ca-debug-test-app \
     --image mcr.microsoft.com/devcontainers/python:3.12 \
     --entrypoint '/bin/bash -c "sleep infinity"' \
     --command '/bin/bash'
   

2. Captured the outbound request in browser DevTools (when paired with the matching portal change) and via az --debug log.
3. Confirmed the WebSocket request URL contains both encoded params:

   ...customDebugImageName=mcr.microsoft.com%2Fdevcontainers%2Fpython%3A3.12
      &customDebugImageEntrypointCommand=%2Fbin%2Fbash+-c+%22sleep+infinity%22
   

4. Server returned HTTP 101 Switching Protocols and the debug session attached successfully into the custom image.

Validation negative cases verified manually:

• --entrypoint X without --image → ValidationError: --entrypoint requires --image to also be specified.
• --image X without --command → ValidationError: --image and --entrypoint are only supported with --command. Interactive mode with custom images is not yet supported.

---

This checklist is used to make sure that common guidelines for a pull request are followed.

Related command

az containerapp debug

General Guidelines

• Have you run azdev style <YOUR_EXT> locally? (pip install azdev required)
• Have you run python scripts/ci/test_index.py -q locally? (pip install wheel==0.30.0 required)
• My extension version conforms to the Extension version schema

For new extensions:

• My extension description/summary conforms to the Extension Summary Guidelines.

About Extension Publish

There is a pipeline to automatically build, upload and publish extension wheels.
Once your pull request is merged into main branch, a new pull request will be created to update src/index.json automatically.
You only need to update the version information in file setup.py and historical information in file HISTORY.rst in your PR but do not modify src/index.json.

[azure-client-tools-bot-prd]

Hi @khkh-ms,
Please write the description of changes which can be perceived by customers into HISTORY.rst.
If you want to release a new extension version, please update the version in setup.py as well.

[azure-client-tools-bot-prd]

Validation for Breaking Change Starting...

Thanks for your contribution!

[yonzhan]

Thank you for your contribution! We will review the pull request and get back to you soon.

[github-actions]

The git hooks are available for azure-cli and azure-cli-extensions repos. They could help you run required checks before creating the PR.

Please sync the latest code with latest dev branch (for azure-cli) or main branch (for azure-cli-extensions).
After that please run the following commands to enable git hooks:

pip install azdev --upgrade
azdev setup -c <your azure-cli repo path> -r <your azure-cli-extensions repo path>

[github-actions]

• For more info about extension versioning, please refer to Extension version schema

[Copilot]

Pull request overview

This PR aims to extend az containerapp debug so users can customize the debug ephemeral container by specifying a container image (--image) and an entrypoint (--entrypoint). This is implemented by adding new CLI arguments and (when provided) appending corresponding query parameters to the debug endpoint URL.

Changes:

• Added --image and --entrypoint optional parameters to containerapp debug.
• Updated debug URL construction to include customDebugImageName and customDebugImageEntrypointCommand query params when set.
• Added client-side validation that --entrypoint requires --image, plus new help examples.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/containerapp/azext_containerapp/containerapp_debug_command_decorator.py	Adds new argument accessors, appends custom image/entrypoint query params, and introduces entrypoint/image validation.
src/containerapp/azext_containerapp/_params.py	Registers the new --image / --entrypoint CLI arguments for containerapp debug.
src/containerapp/azext_containerapp/_help.py	Adds usage examples demonstrating --image and --entrypoint.

Comments suppressed due to low confidence (1)

src/containerapp/azext_containerapp/containerapp_debug_command_decorator.py:99

• Validation for --entrypoint requiring --image is implemented inside execute_Command, but this method is only used for the non-interactive --command flow. Once the new args are wired through, the interactive debug console path (WebSocket) would bypass this check. Consider moving this validation into validate_arguments and/or the command validator (validate_debug) so it applies consistently for both interactive and non-interactive debug.

        custom_debug_image_name = self.get_argument_custom_debug_image_name()
        custom_debug_image_entrypoint_command = self.get_argument_custom_debug_image_entrypoint_command()
        if custom_debug_image_entrypoint_command and not custom_debug_image_name:
            raise ValidationError("--entrypoint requires --image to also be specified.")
        url = self._get_url(cmd, resource_group_name, container_app_name, revision_name, replica_name, container_name, command, custom_debug_image_name, custom_debug_image_entrypoint_command)

[khkh-ms]

Addressed in commit acf432b: containerapp_debug(...) in custom.py now accepts custom_debug_image_name and custom_debug_image_entrypoint_command and forwards them via raw_parameters into ContainerAppDebugCommandDecorator. Verified end-to-end (WebSocket request URL contains both encoded params; server returns HTTP 101).

[khkh-ms]

Addressed in commit acf432b: containerapp_debug(...) in custom.py now accepts custom_debug_image_name and custom_debug_image_entrypoint_command and forwards them via raw_parameters into ContainerAppDebugCommandDecorator. Verified end-to-end (WebSocket request URL contains both encoded params; server returns HTTP 101).

[khkh-ms]

Addressed in commit b978fd8: added unit tests in tests/latest/test_containerapp_debug_unit.py covering URL building (4), command-decorator behavior (4), and the validate_debug validator (4) including the new test_entrypoint_without_image_raises failure case. All 12 unit tests pass locally. Happy to add a recorded test_containerapp_scenario.py case as well if preferred over unit-level coverage.

[khkh-ms]

Addressed in commit b978fd8: added unit tests in tests/latest/test_containerapp_debug_unit.py covering URL building (4), command-decorator behavior (4), and the validate_debug validator (4) including the new test_entrypoint_without_image_raises failure case. All 12 unit tests pass locally. Happy to add a recorded test_containerapp_scenario.py case as well if preferred over unit-level coverage.

[khkh-ms]

Thanks for the review! Pushed b978fd88 addressing all feedback.

Bot — HISTORY.rst + version bump

• Bumped VERSION to 1.3.0b5 in src/containerapp/setup.py
• Added 1.3.0b5 entry to src/containerapp/HISTORY.rst describing the new --image / --entrypoint parameters

Copilot summary — move --entrypoint requires --image into validate_debug
Good catch. Moved the check from execute_Command (HTTP-only path) into validate_debug in _validators.py so it runs as a CLI-level validator and applies consistently to both the non-interactive (--command) and interactive WebSocket paths. (Today the same validator also blocks --image/--entrypoint without --command since interactive custom-image debug is not yet supported server-side.)

Copilot inline — containerapp_debug signature missing new args
Already plumbed through in commit acf432bc: containerapp_debug(...) in custom.py now accepts custom_debug_image_name and custom_debug_image_entrypoint_command and forwards them via raw_parameters into ContainerAppDebugCommandDecorator. Confirmed end-to-end (WebSocket request URL contains both encoded params; server returns HTTP 101).

Copilot inline — add tests for new flags + failure case
Added/updated unit tests in tests/latest/test_containerapp_debug_unit.py: 12 tests across URL building, command-decorator behavior, and validate_debug (including the new test_entrypoint_without_image_raises). All pass locally. Happy to add a recorded test_containerapp_scenario.py case as well if preferred.