From 09c297f1ac2b21da1a2a21e2bee5dabc211e2006 Mon Sep 17 00:00:00 2001 From: Jordan Selig Date: Wed, 25 Mar 2026 21:17:50 -0400 Subject: [PATCH 1/4] [App Service] Improve az webapp deploy parameter documentation (#29759, #29758, #29561, #30110) - Add default timeout value to --timeout help text - Clarify --acr-use-identity default behavior - Document --track-status behavior and parameter relationships - Add more examples to az webapp deploy help (URL deploy, slots, --clean) Fixes #29759 Fixes #29758 Fixes #29561 Fixes #30110 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/command_modules/appservice/_help.py | 23 +++++++++++++++---- .../cli/command_modules/appservice/_params.py | 8 +++---- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_help.py b/src/azure-cli/azure/cli/command_modules/appservice/_help.py index e0dad92e98c..64a104dcc95 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_help.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_help.py @@ -3287,9 +3287,24 @@ helps['webapp deploy'] = """ type: command short-summary: Deploys a provided artifact to Azure Web Apps. + long-summary: | + Supports deploying from local files (--src-path) or remote URLs (--src-url). + When --track-status is enabled (the default for Linux web apps), the command monitors + application startup after deployment by polling health endpoints. If the app fails to + start within the expected window, the command returns a non-zero exit code. Use + --async false together with --track-status true to wait for full deployment completion + before tracking begins. examples: - - name: Deploy a war file asynchronously. - text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path SourcePath --type war --async true - - name: Deploy a static text file to wwwroot/staticfiles/test.txt - text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path SourcePath --type static --target-path staticfiles/test.txt + - name: Deploy a war file asynchronously from local path. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.war --type war --async true + - name: Deploy a zip file from a remote URL. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-url https://example.com/app.zip + - name: Deploy without cleaning the target directory. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.zip --clean false + - name: Deploy with runtime status tracking for Linux web app. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.zip --track-status true --async false + - name: Deploy to a specific slot. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.jar --type jar --slot staging + - name: Deploy a static text file to a custom path. + text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path file.txt --type static --target-path staticfiles/file.txt """ diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_params.py b/src/azure-cli/azure/cli/command_modules/appservice/_params.py index bd4dc0b7ea5..a7003d1ca15 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_params.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_params.py @@ -591,7 +591,7 @@ def load_arguments(self, _): c.ignore('reserved_instance_count') c.argument('runtime', help="Canonicalized web runtime in the format of Framework:Version, e.g. \"PHP:7.2\"." "Use `az webapp list-runtimes` for available list") - c.argument('acr_use_identity', arg_type=get_three_state_flag(return_label=True), help="Enable or disable pull image from acr use managed identity") + c.argument('acr_use_identity', arg_type=get_three_state_flag(return_label=True), help="If not specified, managed identity will not be used for ACR image pull.") c.argument('acr_identity', help="Accept system or user assigned identity which will be set for acr image pull. " "Use \'[system]\' to refer system assigned identity, or a resource id to refer user assigned identity.") c.argument('java_version', @@ -1007,9 +1007,9 @@ def load_arguments(self, _): c.argument('clean', help='If true, cleans the target directory prior to deploying the file(s). Default value is determined based on artifact type.', arg_type=get_three_state_flag()) c.argument('ignore_stack', help='If true, any stack-specific defaults are ignored.', arg_type=get_three_state_flag()) c.argument('reset', help='Reset Java apps to the default parking page if set to true with no type specified.', arg_type=get_three_state_flag()) - c.argument('timeout', type=int, help='Timeout for the deployment operation in milliseconds. Ignored when using "--src-url" since synchronous deployments are not yet supported when using "--src-url"') - c.argument('slot', help="The name of the slot. Default to the productions slot if not specified.") - c.argument('track_status', help="If true, web app startup status during deployment will be tracked for linux web apps.", + c.argument('timeout', type=int, help='Timeout for the deployment operation in milliseconds. Default: 900000 (15 minutes). Ignored when using "--src-url".') + c.argument('slot', help="The name of the slot. Default to the production slot if not specified.") + c.argument('track_status', help="If not specified, the command will track app startup and runtime health. Default: true.", arg_type=get_three_state_flag()) c.argument('enable_kudu_warmup', help="If true, kudu will be warmed up before performing deployment for a linux webapp.", arg_type=get_three_state_flag()) From 7ec55877da7c9f07bc446855eef27d39d45867da Mon Sep 17 00:00:00 2001 From: Jordan Selig Date: Thu, 26 Mar 2026 10:22:53 -0400 Subject: [PATCH 2/4] docs: add connection string env var prefix docs (#21129) Document the App Service environment variable prefixes for each connection string type (SQLAZURECONNSTR_, POSTGRESQLCONNSTR_, etc.) and note that .NET GetConnectionString() only auto-maps SQL/Custom prefixes. Users with PostgreSQL/MySQL must read the env var directly. Updates _help.py long-summary and adds PostgreSQL example. Updates _params.py --connection-string-type help text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/command_modules/appservice/_help.py | 23 ++++++++++++++++++- .../cli/command_modules/appservice/_params.py | 6 ++++- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_help.py b/src/azure-cli/azure/cli/command_modules/appservice/_help.py index 64a104dcc95..57e95ab1624 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_help.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_help.py @@ -1578,12 +1578,33 @@ helps['webapp config connection-string set'] = """ type: command short-summary: Update a web app's connection strings. -long-summary: Note that connection string values are now redacted in the result. Please use the `az webapp config connection-string list` command to view the values. +long-summary: > + Note that connection string values are now redacted in the result. Please use the + `az webapp config connection-string list` command to view the values. + + + App Service exposes each connection string as an environment variable with a type-based + prefix: + SQLServer → SQLCONNSTR_ + SQLAzure → SQLAZURECONNSTR_ + MySQL → MYSQLCONNSTR_ + PostgreSQL → POSTGRESQLCONNSTR_ + Custom → CUSTOMCONNSTR_ + + + .NET's Configuration.GetConnectionString() auto-maps only the SQLServer, SQLAzure, and + Custom prefixes. For MySQL and PostgreSQL connection strings, access the value directly + via Configuration["MYSQLCONNSTR_"] or Configuration["POSTGRESQLCONNSTR_"] + instead. examples: - name: Add a mysql connection string. text: > az webapp config connection-string set -g MyResourceGroup -n MyUniqueApp -t mysql \\ --settings mysql1='Server=myServer;Database=myDB;Uid=myUser;Pwd=myPwd;' + - name: Add a PostgreSQL connection string (access in .NET via Configuration["POSTGRESQLCONNSTR_pg1"]). + text: > + az webapp config connection-string set -g MyResourceGroup -n MyUniqueApp -t postgresql \\ + --settings pg1='Host=myHost;Database=myDB;Username=myUser;Password=myPwd;' """ helps['webapp config container'] = """ diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_params.py b/src/azure-cli/azure/cli/command_modules/appservice/_params.py index a7003d1ca15..31933f9c0b5 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_params.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_params.py @@ -794,7 +794,11 @@ def load_arguments(self, _): with self.argument_context('webapp config connection-string') as c: c.argument('connection_string_type', options_list=['--connection-string-type', '-t'], - help='connection string type', arg_type=get_enum_type(ConnectionStringType)) + help='Connection string type. App Service sets an env var prefix per type ' + '(e.g., SQLAZURECONNSTR_, POSTGRESQLCONNSTR_). .NET GetConnectionString() ' + 'auto-maps SQLServer, SQLAzure, and Custom only; for MySQL/PostgreSQL, ' + 'read the env var directly.', + arg_type=get_enum_type(ConnectionStringType)) c.argument('ids', options_list=['--ids'], help="One or more resource IDs (space delimited). If provided no other 'Resource Id' arguments should be specified.", required=True) From 2a29e3e863972fff246b02eff99f29fb2de1ae81 Mon Sep 17 00:00:00 2001 From: Jordan Selig Date: Thu, 26 Mar 2026 10:45:57 -0400 Subject: [PATCH 3/4] [App Service] Fix #30336, #29761: Improve --scope and --linux-fx-version help text and examples - Add --scope example to webapp create help showing managed identity assignment - Update --linux-fx-version help with RUNTIME|VERSION format and current runtime examples - Add --linux-fx-version examples to webapp config set help for Python, Node, .NET Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../azure/cli/command_modules/appservice/_help.py | 12 ++++++++++++ .../azure/cli/command_modules/appservice/_params.py | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_help.py b/src/azure-cli/azure/cli/command_modules/appservice/_help.py index 57e95ab1624..6c76e16264e 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_help.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_help.py @@ -1686,6 +1686,15 @@ - name: set configuration through a JSON file called params.json text: > az webapp config set -g MyResourceGroup -n MyUniqueApp --generic-configurations "@.\\params.json" + - name: Set the linux runtime stack to Python 3.11 (format is RUNTIME|VERSION). + text: > + az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "PYTHON|3.11" + - name: Set the linux runtime stack to Node.js 18 LTS. + text: > + az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "NODE|18-lts" + - name: Set the linux runtime stack to .NET 8.0. + text: > + az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "DOTNETCORE|8.0" """ @@ -1931,6 +1940,9 @@ - name: Create a web app with end-to-end encryption enabled and minimum TLS version 1.2 text: > az webapp create -g MyResourceGroup -p MyPlan -n MyUniqueAppName --end-to-end-encryption-enabled true --min-tls-version 1.2 + - name: Create a web app with a system-assigned managed identity and grant it access to a storage account. + text: > + az webapp create -g MyResourceGroup -p MyPlan -n MyUniqueAppName --assign-identity [system] --scope /subscriptions/{subscription}/resourceGroups/{resourceGroup}/providers/Microsoft.Storage/storageAccounts/{storageAccount} --role Contributor """ helps['webapp create-remote-connection'] = """ diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_params.py b/src/azure-cli/azure/cli/command_modules/appservice/_params.py index 31933f9c0b5..602184b6126 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_params.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_params.py @@ -581,7 +581,7 @@ def load_arguments(self, _): c.argument('power_shell_version', help='The version used to run your function app if using PowerShell, e.g., 7.2', options_list=['--powershell-version']) c.argument('python_version', help='The version used to run your web app if using Python, e.g., 2.7, 3.4') c.argument('net_framework_version', help="The version used to run your web app if using .NET Framework, e.g., 'v4.0' for .NET 4.6 and 'v3.0' for .NET 3.5") - c.argument('linux_fx_version', help="The runtime stack used for your linux-based webapp, e.g., \"RUBY|2.5.5\", \"NODE|12LTS\", \"PHP|7.2\", \"DOTNETCORE|2.1\". See https://aka.ms/linux-stacks for more info.") + c.argument('linux_fx_version', help="The runtime stack used for your linux-based webapp, in the format 'RUNTIME|VERSION'. Common examples: \"PYTHON|3.11\", \"NODE|18-lts\", \"DOTNETCORE|8.0\", \"JAVA|17-java17\", \"PHP|8.2\". Use `az webapp list-runtimes --os linux` to see all supported values. See https://aka.ms/linux-stacks for more info.") c.argument('windows_fx_version', help="A docker image name used for your windows container web app, e.g., microsoft/nanoserver:ltsc2016") if scope == 'functionapp': c.ignore('windows_fx_version') From c847509bbde8397b99c2a4764f7e20fd11841298 Mon Sep 17 00:00:00 2001 From: Jordan Selig Date: Thu, 26 Mar 2026 15:19:48 -0400 Subject: [PATCH 4/4] fix: wrap placeholders in backticks to pass disallowed_html_tag linter rule The CLI linter flags bare as a disallowed HTML tag in help text. Wrapping SQLCONNSTR_ and similar patterns in backticks fixes the disallowed_html_tag_from_command HIGH severity violation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../azure/cli/command_modules/appservice/_help.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_help.py b/src/azure-cli/azure/cli/command_modules/appservice/_help.py index 6c76e16264e..6544c364247 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_help.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_help.py @@ -1585,16 +1585,16 @@ App Service exposes each connection string as an environment variable with a type-based prefix: - SQLServer → SQLCONNSTR_ - SQLAzure → SQLAZURECONNSTR_ - MySQL → MYSQLCONNSTR_ - PostgreSQL → POSTGRESQLCONNSTR_ - Custom → CUSTOMCONNSTR_ + SQLServer → `SQLCONNSTR_` + SQLAzure → `SQLAZURECONNSTR_` + MySQL → `MYSQLCONNSTR_` + PostgreSQL → `POSTGRESQLCONNSTR_` + Custom → `CUSTOMCONNSTR_` .NET's Configuration.GetConnectionString() auto-maps only the SQLServer, SQLAzure, and Custom prefixes. For MySQL and PostgreSQL connection strings, access the value directly - via Configuration["MYSQLCONNSTR_"] or Configuration["POSTGRESQLCONNSTR_"] + via `Configuration["MYSQLCONNSTR_"]` or `Configuration["POSTGRESQLCONNSTR_"]` instead. examples: - name: Add a mysql connection string.